Skip to Content
Cloud Engineering Academy
3. .NET Application Development on AWS

Porting .NET Framework apps to AWS

Decide whether to rehost, replatform or port a legacy .NET Framework 4.8 banking application, use AWS Transform for .NET and Microsoft's upgrade tooling, fix the classic blockers (System.Web, WCF, configuration, Windows-only APIs), and know when Windows on EC2 or Beanstalk is the right answer.

advanced⏱ 2 h 30 min🟢 FreeSAA-C03DVA-C03

Assumes: .NET Framework 4.8 → .NET 10 LTS · AWS Transform for .NET · AWS SDK for .NET v4 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Classify a legacy .NET application with the migration strategies (rehost, replatform, refactor, retire, retain, repurchase, relocate) and defend a choice on risk, cost and time.
  • Explain what AWS Transform for .NET does, what it supports, how it is accessed, what it costs, and which older AWS tools it replaced.
  • Explain where Microsoft's .NET Upgrade Assistant and its successor fit, and why tool output is a starting point, not a finished port.
  • Recognise and fix the common blockers: System.Web, web.config/ConfigurationManager, WCF servers, Windows-only APIs (registry, event log, System.Drawing), and Windows authentication.
  • Choose a target on AWS: Windows on EC2 or Elastic Beanstalk (IIS) for rehost, Linux containers on ECS Fargate for ported code, and understand the licensing cost difference.

Prerequisites

  • Module 3 overview — hosting options; the Accounts API as the "target shape"
  • Logging and errors, Authentication and authorisation — what modern equivalents look like
  • Familiarity with ASP.NET MVC 5 / Web API 2 / WCF on .NET Framework (you have probably maintained some)
  • Tools for the exercises: .NET 10 SDK or Docker. No AWS account is needed for this lesson.

Why this matters in banking

Harbourline Bank runs about 140 .NET applications. Roughly 60 are still on .NET Framework 4.x: an internal Customer Servicing Portal (ASP.NET MVC 5), a Payments Gateway (WCF over net.tcp and SOAP), batch jobs as Windows Services, and dozens of small Web API 2 services. They run on Windows Server VMs on-premises, with IIS, Windows authentication and SQL Server.

The cloud programme has a deadline: the data-centre lease ends in 18 months. Porting all 60 apps to .NET 10 in that time is unrealistic; leaving them all on Windows VMs in AWS costs a lot in Windows licences and keeps the patching burden. The right answer is a portfolio decision: port some, rehost some, retire some. Engineers who can estimate the effort of a port, run the tools, and fix what the tools can't, are exactly who the bank needs.

The idea in plain language

.NET Framework (1.0–4.8.1) is the original Windows-only .NET. It is still supported as part of Windows, but receives no new features. Modern .NET (.NET Core 1.0 → .NET 5 → … → .NET 10) is cross-platform, faster, and runs on Linux containers.

Many Framework apps cannot simply be recompiled for .NET 10: some libraries do not exist there (System.Web, WCF server, AppDomain isolation, .NET Remoting), and some code relies on Windows (registry, IIS modules, Windows authentication). Porting means changing the code to remove those dependencies.

Rehosting (lift and shift) means moving the app unchanged to a Windows server in AWS. Fast, but you keep Windows licences and the old runtime.

Analogy: moving a bank branch to a new building. Rehosting is moving all the old furniture as-is: quick, but the old filing cabinets still don't fit the new digital system. Porting is refitting the branch: slower, but afterwards it runs on the bank's standard systems and costs less to run. Some branches will close (retire) and some stay where they are for now (retain).

What problem AWS Transform for .NET solves

AWS Transform for .NET (generally available since May 2025) is an agentic AI service that ports .NET Framework applications to cross-platform .NET and upgrades older .NET versions. It replaced the earlier AWS tools: Porting Assistant for .NET, App2Container, the AWS Toolkit for .NET Refactoring and Microservice Extractor for .NET, which closed to new customers on 7 November 2025. Do not build plans on those tools.

What it does, as documented on the verification date:

