Modernization

Migrate to modern .NET without putting your business on hold.

Keep customers working. Keep shipping features and improvements. Roll out gradually, with a tested path back to legacy.

Published · AI disclosure

Keep the business moving

  • Protect live customer workflows
  • Switch traffic back when the new implementation fails
  • Keep shipping new features
  • Keep improving the existing product

Build the migration around these requirements. Move one feature at a time, establish its business behavior, and control its release before taking on the next feature.

1. Choose one feature

Capture the feature in Jira. Define its acceptance criteria, business rules, permissions, data, and dependencies. Agree what will move to ASP.NET Core and what will remain in ASP.NET on .NET Framework.

For a reporting feature, that may include filters, saved reports, and export. Give the team a clear boundary and an agreed definition of success.

The feature is now described on paper. But the new code will be a different implementation. How will you know it still meets those requirements?

2. Establish the business baseline before migrating

Automate the acceptance criteria against the legacy feature first. Use Playwright for customer-visible behavior and integration tests for the business behavior behind it. Verify the results of representative requests, including permissions, calculations, saved data, and expected side effects. A successful HTTP response alone is insufficient. [1]

Use controlled test data and isolated state for operations that make changes. Once these checks pass against the legacy implementation, you have an executable baseline.

Example: check the same reporting result in legacy and Core

In this illustrative fixture, the signed-in test account can see exactly sale-a and sale-b for September 2026, totaling USD 125.00. Keep those business assertions fixed when changing the target application.

Use the playwright package and its playwright/test entry point. Set TARGET_BASE_URL to the legacy test application’s base URL, including its application path and a trailing slash. TEST_STORAGE_STATE names a private Playwright state file containing valid test-account cookies for that target. Token-based APIs need explicit authorization headers instead; browser storage tokens are not automatically sent as API headers.

playwright.config.cjs
const { defineConfig } = require('playwright/test');
const { TARGET_BASE_URL, TEST_STORAGE_STATE } = process.env;

if (!TARGET_BASE_URL?.endsWith('/') || !TEST_STORAGE_STATE) {
  throw new Error('Set a test base URL ending in / and its test-account state.');
}

module.exports = defineConfig({
  testDir: './acceptance',
  retries: 0,
  use: { baseURL: TARGET_BASE_URL, storageState: TEST_STORAGE_STATE },
});
acceptance/report.spec.cjs
const { test, expect } = require('playwright/test');

test('September report contains the agreed sales and total', async ({ request }) => {
  const response = await request.get('api/reports/sales', {
    params: { month: '2026-09' },
    maxRedirects: 0,
  });
  expect(response.status()).toBe(200);
  const report = await response.json();
  expect(report.currency).toBe('USD');
  expect(report.totalMinor).toBe(12500);
  expect(report.rows.map(row => row.id).sort()).toEqual(['sale-a', 'sale-b']);
});

Run the suite against the seeded legacy test environment first. After migrating, change only the test base URL and target-specific test-account state, then run it against Core. The relative request path preserves an application path in the base URL. Disabling redirect following lets the status assertion catch a login redirect instead of mistaking its final page for a successful report.

This example verifies the response status, currency, total, and exact row IDs for one fixture. Add the feature’s other acceptance scenarios and browser tests; this single response check does not establish permissions, UI behavior, or complete parity. Keep the authentication state file out of source control.

JavaScript syntax checks, Playwright configuration/test discovery, and isolated assertion checks passed. No application endpoints, browser sessions, or k6 load run were exercised.

Now migrate the implementation and run the same suite against Core. Does it still pass? That is where confidence comes from: the technology changed; the tested business behavior stayed intact.

Investigate differences. Keep business redesign separate from this migration rather than changing expectations merely to make the new code pass.

3. Check performance before production

The acceptance tests pass. Will the feature still respond well when many customers use it at once?

Use Grafana k6 to compare the legacy and Core implementations under comparable conditions: the same representative workload, data, and infrastructure capacity. Measure response times, throughput, and error rates. Set pass/fail thresholds against the feature’s performance requirements and investigate regressions before release. [2]

