AWS Builder Center

Modernizing .NET with AWS Transform and AWS DevOps Agent

Legacy .NET modernization stalls for a predictable reason: the upgrade itself is tractable, but nobody can say whether the upgraded application is "safe to release". A framework port touches hosting, configuration, serialization and error handling all at once, and a green build says nothing about any of them. This guide shows how to close that gap by pairing two AWS services: AWS Transform and AWS DevOps Agent release management

Objective

This guide shows how to close that gap by pairing two AWS services:
  •  AWS Transform  does the upgrade - assesses the estate, plans the work, and ports the code.
Run AWS Transform and AWS Devops Agent release management in sequence, they form a loop: transform, review, fix, re-review, deploy. The loop is the deliverable — it turns modernization from a one-off project into a repeatable stage you keep for the next upgrade.



Table of contents

  1. Conclusion



1. The upgrade problem in a typical .NET estate

Most .NET applications waiting to be modernized share a shape: three tiers, plus cross-cutting dependencies on Windows and IIS the tiers were never designed to be separated from.
Tier
Typical legacy form
Modern .NET form
Presentation
ASP.NET Web Forms / MVC 5 / Web API 2 on IIS,  Global.asax ,  System.Web , bundling
ASP.NET Core MVC,  Program.cs  + middleware, static assets
Business
Class libraries, WCF services, Windows Services,  System.Configuration 
CoreWCF / gRPC / REST,  IConfiguration , dependency injection
Data
SQL Server via ADO.NET or Entity Framework 6
EF Core,  Microsoft.Data.SqlClient 
Host
IIS terminates TLS,  Web.config , in-process pipeline
Kestrel behind a reverse proxy,  appsettings.json 
An upgrade rewrites all four rows at once — a large diff by definition, and the parts a compiler can verify are the easy parts.

What a green build does not tell you

A successful build proves
It says nothing about
Types resolve, packages substitute cleanly
Middleware ordering in the new pipeline
The project system converted
Who terminates TLS, and what the proxy forwards
The target framework is set
Whether error pages and health probes still resolve
References compile
Whether JSON on the wire kept its shape

Whether config keys survived the move out of  Web.config 
Every item in the right column is a dynamic, runtime property — it can only be verified by executing the application in an environment that resembles production. No compiler, linter, or source-to-source transformation tool can discover them; they require a sandbox that builds the change, runs it, and observes the result.
That is the gap AWS DevOps Agent release management fills. Its autonomous release testing does not re-read the diff — it deploys the change into an isolated sandbox, generates tests specific to the change, executes them, and observes real behaviour: HTTP status codes, response bodies, log output, error paths. A static build answers "does it compile?"; the sandbox answers "does it work?".



2. Division of responsibility

Knowing where each service stops prevents most wasted effort.
┌───────────────────────────── AWS Transform ────────────────────────────┐
│ Reads source ──▶ Assesses ──────▶ Plans ────────▶ Ports │
│ repo scan complexity, per-project writes code, │
│ package compat work items builds, reports │
│ │ │ │ │
│ Assessment Modernization transformed source │
│ _Report.md _Plan.md + nextsteps.md │
└─────────────────────────────────────────────────────────────────────────┘
│
▼ transformed code lands in your repo ▼
│
┌──────────────────────────── AWS DevOps Agent ──────────────────────────┐
│ Release readiness review Autonomous release testing │
│ • reads the diff • builds the change │
│ • cross-repo dependency • generates change-specific tests │
│ • access control ──────▶ • runs them in a sandbox │
│ • your written standards • observes real behaviour │
│ │ │ │
│ └────────────┬─────────────┘ │
│ ▼ │
│ release verdict │
└─────────────────────────────────────────────────────────────────────────┘
AWS Transform owns framework retarget, project system conversion, package substitution, API surface migration, UI layer porting, build validation, and a written account of what it could not finish. DevOps Agent owns whether the resulting diff is safe to release — judged against production requirements, dependency safety, access-control changes, and standards you author in plain English. You own the topology-specific decisions neither service can infer: where TLS terminates, what the reverse proxy does, which host the app runs on.

Release readiness review: the four verdicts

The review returns a report whose decisive field is  recommendedAction , the value your pipeline keys on. It takes four values — three documented, plus one that matters more than its documentation suggests.
 recommendedAction 
Meaning
What your pipeline should do
 Safe to Release 
No blocking findings
Proceed
 Deploy with Caution 
Findings exist, none blocking
Proceed with recorded sign-off, or fail on a strict gate
 BLOCK 
Blocking findings
Fail
 Request Permissions 