AspectDetails
Transforms from.NET Framework 3.5 (and 4.x), .NET Core 3.1, .NET 5 and later
Transforms to.NET 8, .NET 10, .NET Standard (class libraries)
LanguagesC#, VB.NET
Project typesClass libraries, console apps, ASP.NET (MVC, Web API, Web Forms), unit test projects (NUnit, xUnit, MSTest), WCF services, desktop (WinForms, WPF), Xamarin, ASMX web services
Source controlConnects to GitHub, GitLab, Bitbucket and Azure Repos; commits results to a new branch, original code untouched
ExperiencesAWS Transform web application (bulk, many repositories), the AWS Toolkit for Visual Studio (interactive, one solution), and AI code companions via an MCP server
ValidationBuilds the transformed code and runs unit tests; produces a transformation report with next steps
Human stepsApprove the plan, supply missing private NuGet packages, review and accept code
CostAWS-managed .NET transformations are free up to a monthly quota of 50,000 agent minutes; the IDE integration has no charge

What it does not do (limitations):

  • Win32 DLLs with no .NET (Core)-compatible equivalent, repositories without a .NET solution, and "Web Site" projects without a project file are not transformed.
  • Web Forms is ported to modern .NET, but rewriting Web Forms UI into, say, React is outside the .NET agent's scope (AWS points to AWS Transform custom for that).
  • It does not make architectural decisions for you: session state, configuration, authentication and logging still need human design (lessons 10–16).
  • AI-generated changes need code review like any other change. In a bank, a port is a change subject to the same testing, segregation of duties and approval as a hand-written one.

Microsoft's tooling

Microsoft's .NET Upgrade Assistant (Visual Studio extension and CLI) analysed projects and applied mechanical upgrades: SDK-style project files, package updates, TargetFramework changes, some API replacements. Microsoft has since deprecated it in favour of the GitHub Copilot app modernization agent in Visual Studio, which requires a paid GitHub Copilot subscription. The deprecated tool can still be enabled in Visual Studio, but is no longer developed ⚠ VERIFY the current status before you rely on either tool.

Other useful, free building blocks:

  • try-convert-style SDK project conversion and the Microsoft.DotNet.UpgradeAssistant analyzers (historical); in practice the modern route is: convert to SDK-style project, multi-target, fix compile errors.
  • Microsoft.Windows.Compatibility package — brings many Windows-only APIs (registry, event log, System.Drawing.Common on Windows) to modern .NET. Useful as a bridge, but it keeps you on Windows.
  • CoreWCF — an open-source, .NET Foundation port of the WCF server to modern .NET. Lets SOAP services keep their contracts.
  • System.Web adapters (Microsoft.AspNetCore.SystemWebAdapters) — support an incremental migration where a new ASP.NET Core app proxies to the old one (the "strangler fig" pattern).

Whichever tool you use: the hard 20% is design, not syntax.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Azure Migrate (discovery, assessment)AWS Transform (assessment and migration agents), AWS Migration EvaluatorAWS Migration Hub and Application Discovery Service closed to new customers in 2025
.NET Upgrade Assistant / Copilot app modernizationAWS Transform for .NETAWS Transform works on whole repository portfolios and commits to branches; IDE integration also available
App Service on Windows (IIS)Elastic Beanstalk "IIS on Windows Server" platform, or EC2 WindowsBeanstalk creates real EC2 instances you can see and pay for (Windows licence included in the price)
App Service on Linux / Container AppsECS on Fargate (Linux), ECS Express ModeLinux Fargate tasks are cheaper than Windows ones and start faster
Azure Hybrid Benefit for Windows ServerBring Your Own License on Dedicated Hosts (restricted), otherwise licence-includedLicence mobility rules for Windows Server changed in 2019; licence-included is the norm on shared tenancy
Managed Instance for SQL ServerAmazon RDS for SQL ServerLicence-included pricing; consider Aurora PostgreSQL / Babelfish only for deeper refactors

Architecture

The decision flow Harbourline uses per application:

Target state for a ported app (the same shape as the module project):

Security boundary view. The legacy app relied on the network perimeter and Windows authentication (Kerberos inside the domain). In AWS, identity moves to OIDC (staff sign in through the corporate IdP), secrets move from web.config to Secrets Manager/Parameter Store, and the app's own permissions become an IAM task role. This is usually the biggest change in a port, and it needs security review.

The classic blockers and their fixes

