Logo
AWS AWS Transform .NET migration Azure

AWS Transform .NET conversion stops or leaves TODOs: unsupported code and dependency failures

Resolve AWS Transform for .NET stopping on a dependency it cannot port, or completing with TODO comments, stubbed code, and a Next Steps file: read what it flagged, understand the known unsupported cases, and finish the parts the agent leaves to you.

Jerzy Kopaczewski ·
AWS Transform for .NET either stops mid-run reporting it cannot port a dependency, or it finishes but leaves TODO comments, stubbed methods, and a Next Steps markdown file. This is not a bug - it is the agent telling you which code it could not convert automatically. This runbook shows how to read what it flagged, which cases are known-unsupported, and how to close the gap.

This runbook is the hands-on companion to our guide on migrating Azure to AWS with AWS Transform, which covers what the tool does and does not automate. For help running a migration end to end, book a consulting session.

Symptoms

The run either halts on a dependency or completes with gaps you have to fill.

# 1. Transformation stops on a dependency it cannot port
AWS Transform stopped: unable to port dependency <ProjectName>.
See the error details for the dependency that caused the failure.

# 2. Completes, but with unconverted code marked in place
// TODO: AWS Transform could not convert this code automatically.
// Manual migration required.

# 3. A Next Steps file is generated listing the manual work
# NextSteps.md  ->  "The following items require manual migration"

Observable impact:

  • The transformation finishes but the ported solution does not build until TODOs are resolved
  • A single low-level dependency stops the whole run (the agent ports bottom-up, lowest dependency first)
  • UI projects or native interop are flagged as not transformed

Cause

AWS Transform ports an application from the lowest-level dependency upward, and it deliberately stops or stubs rather than guessing when it meets code it cannot convert.

  • It works bottom-up and stops on a dependency it cannot port. If a low-level project fails to port, the agent halts the transformation and reports what caused it, because everything above depends on it. One blocking dependency can stop the whole run.
  • Some code is known-unsupported. AWS Transform does not transform Blazor UI components, Win32 DLLs that do not have core-compatible libraries, or repositories that contain no .NET solutions. Code that has no equivalent on AWS is left as TODO comments, stubbed code, or entries in the generated Next Steps file.
  • Environment and version constraints. The .NET agent requires a Windows development machine, and database tooling supports only specific versions (Entity Framework 6.3-6.5 and EF Core 1.0-10.0). Running outside these constraints produces failures that look like conversion errors but are really prerequisites.

Fix

Step 1: Read the Next Steps file and TODO markers first

The agent already told you what it could not do. Collect that before touching code.

# Find the generated Next Steps file in the transformed output
find . -iname "NextSteps*.md" -o -iname "README*transform*.md"

# List every TODO the agent left, with file and line
grep -rn "AWS Transform could not convert" --include="*.cs" .
grep -rn "TODO: Manual migration" --include="*.cs" .

This is your actual worklist. Do not start a manual rewrite before you have read it - most of the remaining effort is enumerated here.

Step 2: If the run stopped, isolate the blocking dependency

A halt means one dependency could not be ported. Because the agent works bottom-up, fix the lowest failing project first and re-run.

# Identify project dependency order (lowest-level first)
dotnet list YourSolution.sln reference

# Inspect the dependency the error named for the known-unsupported cases:
#  - Blazor UI components
#  - Win32 / native interop DLLs without core-compatible libraries
#  - references to Azure SDK packages with no direct AWS equivalent
grep -rln "Microsoft.AspNetCore.Components" --include="*.csproj" .
grep -rln "Azure\." --include="*.csproj" .

Resolve or exclude the blocking project (see Step 3), then restart the transformation so the bottom-up port can proceed past it.

Step 3: Handle the known-unsupported cases deliberately

Each unsupported category has a standard path. Do not expect the agent to convert these.

  • Blazor UI components are not transformed. Port the UI layer separately, or keep it and re-point only the backend. AWS Transform can port ASP.NET UI to ASP.NET Core-compatible frameworks, but Blazor specifically is out of scope.
  • Win32 / native DLLs without core-compatible libraries need a managed replacement or a rework of that interop before the project will run on Linux.
  • Azure SDK calls with no AWS equivalent are stubbed or TODO’d. Swap them to the AWS SDK by hand - for example Azure Blob client to the S3 client, Azure Service Bus to SQS/SNS - which is exactly the service-mapping work the agent cannot infer.

Step 4: Confirm prerequisites before blaming the conversion

Rule out the environment constraints that masquerade as conversion errors.

# The .NET agent requires a Windows development machine
# Confirm your EF version is in the supported range
#   Entity Framework 6.3-6.5, or EF Core 1.0-10.0
dotnet list package | grep -iE "EntityFramework|Microsoft.EntityFrameworkCore"

If the EF version is outside the supported range, align it first; the conversion of data-access code depends on it.

Validation

Confirm the ported solution builds and the flagged work is closed out.

# 1. No unresolved AWS Transform TODOs remain
grep -rc "AWS Transform could not convert" --include="*.cs" . | grep -v ":0$"
# Expected: no output (every flagged TODO resolved)

# 2. The ported solution builds on the target
dotnet build YourSolution.sln -c Release
# Expected: Build succeeded, 0 Error(s)

# 3. The app targets a modern, Linux-capable runtime
dotnet list YourSolution.sln reference >/dev/null && \
  grep -rh "<TargetFramework>" --include="*.csproj" . | sort -u
# Expected: net8.0 / net9.0 (not net48 / netframework)

AWS Transform does the mechanical bulk of a .NET port, but the parts it flags - Blazor UI, native interop, and Azure-to-AWS service mapping - are exactly the architectural decisions that need a human. Treat the Next Steps file as the real scope of the migration’s back half, not an afterthought.

 

Jerzy Kopaczewski

Migrating .NET from Azure to AWS?

Book a free 30-minute call. We run AWS Transform migrations end to end, close out the manual service-mapping work it flags, and get your .NET apps building on Linux.

Book a call