The agent could not read the change
Fail — this is not a pass
 Request Permissions  will bite an unattended pipeline. In the reference run the review returned it because the repository had not been associated with the agent space. The review completed successfully and reported zero risks:
RECOMMENDED ACTION : Request Permissions
risks : 0
critical gaps : 3
files : +0 -0 ~0
SUMMARY
Deployment safety cannot be assessed — repository access is required
before this change can be analyzed.
Zero risks does not mean safe; it means nothing was examined. Two rules follow — the whole of the gate logic:
  • Gate on  recommendedAction , never on risk count.
  • Treat an unrecognised value as failure. The vocabulary can grow.



3. Setting up

Both services need a source-control connection, an identity, and a region. The mechanics are well covered in AWS documentation; this gives the sequence and the three things that consistently catch people out.

3.1 AWS Transform

  1. Sign in to your Transform tenant with IAM Identity Center.
  1. Connect source code — one of four options - Code Connection, PAT, S3Direct Upload.
  1. Start a .NET modernization job and let discovery run.
  1. Approve scope → review assessment → approve plan → transform.
  1. Download the artifacts.

3.2 AWS DevOps Agent

  1. Create an agent space in US East (N. Virginia).
  1. Associate your repository with that agent space. GitHub is a one-time OAuth step in the console; GitLab can be registered programmatically.
  1. Author your release readiness standards — web app, under Knowledge → Instructions → Release readiness review, in plain English. Without them the agent applies general best practices — a reasonable start, but not your policy.
  1. Request a review naming repository, head and base.
  1. Read the verdict.



4. The migration loop

Eight steps, three owners. The bands show which service is in scope at each step — and ownership alternates, the single most important thing to internalize here.
OWNER STEP OUTPUT / GATE
══════════╪══════════════════════╪═════════════════════════════════
YOU [0] BASELINE legacy deployed, contract recorded
──────────┼──────────────────────┼─────────────────────────────────
[1] ASSESS ─ ─ ─ ─ ─▶ Assessment_Report.md GATE accept scope
AWS [2] PLAN ─ ─ ─ ─ ─▶ Modernization_Plan.md GATE approve/edit plan
TRANSFORM [3] TRANSFORM transformed source + nextsteps.md
──────────┼──────────────────────┼─────────────────────────────────
YOU [4] TRIAGE ◀───────┐ topology fixes, on a branch
──────────┼─────────────────── │ ┼─────────────────────────────────
AWS [5] REVIEW │ verdict + risks + test evidence
DEVOPS verdict? ──────┘ LOOP until acceptable
──────────┼──────────────────────┼─────────────────────────────────
YOU [6] DEPLOY verify the step [0] contract
──────────┼──────────────────────┼─────────────────────────────────
AWS [7] OPERATE incident investigation, RCA
DEVOPS



5. Phase walkthrough

Phase 0 — Establish a verifiable baseline

Phase 0 captures it. Deploy the legacy application unchanged and record its externally observable contract before touching the code, so every later comparison is against a fixed reference rather than memory or assumption. Capture the contract by whatever means fits your stack — a health or info endpoint, recorded API responses, saved HTTP traces.
Reference .Net Web+ App before migration




Phase 1 — Assessment

Discovery runs first, reporting what it found per repository and branch:
Note the third option — upload steering docs — offered before assessment begins. Steering documents are custom transformation rules; if you already know house conventions the transform should follow, this is the earlist point to say so.
Assessment then produces a per-repository summary and  Assessment_Report.md :

Complexity does not scale with size. Sample repo 357 lines rated  Complex  at repository level and  critical  per project — the rating reflects framework-coupling density, not volume. Do not estimate effort linearly, and do not dismiss a small repository as easy.
Before approving, read two things in the report:
  1. Blocking issues — named incompatible packages with no automated upgrade path.
  1. Configuration review — Transform inspects config for secrets (the reference run reported "Web.config contains no secrets"). If yours does, resolve it before the port, not after.



Phase 2 — Plan

Planning runs in the background after assessment; the target framework is confirmed here:

When the plan is ready, the agent surfaces a recommendation worth taking seriously:

Recommendation: For medium/high complexity, consider AWS Toolkit for Visual Studio for a more interactive experience with better control over complex migrations.
Transform routes you to a different surface based on its own complexity assessment. The web app suits straightforward repositories; the Visual Studio toolkit gives per-project step-through for the hard ones. If your first wave is rated Complex, take the advice.
 Modernization_Plan.md  is where you exercise the most control — per project: target framework, complexity, change count, work items, a package table, a legacy-file mapping, and prose migration notes. Work items are specific and reviewable:
Update target framework: v4.8 -> net10.0 (convert legacy project to SDK-style)
Replace package: Microsoft.AspNet.WebApi (no automated upgrade path)
Migrate to ASP.NET Core Controllers on .NET 10 as the primary target
Replace HttpResponseMessage and IHttpActionResult returns with IActionResult
Add unit tests: automatically generated post-migration for testable classes
Change it two ways: edit the plan directly, or ask in natural language ("skip repo X", "transform only the .NET ones"). Note also where the plan defers to you — the reference plan raised host consolidation as an open architectural question and left it open; resolve those now. This is the cheapest place to intervene: changing direction here costs a re-plan, after transformation a re-run. Blocking gate.



Phase 3 — Transformation

Before transformation starts, the agent flags the setting that determines whether this phase is attended:

Checkpoints are on by default. The job pauses after each repo; turn off per repo in the Transformation dashboard, or switch to Autonomous to run end-to-end without pausing.
This is the most consequential setting for automation, and it is on by default. Choose deliberately:
Mode
Behaviour
Use for
Checkpoints on (default)
Pauses after every repository
First wave, complex repos, anything new to you
Checkpoints off per repo
Selected repositories run straight through
Mixed waves — hold the risky ones, release the routine ones
Autonomous
Whole job runs end to end
Unattended batches of known-shape repositories
Per-repo granularity is the useful part — in a mixed wave, hold checkpoints on the risky repos and let the rest run. Transformation then proceeds in dependency order:

Two dashboard panels appear as non-blocking human-in-the-loop items. If you automate polling, distinguish  BLOCKING  from  NON_BLOCKING  or you will wait forever on panels that never needed you. The agent then posts a structured change summary in chat and in the artifacts:

A reviewer who will not read a diff sees the structural change in plain terms:  net48  →  net10.0 ,  .csproj  → SDK-style,  packages.config  →  PackageReference ,  Global.asax  and  App_Start/  removed,  Program.cs  added, lifecycle events replaced by middleware. Outputs:
Artifact
Use
 transformed-source.zip 
the ported code
 Assessment_Report.md 
pre-transform analysis
 Modernization_Plan.md 
approved plan of record
 Transformation_Report.html 
rich change summary
 nextsteps.md 
the most important file — read it first



Phase 4 — Triage

Zero errors, zero warnings — and not deployable. Teams underestimate this phase; budget real engineering time for it.
 nextsteps.md  is genuinely good. In the reference run it opened with a prioritised summary, stated "there are no blockers", and listed ten items with file paths, priorities and concrete code — even ranking its own gaps: the top item was a missing static asset it had introduced, "causes a 404 on every page load; highest visible runtime impact."
Work it top to bottom first. Then look for what it could not know. Two classes of issue — and only the first is in the file.
Class 1 — flagged by the transform. Mechanical, well described, safe to delegate: a hardcoded framework string, a missing vendor asset, JSON casing, stale comments, leftover  Web.config  files. The hardcoded string is subtle:
Runtime = ".NET Framework " + Environment.Version // carried over unchanged
This compiled and ran. Left alone, the modernized application would have kept reporting itself as .NET Framework — the migration would have looked like it never happened. Anything that describes the runtime rather than uses it needs an explicit pass.
Class 2 — not flagged, because it depends on topology. This is where the review agent earns its place. The reference transform emitted, correct by any general standard:
app.UseHttpsRedirection();
app.UseHsts();
In the target topology — nginx terminating public traffic, forwarding plain HTTP to Kestrel on loopback, no HTTPS listener — that makes the app unreachable: every request 307-redirects to a port nothing is bound to, and HSTS pins browsers to a scheme not served. The right middleware is  UseForwardedHeaders() , which the transform did recommend in prose under Deployment Considerations.
Read the deployment-considerations prose, not just the code diff. The transform often knows the right answer and states it narratively while emitting a general-purpose default in code.

Triage checklist

  • [ ] Work every  nextsteps.md  item; explicitly record deferrals
  • [ ] Grep for strings describing runtime, framework or OS
  • [ ] Reconcile emitted middleware against your topology — TLS termination, reverse proxy, forwarded headers, health probe paths
  • [ ] Diff serialization behaviour against the Phase 0 baseline payload
  • [ ] Confirm config keys survived  Web.config  →  appsettings.json 
  • [ ] Remove legacy hosting config the transform preserved for reference
  • [ ] Verify the installed runtime matches the produced  TargetFramework 



Phase 5 — Release readiness review

Hand the change to the DevOps Agent, naming repository, head and base.
Choose the base deliberately. If head and base are the same branch, the diff is empty and the review vacuous. Either transform on a feature branch and review against mainline, or review mainline against the commit immediately before the transformation landed.
The report structure:
recommendedAction summary risks[] (severity, title, description)
confidenceLevel decisionReasoning preExistingRisks[]
revisions{from,to} changes{summary, criticalGaps[]
added,removed, recommendations[]
updated} monitoringGuidance