Legacy (.NET Framework)Modern .NET replacementEffort
System.Web (HttpContext.Current, HttpModule, Global.asax)ASP.NET Core middleware, IHttpContextAccessor, Program.csMedium; mechanical for MVC/Web API controllers, hard for modules
web.config + ConfigurationManager.AppSettingsappsettings.json, environment variables, IOptions<T>, Parameter StoreLow–medium
Connection strings with passwords in web.configSecrets Manager (+ IAM auth where possible)Low, but needs process change
WCF clientSystem.ServiceModel.* packages (client side is supported on modern .NET)Low
WCF serverCoreWCF (keep SOAP contracts) or redesign as REST/gRPCMedium–high
ASP.NET Web FormsNo direct equivalent: Razor Pages/Blazor rewrite, ideally incrementalHigh
Windows authentication (Kerberos/NTLM)OIDC with the corporate IdP; Negotiate auth only if you stay on domain-joined WindowsMedium
Session in-proc / SQL Server session stateIDistributedCache (ElastiCache/DynamoDB) — see Scaling .NET appsLow–medium
System.Drawing for images/PDFsCross-platform libraries (e.g. SkiaSharp, ImageSharp, QuestPDF)Medium
Registry, Event Log, Windows ServicesConfiguration, stdout logs, Worker ServicesLow–medium
AppDomain, .NET Remoting, Code Access SecuritySeparate processes, gRPC/HTTP, OS-level isolationHigh (redesign)
Entity Framework 6EF Core 10 (EF6 also runs on modern .NET, as a bridge)Medium

Before and after: a Harbourline controller

The Customer Servicing Portal has a Web API 2 controller that returns a customer's accounts. A simplified but realistic version:

Before: AccountsController.cs (.NET Framework 4.8, Web API 2)
using System.Configuration;
using System.Data.SqlClient;
using System.Diagnostics;
using System.Web;
using System.Web.Http;

namespace Harbourline.ServicingPortal.Controllers
{
    [Authorize] // Windows authentication via IIS
    public class AccountsController : ApiController
    {
        [HttpGet, Route("api/customers/{customerId}/accounts")]
        public IHttpActionResult Get(string customerId)
        {
            var user = HttpContext.Current.User.Identity.Name;            // DOMAIN\jsmith
            var cs = ConfigurationManager.ConnectionStrings["CoreBanking"].ConnectionString; // password inside
            var accounts = new List<object>();

            using (var conn = new SqlConnection(cs))
            using (var cmd = new SqlCommand(
                "SELECT account_id, currency, balance FROM accounts WHERE customer_id = '" + customerId + "'", conn))
            {
                conn.Open();
                using (var r = cmd.ExecuteReader())
                {
                    while (r.Read())
                        accounts.Add(new { AccountId = r.GetString(0), Currency = r.GetString(1), Balance = r.GetDecimal(2) });
                }
            }

            EventLog.WriteEntry("ServicingPortal", user + " viewed accounts of " + customerId); // audit
            return Ok(accounts);
        }
    }
}

Problems beyond the platform: SQL injection, a password in configuration, a full customer ID in the Windows event log, synchronous I/O, no error contract.

After: AccountsEndpoints.cs (.NET 10, ASP.NET Core minimal API)
using System.Security.Claims;
using Microsoft.Data.SqlClient;

namespace Harbourline.ServicingPortal;

public sealed record AccountSummary(string AccountId, string Currency, decimal Balance);

public static class AccountsEndpoints
{
    public static IEndpointRouteBuilder MapServicingAccounts(this IEndpointRouteBuilder app)
    {
        app.MapGet("/api/customers/{customerId}/accounts", GetAsync)
           .RequireAuthorization("servicing:read");   // OIDC token from the corporate IdP + policy
        return app;
    }

    private static async Task<IResult> GetAsync(
        string customerId,
        ClaimsPrincipal user,
        SqlConnectionFactory connections,
        ILogger<AccountSummary> log,
        CancellationToken ct)
    {
        if (!System.Text.RegularExpressions.Regex.IsMatch(customerId, "^CUS-[0-9]{8}$"))
        {
            return Results.Problem(statusCode: 400, title: "Invalid customer id");
        }

        await using var conn = await connections.OpenAsync(ct);   // password from Secrets Manager
        await using var cmd = new SqlCommand(
            "SELECT account_id, currency, balance FROM accounts WHERE customer_id = @customerId", conn);
        cmd.Parameters.Add(new SqlParameter("@customerId", System.Data.SqlDbType.VarChar, 12) { Value = customerId });

        var accounts = new List<AccountSummary>();
        await using var r = await cmd.ExecuteReaderAsync(ct);
        while (await r.ReadAsync(ct))
        {
            accounts.Add(new AccountSummary(r.GetString(0), r.GetString(1), r.GetDecimal(2)));
        }

        // Structured audit line: staff identity from the token, count only, no customer data in the message.
        log.LogInformation("Servicing view by {StaffId}: {AccountCount} accounts", user.FindFirstValue("sub"), accounts.Count);
        return Results.Ok(accounts);
    }
}