Example: make the agreed performance limits fail the load test

Add this options fragment to the feature’s existing k6 script. That script must already exercise the authenticated feature under a representative workload and record a business-result check on every iteration. Supply MAX_P95_MS in milliseconds and MAX_ERROR_RATE as a fraction, such as 0.01 for one percent. Choose the values from the feature’s requirements.

Options fragment in the feature’s k6 script
const p95Ms = Number(__ENV.MAX_P95_MS);
const maxErrorRate = Number(__ENV.MAX_ERROR_RATE);

if (!Number.isFinite(p95Ms) || p95Ms <= 0 ||
    !__ENV.MAX_ERROR_RATE?.trim() || !Number.isFinite(maxErrorRate) ||
    maxErrorRate < 0 || maxErrorRate > 1) {
  throw new Error('Supply an agreed positive p95 limit and error rate from 0 to 1.');
}

export const options = {
  thresholds: {
    http_req_duration: [`p(95)<=${p95Ms}`],
    http_req_failed: [`rate<=${maxErrorRate}`],
    checks: ['rate==1'],
  },
};

The latency and HTTP-error limits apply to the requests in this script. The checks threshold also fails the run when any recorded business check fails. An incorrect report returned with HTTP 200 is still incorrect; HTTP failure metrics alone will not identify it. Use a feature-specific script here, or tag and scope thresholds when combining several features.

This fragment does not generate traffic. Keep the same workload and limits when comparing legacy and Core. k6’s default expected HTTP statuses include 200–399, so the scenario must check authentication and the business response rather than relying only on http_req_failed.

The JavaScript guards and threshold object were checked in isolation. No k6 load run was executed.

Those numbers establish how the feature performed under the tested conditions. The next step is to control its exposure to real customers.

4. Release behind a migration flag

Use Core as the public entry point, with YARP (Yet Another Reverse Proxy) forwarding requests to Framework for features that remain there. Verify existing customer journeys through the proxy before enabling the migrated feature. [3]

Connect a feature flag in the Core codebase to route selection:

  • Disabled: exclude the Core route so YARP forwards these requests to Framework
  • Enabled for a selected group: Core handles those requests

This conditional routing must be implemented explicitly; deploying a Core endpoint does not make it flag-controlled. [4]

Start with a small, identified customer group. Keep related requests on the intended version, using trusted customer context. Watch production behavior and collect feedback before expanding exposure. [5]

Test the return path too. Framework must be able to read data written by Core. An incompatible saved-report format can break the old feature even after traffic switches back. Rehearse the flag change, including its propagation across instances. It redirects subsequent requests; it does not undo writes or cancel work already running. [6]

5. Decide how long both versions stay

What happens when the legacy feature needs a bug fix or enhancement during migration? And how long will the team maintain both versions?

Keep work with the implementation serving that feature. Features outside the migration continue receiving new capabilities and improvements in Framework. Features already migrated develop in Core, subject to any remaining rollback requirements.

During the overlap, update acceptance criteria and tests when an approved fix or enhancement changes business behavior. Carry that change into both implementations where necessary. Do not automatically duplicate every backlog item.

As customer feedback and production results build confidence, expand the rollout. Agree a retirement timeline and exit criteria. Once those criteria are met and remaining callers have been checked, close the rollback period and remove the old feature implementation and migration flag. Future fixes and enhancements for that feature then happen only in Core.

Finish against the original requirements

The completed feature migration should demonstrate:

  • Business behavior verified by the acceptance suite
  • Performance measured before release and observed in production
  • A tested return path throughout the agreed rollback period
  • Continued feature delivery and enhancements, with temporary dual maintenance ended

You own the budget, priorities, and decision to retire the legacy feature. Fund those decisions explicitly rather than leaving two implementations in place indefinitely.

Apply this playbook to your next feature. If you need development and QA capacity to carry it out, Mottobits can work with your team on the implementation, testing, and rollout.

Discuss your modernization team

Sources

Written with AI and not reviewed by a human. It may contain mistakes.