What the reference review produced


Read that header carefully: 0 critical issues of 1 total finding. A dashboard surfacing only the critical count would render this as a clean zero — yet the finding is the entire value of the run. It caught a defect a human review had already waved past: the transform emitted the path-based exception handler overload,
app.UseExceptionHandler("/error");
but no controller in that project served  /error .



Phase 6 — Remediate and re-review

Fix, push, re-run. Keep the loop short — it is the mechanism by which the pipeline adds value.
For the reference finding, the fix adopted the inline handler pattern the transform had already produced correctly in the sibling project, extended to emit a  ProblemDetails  body. Mark such changes distinctly in source —  POST-REVIEW FIX  alongside  POST-TRANSFORM FIX  — so later readers can tell transform output from transform output plus human correction. Then re-review: do not assume a fix is clean because it compiles — that assumption is what produced the finding in the first place.



Phase 7 — Deploy and operate

Deploy on  Safe to Release , or on  Deploy with Caution  plus recorded sign-off. Verify the same contract you captured in Phase 0 — same routes, same response shape, static assets resolving, health endpoints answering.

Same page, same  Hello World , same API contract — different runtime, OS and host. Against the Phase 0 capture, the only things that changed are the ones that were supposed to.
After deployment the same agent space covers operations: autonomous incident investigation, root cause analysis, and recommendations to prevent recurrence. The migration and operational halves share one knowledge graph of your environment — the argument for not treating them as separate tools.



6. Automating the loop

The two halves of the loop have different automation ceilings; being precise about why prevents over-promising and unnecessary pessimism alike.

6.1 What automates

Half
Ceiling
Why
Release readiness review
Fully automatable
SigV4, standard credentials, no interactive step. Put it in the PR gate permanently.
Transformation
Automatable within an operator session
Needs an IAM Identity Center token (~1 hour, browser PKCE).

6.2 The gate

Run the review in parallel with your existing build and scanners, not after — it is slower than a linter, and independent of them.
feature branch ──▶ pull request
│
┌────────────────┼────────────────┐
▼ ▼ ▼
build + unit release readiness existing
tests review scanners
│ │ │
└────────────────┼────────────────┘
▼
verdict gate
│
┌──────────┴──────────┐
▼ ▼
BLOCK / Request Safe / Caution
Permissions + sign-off
│ │
▼ ▼
fail the PR merge ──▶ deploy
The decision:
verdict = report.recommendedAction

if verdict == "Safe to Release": pass
elif verdict == "BLOCK": fail
elif verdict == "Request Permissions": fail # nothing was read
elif verdict == "Deploy with Caution": pass if signed off else fail
else: fail # unknown → fail closed
Publish the report to the pull request even when it passes — the value compounds when reviewers can see what was checked.

6.3 The APIs you need

Enough to build your own orchestration. Check current documentation before relying on any specific signature.
AWS DevOps Agent — SDK/CLI service name  devops-agent , endpoint prefix and signing name  aidevops .
Operation
Purpose
 ListAgentSpaces ,  GetAgentSpace 
discovery
 ListAssociations ,  AssociateService ,  RegisterService 
connection state
 CreateChat ,  SendMessage 
request a review
 ListBacklogTasks ,  GetBacklogTask 
find and track  RELEASE_READINESS_REVIEW  tasks
 ListJournalRecords 
reasoning and reports — the verdict lives here
 ListRecommendations ,  GetRecommendation ,  UpdateRecommendation 
mitigation lifecycle
AWS Transform — MCP server  awslabs.aws-transform-mcp-server  (19 tools, Python 3.10+) is the right choice for anything scripted. Key tools:  configure ,  load_instructions ,  create_workspace ,  create_job ,  create_connector ,  get_job_status ,  list_resources ,  get_resource ,  complete_task ,  control_job ,  upload_artifact . The  atx  CLI covers  custom  (natural-language),  ct  (continuous modernization),  mcp  and  json .
A minimal orchestration is four calls: submit the review, poll the task to a terminal state, paginate the journal for  release_analysis_report , gate on  recommendedAction .



Conclusion

The value is not either service on its own — it is the loop: Transform ports the code, the DevOps Agent proves the result behaves, and every finding you capture as a standard makes the next migration faster. Static build plus dynamic sandbox verification is what turns "it compiles" into "it is safe to release."
Start with one representative application, run it end to end, and convert what you learn into steering documents and standards before scaling to a portfolio.
Questions, corrections, or a topology this guide did not anticipate? Reach out — happy to help you adapt the loop to your estate.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article