/// <summary>Builds connections from a connection string whose password comes from Secrets Manager.</summary>
public sealed class SqlConnectionFactory(IConfiguration configuration)
{
    public async Task<SqlConnection> OpenAsync(CancellationToken ct)
    {
        // "ConnectionStrings:CoreBanking" is assembled at start-up from Parameter Store (host, db)
        // and Secrets Manager (user, password) — see the Configuration and Secrets lessons.
        var conn = new SqlConnection(configuration.GetConnectionString("CoreBanking"));
        await conn.OpenAsync(ct);
        return conn;
    }
}

What changed and why:

  1. ApiController/IHttpActionResult → minimal API returning IResult. MVC controllers also exist in ASP.NET Core; minimal APIs are shown because they match the module project.
  2. HttpContext.Current → the ClaimsPrincipal parameter, injected per request. HttpContext.Current does not exist in ASP.NET Core.
  3. [Authorize] with Windows auth → RequireAuthorization("servicing:read") with an OIDC token. Staff sign in through the corporate IdP; the policy checks a group or scope.
  4. System.Data.SqlClient → Microsoft.Data.SqlClient, the maintained provider for modern .NET.
  5. String-concatenated SQL → a parameter with an explicit type and length. (Tools port syntax; they do not reliably fix security bugs. Review finds those.)
  6. ConfigurationManager → IConfiguration; the password arrives from Secrets Manager, never from a file.
  7. Synchronous Open/ExecuteReader → async with cancellation, so threads are not blocked under load.
  8. EventLog.WriteEntry with the customer ID → a structured log line with the staff ID and a count only; it goes to stdout and CloudWatch.
  9. Validation returns ProblemDetails 400 instead of passing garbage to SQL.

WCF: keep the contract or redesign

The Payments Gateway exposes a SOAP IPaymentService over basicHttpBinding to three partner systems that will not change for two years. Options:

  • CoreWCF: keep the [ServiceContract] and data contracts, host in ASP.NET Core on .NET 10, run on Linux Fargate. Supports the common HTTP bindings and NetTcp ⚠ VERIFY the binding you use is supported by your CoreWCF version.
  • Facade: a new REST/gRPC service for new consumers, with a thin CoreWCF facade translating for the legacy partners until they move.
  • Retain on Windows: if it depends on WS-* features or bindings CoreWCF lacks (some security modes, MSMQ), keep it on Windows EC2 for now behind an internal load balancer.
CoreWCF hosting in Program.cs (sketch)
// Packages: CoreWCF.Primitives, CoreWCF.Http
builder.Services.AddServiceModelServices();
var app = builder.Build();
app.UseServiceModel(sm =>
{
    sm.AddService<PaymentService>();
    sm.AddServiceEndpoint<PaymentService, IPaymentService>(
        new CoreWCF.BasicHttpBinding(CoreWCF.Channels.BasicHttpSecurityMode.Transport), "/PaymentService.svc");
});
app.Run();

Step-by-step implementation

Inventory and classify

For every app: owner, business criticality, framework version, project types, external dependencies (COM, native DLLs, MSMQ), authentication method, data stores and change frequency. Assign a strategy with the decision flow above.

Assess with AWS Transform for .NET

Connect the repositories, run an assessment, and review the modernisation plan: which projects port cleanly, which have blockers, which private NuGet packages are missing.

Prepare the codebase

Get the solution building and its tests passing before transformation. Convert to SDK-style project files where possible. Add characterisation tests around critical behaviour (e.g. fee calculation, rounding) so you can prove the port changed nothing.

Transform and review

