Modernize .NET and SQL without losing the business

The application is not the whole system

A mature line-of-business system is an operating environment, not merely a code repository.

Important behavior can be found in:

• C#, VB.NET, Classic ASP, JavaScript, and client-side validation
• ASP.NET Web Forms page events and state behavior
• SQL Server stored procedures, triggers, functions, and views
• SQL Agent jobs and batch files
• SSIS or other integration packages
• Reports that perform their own calculations
• Configuration tables and feature flags
• Manual data corrections
• Email-based approvals
• Spreadsheet reconciliations
• Vendor file formats and undocumented API expectations
• Operational sequences known only to experienced staff

A source-code conversion can preserve syntax while losing this wider system behavior. Conversely, some current behavior may be a defect that should not be preserved.

Modernization therefore begins with a question: What business result does the organization actually rely on?

Observed behavior is not automatically intended policy

When the current system and written policy disagree, neither should be silently declared correct.

Use explicit categories:

• Known and intended: supported by current policy and operational evidence
• Known but accidental: a defect or workaround the organization wants to remove
• Observed but unconfirmed: current behavior without authoritative intent
• Disputed: stakeholders or sources disagree
• Unknown: evidence is insufficient
• Retired: behavior no longer required
• New: an intentional capability added during modernization

This classification prevents two common mistakes:

1. Treating every existing output as sacred behavior
2. Treating every written requirement as if the system has always followed it

Domain owners must resolve the difference where possible. Where they cannot, the uncertainty belongs in a decision and risk register.

Characterization tests create a baseline

A characterization test records what the current system does for a representative input. It is especially useful when the original code is difficult to understand or when rules are distributed across layers.

A parity catalog should include more than happy paths:

• Common transactions
• Boundary dates and threshold values
• Null, missing, malformed, and duplicate data
• Permission and role variations
• Reversals, cancellations, and adjustments
• Historical records created under older rules
• Integration failures and retries
• Report totals and reconciliation points
• Performance-sensitive volume cases
• Manual exception paths

The expected result may initially be "match the current system" rather than "match a written formula." That is acceptable as long as the test is labeled as observed behavior rather than policy truth.

Golden datasets and reconciliation

For data-heavy systems, create a set of representative records and expected outputs. The dataset should be versioned and tied to source state.

Useful comparison levels include:

• Field-by-field result comparison
• Aggregated totals
• Record counts
• State transitions
• Permission outcomes
• Generated document content
• Downstream messages
• Timing and sequence where timing is meaningful

Do not assume that exact equality is always correct. A deliberate rounding change, timestamp normalization, or data-cleaning rule may create expected differences. Record tolerances and approved transformations explicitly.

Reconciliation should produce understandable categories:

• Exact match
• Expected intentional difference
• Unexpected difference
• Missing source evidence
• Comparison not applicable
• Requires domain review

Reversible seams reduce cutover risk

A big-bang rewrite combines too many uncertainties: new framework, new architecture, new data path, new deployment model, and new business behavior.

A reversible seam isolates change. Examples include:

• Route one bounded workflow to a new service while retaining the old path
• Wrap a stored procedure behind an explicit interface before replacing it
• Introduce an API around a stable legacy calculation
• Run old and new calculations in parallel without changing the authoritative result
• Shadow-write to a new data model and reconcile
• Replace one report while retaining the underlying system
• Move authentication or file handling before changing core rules

The seam should define:

• Input and output contract
• Source of truth
• Failure and timeout behavior
• Observability
• Comparison method
• Cutover criteria
• Rollback procedure
• Ownership

Incremental modernization is not inherently safe; a poorly defined seam can spread ambiguity. The value comes from making the boundary testable and reversible.

Modern tools help, but they do not own the business decision

Microsoft's current GitHub Copilot modernization tooling can assess projects, propose plans, apply upgrade transformations, and validate builds and tests. [S1] [S2] This can materially reduce mechanical upgrade work.

The limitation is equally important: automated modernization cannot independently establish the organization's intended business behavior. It can generate code changes and tests, but the team still needs authoritative scenarios, representative data, access rules, operational constraints, and human review.

AI-assisted documentation can help by:

• Summarizing code paths
• Identifying candidate dependencies
• Drafting test cases for review
• Comparing schemas or interfaces
• Producing first-pass architecture notes
• Grouping repeated patterns

It should not:

• Convert an inferred rule into accepted policy
• Invent a missing business requirement
• Mark an undocumented behavior as safe to remove
• Approve a parity difference
• Replace domain-owner review
• Commit a high-risk change without evidence

Generated documentation is proposed work until reviewed against source and system evidence.

Cutover is an operational decision

A modernization cutover should define more than a deployment date.

A decision package normally includes:

• Scope and affected workflows
• Approved parity set
• Known differences
• Unresolved risks
• Data migration and reconciliation status
• Rollback trigger and maximum rollback time
• Support ownership
• Monitoring and alert conditions
• User communication
• Freeze periods and change windows
• Recovery from partial migration
• Evidence-retention requirements

Operational continuity matters because a technically correct new system can still fail through missing support procedures, integration timing, data access, or user workarounds.

Secure-development evidence belongs in the modernization

NIST's SSDF provides a common set of secure-development practices that can be integrated into an organization's software development lifecycle. [S3] A modernization can use that vocabulary to structure source control, dependency review, change protection, verification, release integrity, and vulnerability response without claiming certification.

The key is to make security part of the delivery evidence rather than a final checklist detached from the actual change.

Practical evidence inventory

Current state

• Application and repository inventory
• Runtime and framework versions
• Database objects and jobs
• Integrations and file exchanges
• Reports and document outputs
• Access roles and service accounts
• Deployment and support dependencies
• Known incidents and fragile areas

Behavior

• Business-rule map
• Representative scenarios
• Source traces
• Characterization tests
• Golden datasets
• Reconciliation reports
• Unknown and disputed behavior register

Target state

• Architecture and service seams
• Data ownership and migration strategy
• Interface contracts
• Dependency plan
• Observability and failure behavior
• Security and access boundaries
• Rollback design

Decision

• Intentional change register
• Parity acceptance criteria
• Cutover and rollback criteria
• Named owners
• Risk acceptance or remediation decisions
• Handoff and continuity artifacts

Implementation checklist

• [ ] Inventory code, data, jobs, reports, integrations, configuration, and workarounds.
• [ ] Separate observed behavior from intended policy.
• [ ] Classify known, unknown, disputed, intentional, and accidental behavior.
• [ ] Build representative parity scenarios including negative and exception cases.
• [ ] Version golden datasets and comparison tolerances.
• [ ] Trace critical outputs to source and domain authority.
• [ ] Define reversible seams before replacing core behavior.
• [ ] Run old and new paths in parallel where risk justifies it.
• [ ] Reconcile data, reports, permissions, and downstream messages.
• [ ] Define cutover, rollback, and operational support criteria.
• [ ] Review AI-generated documentation as proposed work.
• [ ] Retain client-owned architecture, evidence, and decision records.

Decision connection

The modernization decision is not simply "Can the code be upgraded?" It is "Can the organization change the technology while preserving, intentionally changing, and proving the behavior that matters?"

The AI-Ready .NET & SQL Modernization Blueprint creates the current-state map, parity plan, reversible sequence, and decision record before implementation begins. The Legacy Modernization Evidence Inventory provides a practical starting checklist.