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.
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:
| Aspect | Details |
|---|---|
| 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) |
| Languages | C#, VB.NET |
| Project types | Class 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 control | Connects to GitHub, GitLab, Bitbucket and Azure Repos; commits results to a new branch, original code untouched |
| Experiences | AWS Transform web application (bulk, many repositories), the AWS Toolkit for Visual Studio (interactive, one solution), and AI code companions via an MCP server |
| Validation | Builds the transformed code and runs unit tests; produces a transformation report with next steps |
| Human steps | Approve the plan, supply missing private NuGet packages, review and accept code |
| Cost | AWS-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 theMicrosoft.DotNet.UpgradeAssistantanalyzers (historical); in practice the modern route is: convert to SDK-style project, multi-target, fix compile errors.Microsoft.Windows.Compatibilitypackage — brings many Windows-only APIs (registry, event log,System.Drawing.Commonon 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 equivalent | What's different |
|---|---|---|
| Azure Migrate (discovery, assessment) | AWS Transform (assessment and migration agents), AWS Migration Evaluator | AWS Migration Hub and Application Discovery Service closed to new customers in 2025 |
| .NET Upgrade Assistant / Copilot app modernization | AWS Transform for .NET | AWS 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 Windows | Beanstalk creates real EC2 instances you can see and pay for (Windows licence included in the price) |
| App Service on Linux / Container Apps | ECS on Fargate (Linux), ECS Express Mode | Linux Fargate tasks are cheaper than Windows ones and start faster |
| Azure Hybrid Benefit for Windows Server | Bring Your Own License on Dedicated Hosts (restricted), otherwise licence-included | Licence mobility rules for Windows Server changed in 2019; licence-included is the norm on shared tenancy |
| Managed Instance for SQL Server | Amazon RDS for SQL Server | Licence-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 replacement | Effort |
|---|---|---|
System.Web (HttpContext.Current, HttpModule, Global.asax) | ASP.NET Core middleware, IHttpContextAccessor, Program.cs | Medium; mechanical for MVC/Web API controllers, hard for modules |
web.config + ConfigurationManager.AppSettings | appsettings.json, environment variables, IOptions<T>, Parameter Store | Low–medium |
Connection strings with passwords in web.config | Secrets Manager (+ IAM auth where possible) | Low, but needs process change |
| WCF client | System.ServiceModel.* packages (client side is supported on modern .NET) | Low |
| WCF server | CoreWCF (keep SOAP contracts) or redesign as REST/gRPC | Medium–high |
| ASP.NET Web Forms | No direct equivalent: Razor Pages/Blazor rewrite, ideally incremental | High |
| Windows authentication (Kerberos/NTLM) | OIDC with the corporate IdP; Negotiate auth only if you stay on domain-joined Windows | Medium |
| Session in-proc / SQL Server session state | IDistributedCache (ElastiCache/DynamoDB) — see Scaling .NET apps | Low–medium |
System.Drawing for images/PDFs | Cross-platform libraries (e.g. SkiaSharp, ImageSharp, QuestPDF) | Medium |
| Registry, Event Log, Windows Services | Configuration, stdout logs, Worker Services | Low–medium |
AppDomain, .NET Remoting, Code Access Security | Separate processes, gRPC/HTTP, OS-level isolation | High (redesign) |
| Entity Framework 6 | EF 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:
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.
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:
ApiController/IHttpActionResult→ minimal API returningIResult. MVC controllers also exist in ASP.NET Core; minimal APIs are shown because they match the module project.HttpContext.Current→ theClaimsPrincipalparameter, injected per request.HttpContext.Currentdoes not exist in ASP.NET Core.[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.System.Data.SqlClient→Microsoft.Data.SqlClient, the maintained provider for modern .NET.- String-concatenated SQL → a parameter with an explicit type and length. (Tools port syntax; they do not reliably fix security bugs. Review finds those.)
ConfigurationManager→IConfiguration; the password arrives from Secrets Manager, never from a file.- Synchronous
Open/ExecuteReader→ async with cancellation, so threads are not blocked under load. EventLog.WriteEntrywith the customer ID → a structured log line with the staff ID and a count only; it goes to stdout and CloudWatch.- 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 andNetTcp⚠ 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.
// 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 2000Infrastructure 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.
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.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
</Project>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
args[0]— the folder holding the legacy solution; nothing is modified, the tool only reads.rules— each blocker as a regular expression and a weight. Weights encode experience:ConfigurationManageris mechanical (1), WCF server contracts need a hosting decision (4), Web Forms and AppDomains need redesign (5).- 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.
Directory.EnumerateFiles(root, "*.csproj", ...)— every project; old-style and SDK-style project files both work.- Skipping
objfolders — generated code would inflate counts. Math.Min(counts, 20) * weight— caps each rule so that 300ConfigurationManagercalls (one search-and-replace) do not outweigh three WCF contracts.ReadTargetFramework— old-style projects useTargetFrameworkVersion(v4.8); SDK-style useTargetFramework(s)(net48).LocalNameignores the MSBuild XML namespace of old-style projects.- 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.configare 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:
| Strategy | Apps | Examples | Target |
|---|---|---|---|
| Retire | 9 | Old report viewers replaced by the data platform | Decommission |
| Repurchase | 4 | HR and expenses tools | SaaS |
| Port (tool-assisted) | 28 | Web API 2 services, MVC internal tools, batch console apps | .NET 10, Linux containers on ECS Fargate |
| Port with redesign | 6 | Payments Gateway (WCF → CoreWCF facade + REST), Servicing Portal (incremental strangler) | .NET 10 on Fargate, over 9–12 months |
| Rehost now, port later | 10 | Apps with third-party Windows-only components | EC2 Windows / Beanstalk IIS, private subnets |
| Retain on-premises | 3 | Mainframe-adjacent integrations | Stay 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
| Symptom | Likely cause | Fix |
|---|---|---|
| Transformation stops asking for packages | Private NuGet packages not reachable | Upload them or connect the private feed as the job requests |
Ported app builds but fails at runtime with PlatformNotSupportedException | Windows-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 Linux | Invariant globalisation or missing culture in the container | Format with explicit CultureInfo("en-GB"); include ICU or disable InvariantGlobalization |
| WCF clients cannot connect to the CoreWCF service | Unsupported binding or security mode | Check CoreWCF binding support; add a facade or keep that endpoint on Windows |
| Login loop after port | Cookie/auth settings differ behind the ALB (scheme, forwarded headers) | UseForwardedHeaders with known networks; correct OIDC redirect URIs |
| Beanstalk Windows deployment fails | Package layout not as the IIS platform expects | Use 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-sandboxExercises
- 🟢 Guided: Create a folder with the "Before" controller in a
.csfile and a minimal old-style.csprojcontaining<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 stringCUS-00012345' OR '1'='1returns 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
wsHttpBindingwith 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
The scanner reports System.Web usage (the using System.Web; and HttpContext.Current), ConfigurationManager (1), Event Log (1) and SQL built by concatenation (1), with framework v4.8. Interpretation: the controller itself is mechanical to port (score in the low teens), but the SQL finding is a security defect to fix during the port, the event log call means the audit trail must be redesigned (structured logs), and HttpContext.Current.User signals Windows authentication, so identity is the real design work.
Create an ASP.NET Core project, a ICustomerAccountsReader interface with a SQL implementation using parameters and a fake for tests, an endpoint that validates ^CUS-[0-9]{8}$ and returns Results.Problem(statusCode: 400, ...) otherwise, and the Accounts API's ProblemDetails registration. The test uses WebApplicationFactory<Program>, replaces the reader with a fake, sends GET /api/customers/CUS-00012345'%20OR%20'1'='1/accounts (URL-encoded) and asserts 400 and that the fake was never called. Why: validation is the first defence and parameterisation the second; the test pins both so a later refactor cannot remove them silently.
No. A two-day port is excellent progress, not a release. Before go-live: (1) work through the 14 next steps; (2) wsHttpBinding with message security is a binding/security mode to check against CoreWCF support, and may require a facade or keeping that endpoint on Windows; (3) with no tests there is no evidence of equivalence for a payments system: build characterisation tests against the old system, replay a representative sample of real (anonymised) requests through both, compare responses; (4) security review of the diff and the new auth model; (5) partner connectivity tests; (6) a cutover plan with rollback. Offer a realistic date and a parallel run, and propose moving lower-risk ported services first.
Knowledge check
Answer: AWS Transform for .NET. The older tools closed to new customers on 7 November 2025.
Answer: ASP.NET Web Forms (rewrite UI incrementally with Razor Pages/Blazor, strangler pattern) and WCF server (CoreWCF to keep contracts, or redesign as REST/gRPC). Also AppDomains/Remoting (separate processes and HTTP/gRPC).
Answer: When the deadline is short, the port risk is high, or the app depends on Windows-only components (COM, native DLLs, unsupported bindings). It moves the app quickly, often as a first step before porting later.
Answer: Windows instances include the Windows Server licence in their hourly price; Linux tasks and instances do not. Linux containers are also smaller and start faster, so they scale more cheaply.
Answer: Treat them as compromised: rotate them and move them to Secrets Manager (or Parameter Store SecureString), with the app reading them at run time through its IAM role.
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.Webmodules 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
A company runs 20 ASP.NET Web API 2 services on .NET Framework 4.8 on Windows EC2 instances. Analysis shows no Windows-specific dependencies. Which change reduces compute cost the MOST over time?
A. Move the instances to Dedicated Hosts. B. Port the services to .NET 10, containerise them and run them on Amazon ECS with AWS Fargate on Linux. C. Purchase Windows Reserved Instances for three years. D. Move the instances to larger instance types with fewer instances.
Answer: B. Removing the Windows licence cost and right-sizing with containers gives the largest long-term saving. C lowers the price but keeps the licence cost and locks in. A is for licence compliance, usually more expensive. D does not address licensing.
A bank must leave its data centre in four months. A critical .NET Framework application uses a third-party COM component and WCF message security. What is the MOST appropriate first step?
A. Port the application to .NET 10 on Linux before migrating. B. Rehost the application on Windows EC2 instances in private subnets behind an internal Application Load Balancer, and plan a later modernisation. C. Rewrite the application as AWS Lambda functions. D. Retire the application.
Answer: B. The deadline and Windows-only dependencies make rehosting the low-risk choice; modernise afterwards. A and C are high-risk within four months and blocked by COM and WCF. D is not possible for a critical application.
A developer ports an ASP.NET MVC application to ASP.NET Core on Amazon ECS. The old application read a database password from web.config. What is the MOST secure way to provide it now?
A. Put the password in appsettings.json inside the container image.
B. Store the password in AWS Secrets Manager and read it at run time using the task role (or inject it with the task definition's secrets field).
C. Pass the password as a plaintext environment variable in the task definition.
D. Store it in an S3 object with public read disabled.
Answer: B. Secrets Manager keeps it encrypted, access-controlled, audited and rotatable. A bakes the secret into the image. C exposes it to anyone who can describe the task definition. D lacks rotation and secret-specific controls.
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.
Background processing: worker services, SQS consumers and scheduled jobs
Move slow and scheduled work out of the request path: .NET Worker Services on Fargate, SQS consumers with long polling, visibility timeouts, idempotency and dead-letter queues, Lambda SQS triggers with partial batch responses, and EventBridge Scheduler jobs.
Module project: one API, three hosts
Deploy the Harbourline Accounts API to Elastic Beanstalk, to ECS on Fargate behind an ALB, and to Lambda behind an HTTP API, measure each with the same probe, price each one, and record your recommendation as an architecture decision record.