Run the transformation into a new branch. Review the diff like a pull request from a new colleague: correctness, security, unnecessary changes. Fix what the tool flagged as next steps.

Re-platform the cross-cutting concerns

Configuration and secrets, authentication (OIDC), logging (JSON stdout), session state, health checks, a Dockerfile. These are design work: use the module project as the reference shape.

Prove equivalence and cut over

Run the old and new versions side by side on the same inputs (shadow traffic or replayed requests), compare outputs, then switch traffic gradually (weighted target groups), with a rollback plan.

AWS Console instructions

  • AWS Transform is accessed through its web application (sign-in via IAM Identity Center for your organisation) or from Visual Studio with the AWS Toolkit. An administrator first enables AWS Transform in the account and grants users access ⚠ VERIFY the current enablement steps in the AWS Transform user guide, as they changed during 2025–2026.
  • In the web app: create a workspace → create a job → choose .NET modernization → connect a source control connector → select repositories → review the assessment and plan → approve → review the results branch.
  • Elastic Beanstalk → Create application → Platform: .NET on Windows Server (IIS) is the rehost target for an app you are not porting yet.
  • EC2 → Launch instance → Microsoft Windows Server 2025 Base (licence-included AMI) for apps needing full Windows control.

AWS CLI

AWS Transform's .NET jobs are driven from its web application or the IDE, not from the AWS CLI in this lesson. The CLI helps with the rehost and target sides:

# List current Beanstalk platforms for IIS (rehost target) and .NET on Linux (ported target)
aws elasticbeanstalk list-available-solution-stacks \
  --query "SolutionStacks[?contains(@, 'IIS') || contains(@, '.NET 10')]" --profile learn-sandbox

# Find the latest licence-included Windows Server AMI via the public SSM parameter
aws ssm get-parameters-by-path --path /aws/service/ami-windows-latest \
  --query "Parameters[?contains(Name, 'Windows_Server-2025-English-Full-Base')].[Name,Value]" \
  --output table --profile learn-sandbox

# Compare hourly On-Demand prices: Linux vs Windows for the same instance type (Price List API, us-east-1)
aws pricing get-products --service-code AmazonEC2 --region us-east-1 \
  --filters Type=TERM_MATCH,Field=instanceType,Value=m7i.large \
            Type=TERM_MATCH,Field=location,Value="US East (N. Virginia)" \
            Type=TERM_MATCH,Field=tenancy,Value=Shared \
            Type=TERM_MATCH,Field=preInstalledSw,Value=NA \
            Type=TERM_MATCH,Field=capacitystatus,Value=Used \
  --query "PriceList[]" --output text --profile learn-sandbox | head -c 2000

Infrastructure as Code

The rehost target (Windows/IIS on Beanstalk) and the ported target (Linux Fargate, as in the module project's FargateStack.cs) side by side.

RehostStack.cs (Windows/IIS on Elastic Beanstalk)
using Amazon.CDK;
using Amazon.CDK.AWS.ElasticBeanstalk;
using Constructs;

public sealed class RehostStack : Stack
{
    public RehostStack(Construct scope, string id, IStackProps props, string instanceProfileName, string solutionStack)
        : base(scope, id, props)
    {
        var app = new CfnApplication(this, "App", new CfnApplicationProps { ApplicationName = "hl-servicing-portal-legacy" });

        var env = new CfnEnvironment(this, "Env", new CfnEnvironmentProps
        {
            ApplicationName = "hl-servicing-portal-legacy",
            EnvironmentName = "hl-servicing-portal-legacy-test",
            SolutionStackName = solutionStack, // e.g. "64bit Windows Server 2025 v2.x.y running IIS 10.0" — look it up
            OptionSettings = new CfnEnvironment.OptionSettingProperty[]
            {
                new() { Namespace = "aws:elasticbeanstalk:environment", OptionName = "EnvironmentType", Value = "SingleInstance" },
                new() { Namespace = "aws:autoscaling:launchconfiguration", OptionName = "IamInstanceProfile", Value = instanceProfileName },
                new() { Namespace = "aws:ec2:instances", OptionName = "InstanceTypes", Value = "t3.large" },
                new() { Namespace = "aws:elasticbeanstalk:cloudwatch:logs", OptionName = "StreamLogs", Value = "true" },
                new() { Namespace = "aws:elasticbeanstalk:cloudwatch:logs", OptionName = "RetentionInDays", Value = "30" },
            },
        });
        env.AddResourceDependency(app);
    }
}

Complete code

A portability scanner: a small .NET 10 console app you can point at a legacy source tree to count the most common blockers per project before (or alongside) AWS Transform. It is deliberately simple text scanning: a triage tool for estimating effort, not a compiler.

Harbourline.PortScan.csproj
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>
Program.cs
using System.Text.RegularExpressions;
using System.Xml.Linq;

// Usage: dotnet run -- <path-to-legacy-solution-folder>
var root = args.Length > 0 ? args[0] : ".";
if (!Directory.Exists(root))
{
    Console.Error.WriteLine($"Folder not found: {root}");
    return 2;
}

// Blocker patterns, with a rough effort weight (1 = mechanical, 5 = redesign).
var rules = new (string Name, Regex Pattern, int Weight)[]
{
    ("System.Web usage",           new(@"\busing\s+System\.Web\b|HttpContext\.Current"), 3),
    ("ConfigurationManager",       new(@"\bConfigurationManager\."), 1),
    ("WCF service contract",       new(@"\[ServiceContract\]"), 4),
    ("Web Forms page",             new(@"System\.Web\.UI\.Page\b"), 5),
    ("Windows registry",           new(@"\bMicrosoft\.Win32\.Registry\b|\bRegistry\.(LocalMachine|CurrentUser)"), 2),
    ("Event Log",                  new(@"\bEventLog\.WriteEntry\b"), 1),
    ("System.Drawing",             new(@"\busing\s+System\.Drawing\b"), 3),
    ("AppDomain / Remoting",       new(@"\bAppDomain\.CreateDomain\b|System\.Runtime\.Remoting"), 5),
    ("SQL built by concatenation", new("\"\\s*(SELECT|UPDATE|DELETE|INSERT)\\b[^\"]*\"\\s*\\+", RegexOptions.IgnoreCase), 2),
};

var projects = Directory.EnumerateFiles(root, "*.csproj", SearchOption.AllDirectories).ToList();
if (projects.Count == 0)
{
    Console.Error.WriteLine("No .csproj files found.");
    return 1;
}

var grandTotal = 0;
foreach (var project in projects.Order(StringComparer.OrdinalIgnoreCase))
{
    var dir = Path.GetDirectoryName(project)!;
    var framework = ReadTargetFramework(project);
    var counts = rules.ToDictionary(r => r.Name, _ => 0);

    foreach (var file in Directory.EnumerateFiles(dir, "*.cs", SearchOption.AllDirectories)
                                  .Where(f => !f.Contains($"{Path.DirectorySeparatorChar}obj{Path.DirectorySeparatorChar}")))
    {
        var text = File.ReadAllText(file);
        foreach (var rule in rules)
        {
            counts[rule.Name] += rule.Pattern.Matches(text).Count;
        }
    }

    var score = rules.Sum(r => Math.Min(counts[r.Name], 20) * r.Weight); // cap so one noisy rule can't dominate
    grandTotal += score;
    Console.WriteLine($"{Path.GetFileName(project),-45} {framework,-12} effort score {score,4}");
    foreach (var rule in rules.Where(r => counts[r.Name] > 0))
    {
        Console.WriteLine($"    {rule.Name,-28} {counts[rule.Name],5}");
    }
}

Console.WriteLine($"\n{projects.Count} projects, total effort score {grandTotal}. Higher scores need design work, not just tooling.");
return 0;

static string ReadTargetFramework(string csproj)
{
    var doc = XDocument.Load(csproj);
    return doc.Descendants().FirstOrDefault(e => e.Name.LocalName is "TargetFrameworkVersion" or "TargetFramework" or "TargetFrameworks")?.Value
        ?? "unknown";
}

Example output on a fictional legacy tree:

Harbourline.PaymentsGateway.csproj            v4.8         effort score   31
    WCF service contract             3
    ConfigurationManager             7
    Event Log                        2
    SQL built by concatenation       5
Harbourline.ServicingPortal.csproj            v4.8         effort score   46
    System.Web usage                12
    ConfigurationManager             4
    System.Drawing                   2
    SQL built by concatenation       1

2 projects, total effort score 77. Higher scores need design work, not just tooling.

Code explained line by line

  1. args[0] — the folder holding the legacy solution; nothing is modified, the tool only reads.
  2. rules — each blocker as a regular expression and a weight. Weights encode experience: ConfigurationManager is mechanical (1), WCF server contracts need a hosting decision (4), Web Forms and AppDomains need redesign (5).
  3. The SQL concatenation rule flags a security smell, not a portability blocker: a port is the cheapest moment to fix SQL injection, because the code is being touched and retested anyway.
  4. Directory.EnumerateFiles(root, "*.csproj", ...) — every project; old-style and SDK-style project files both work.
  5. Skipping obj folders — generated code would inflate counts.
  6. Math.Min(counts, 20) * weight — caps each rule so that 300 ConfigurationManager calls (one search-and-replace) do not outweigh three WCF contracts.
  7. ReadTargetFramework — old-style projects use TargetFrameworkVersion (v4.8); SDK-style use TargetFramework(s) (net48). LocalName ignores the MSBuild XML namespace of old-style projects.
  8. The output is a triage list. Feed the high scorers to an architect, the low scorers straight to AWS Transform.

Security considerations

⚠ Learning shortcut — not for production

The rehost IaC example uses a single-instance Beanstalk environment in the default VPC. Production rehosts go into private subnets behind an internal or WAF-protected ALB, with Systems Manager Patch Manager for Windows updates, no RDP from the internet (use Session Manager), and CloudWatch agent log collection.

  • Connecting AWS Transform to source control grants a service access to your code. Use a dedicated connector with access only to the repositories in scope, and record the approval. Code is intellectual property and may contain secrets: scan repositories for secrets before connecting, and rotate any you find.
  • Review AI-generated code with the same rigour as human code, including security review and tests. Segregation of duties still applies: the person who ran the transformation should not be the only approver.
  • Windows authentication disappears in a Linux port. Replacing it with OIDC changes how staff are identified in audit logs; agree the new audit identifiers with the security and audit teams.
  • Secrets in web.config are a common finding in legacy code. Treat every secret found during a port as compromised: rotate it and move it to Secrets Manager.

Banking use case

Harbourline's 60 .NET Framework apps after a two-week assessment:

StrategyAppsExamplesTarget
Retire9Old report viewers replaced by the data platformDecommission
Repurchase4HR and expenses toolsSaaS
Port (tool-assisted)28Web API 2 services, MVC internal tools, batch console apps.NET 10, Linux containers on ECS Fargate
Port with redesign6Payments Gateway (WCF → CoreWCF facade + REST), Servicing Portal (incremental strangler).NET 10 on Fargate, over 9–12 months
Rehost now, port later10Apps with third-party Windows-only componentsEC2 Windows / Beanstalk IIS, private subnets
Retain on-premises3Mainframe-adjacent integrationsStay until the core banking programme

Licence cost was a key driver: Windows instances include the Windows Server licence in the hourly price, so the 28 ported apps on Linux Fargate save that licence cost every hour they run, in addition to faster starts and smaller images. The FinOps team tracks the saving per app as the port completes.

Common mistakes

  • Porting everything → the deadline passes with half-ported apps → portfolio strategy: rehost, port, retire.
  • Treating tool output as done → subtle behaviour changes (culture, rounding, date handling) reach production → characterisation tests and side-by-side comparison.
  • Ignoring cross-cutting concerns → the app compiles on .NET 10 but still reads C:\config\, writes to the event log and needs Kerberos → re-platform config, logs, auth and state deliberately.
  • Forgetting globalisation → Linux containers with invariant globalisation format currency and dates differently → set cultures explicitly, test formatting, or disable invariant mode where culture-specific formatting is required.
  • Assuming the old AWS tools exist → plans built around Porting Assistant or App2Container → use AWS Transform for .NET.
  • Porting without tests → no way to prove equivalence → write tests first, on .NET Framework, then keep them passing.

Troubleshooting

SymptomLikely causeFix
Transformation stops asking for packagesPrivate NuGet packages not reachableUpload them or connect the private feed as the job requests
Ported app builds but fails at runtime with PlatformNotSupportedExceptionWindows-only API (registry, System.Drawing, WMI)Replace with a cross-platform library or move the call behind an interface
Amounts formatted as ¤1,234.00 or dates in the wrong order on LinuxInvariant globalisation or missing culture in the containerFormat with explicit CultureInfo("en-GB"); include ICU or disable InvariantGlobalization
WCF clients cannot connect to the CoreWCF serviceUnsupported binding or security modeCheck CoreWCF binding support; add a facade or keep that endpoint on Windows
Login loop after portCookie/auth settings differ behind the ALB (scheme, forwarded headers)UseForwardedHeaders with known networks; correct OIDC redirect URIs
Beanstalk Windows deployment failsPackage layout not as the IIS platform expectsUse the Web Deploy package or a deployment manifest per the Beanstalk Windows docs

Cost and cleanup

This lesson's code runs locally and needs no AWS resources (🟢 free). AWS Transform's managed .NET transformations are free within the monthly quota of 50,000 agent minutes; check the AWS Transform pricing page before large jobs.

If you deployed the rehost example, remember that Windows instances bill the licence in their hourly price and Beanstalk environments keep running until terminated:

aws elasticbeanstalk terminate-environment --environment-name hl-servicing-portal-legacy-test --profile learn-sandbox
aws elasticbeanstalk delete-application --application-name hl-servicing-portal-legacy --terminate-env-by-force --profile learn-sandbox
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab \
  --query "ResourceTagMappingList[].ResourceARN" --profile learn-sandbox

Exercises

  • 🟢 Guided: Create a folder with the "Before" controller in a .cs file and a minimal old-style .csproj containing <TargetFrameworkVersion>v4.8</TargetFrameworkVersion>. Run the portability scanner on it and explain each finding.
  • 🟡 Challenge: Port the "Before" controller yourself to an ASP.NET Core project that uses the Accounts API's patterns (ProblemDetails, correlation IDs, a repository interface, IOptions), with an xUnit v3 test proving the SQL injection string CUS-00012345' OR '1'='1 returns 400.
  • 🔴 Live problem: The programme manager asks: "AWS Transform ported the Payments Gateway in two days. Can we go live next week?" The transformation report lists 14 next steps, the WCF service uses wsHttpBinding with message security, and there are no automated tests. Write your answer.

Assignment

Produce a migration assessment for one real or imagined legacy .NET Framework application: inventory (dependencies, auth, data, integrations), scanner output, the chosen strategy with reasons, the target AWS architecture diagram, the cross-cutting changes needed, test strategy for equivalence, licence cost before/after, and the risks for the change board.

Solutions

Knowledge check

Interview questions

  • "How would you migrate 50 .NET Framework apps to AWS?" — Inventory and classify (retire, repurchase, rehost, port, retain), assess ports with AWS Transform for .NET, port the easy majority to .NET 10 on Linux containers, rehost blockers on Windows for now, standardise cross-cutting concerns, prove equivalence with tests, track licence savings.
  • "What's hard about porting ASP.NET MVC to ASP.NET Core?" — Not controllers: System.Web modules and handlers, HttpContext.Current, configuration, authentication (Windows auth), session state and anything Windows-only. Plus behaviour differences like model binding and globalisation.
  • "Do you trust AI-ported code?" — As much as any colleague's pull request: review, tests, security scanning, equivalence testing, and segregation of duties for approval.
  • "WCF in the cloud?" — CoreWCF for supported bindings on Linux; otherwise a facade or Windows hosting; long-term, move consumers to REST or gRPC.

Certification practice

Completion checklist

  • I can classify an application with the migration strategies and justify the choice
  • I can describe AWS Transform for .NET's scope, access, cost and limits
  • I know which older AWS and Microsoft tools are closed or deprecated
  • I can list the classic blockers and their modern replacements
  • I ran the portability scanner on a sample project
  • I can explain the licence cost difference between Windows and Linux hosting

Key takeaways

  • Migration is a portfolio decision: retire, repurchase, rehost, port and retain each have their place.
  • AWS Transform for .NET is the current AWS tool (Porting Assistant and App2Container are closed to new customers); Microsoft's Upgrade Assistant is deprecated in favour of a Copilot-based agent.
  • Tools port syntax; you redesign identity, configuration, secrets, logging, state and prove equivalence with tests.
  • WCF server → CoreWCF or redesign; Web Forms → incremental rewrite; Windows-only components → rehost and isolate.
  • Ported Linux workloads drop the Windows licence from every running hour.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page