.NET Windows containers on App Service
Rehost a selected Windows web workload with minimal behavior change. Keep modernization optional and separately approved. Use the Windows hosting reference for first-party evidence and concrete platform checks.
When to invoke
- "Move this legacy .NET app to a Windows container on App Service."
- "Rehost our IIS/Web Forms application without rewriting it."
- "Prepare an existing Windows container for Azure App Service."
Windows is a deliberate destination
- Preserve the existing application model for rehosting. Modern .NET is not a prerequisite.
- A .NET Framework application remains a Windows workload. ACA is not a Windows-container destination.
- Match the .NET Framework runtime, Windows base, IIS dependencies, and compatible Windows build host.
- Service eligibility is separate from container startup: validate the Windows-container plan/SKU, region, networking, identity, and state requirements before declaring App Service a fit.
- Windows services, desktop UI, domain joining, COM licensing, native drivers, and machine-level dependencies need explicit assessment; a custom container is not an unrestricted VM replacement.
Prerequisites and context
- A reviewed result from
dotnet-modernization-assessment(skill), selected entry application, and legacy characterization baseline. - A compatible Windows container engine/runner for real build and startup verification. On macOS or Linux, perform static preparation only and report Windows tests as not run.
- Existing build tools appropriate to the project: legacy MSBuild/NuGet where required, not a blind
substitution of
dotnet build. - Azure subscription/resource IDs, capacity checks, and permission are needed only for authorized cloud validation or deployment, not for authoring a proposal.
Procedure
- Reconfirm that the selected path is rehosting. Record out-of-scope framework, database, and UI changes.
- Reproduce the existing build and tests. Identify IIS sites, bindings, app pools, required Windows features, publish artifacts, transforms, native dependencies, and authentication assumptions.
- Select a documented supported base and record its resolved digest and runtime. Inspect an existing Dockerfile before modifying it; do not replace it wholesale. If creating one, use the official ASP.NET Framework image appropriate to the tested application and copy only sanitized published artifacts. Retain the image's IIS service-monitor startup unless a tested requirement changes it.
- Build on the compatible Windows runner. Test startup, a representative route, static files, authentication, authorization, session continuity, serialization, and dependent-service access. Avoid copying source, credentials, signing keys, or private NuGet configuration into runtime layers.
- Prepare reviewable App Service configuration using the existing IaC convention. Specify a Windows-container-capable plan, selected image, port, health endpoint, identity, network/DNS paths, storage, diagnostics, and rollout mechanism. Query live SKU/region availability only when authorized.
- Configure registry pull through managed identity and an appropriate least-privilege role. Verify registry network reachability and authentication settings without enabling admin credentials or weakening policy. Separate registry pull permission from application data-access permission.
- Run the image/port check owned by
dotnet-modernization-assessment(skill). Validate real listening behavior, startup time, restart, scale-out, persistent state, certificate access, and logs separately. - Stop at prepared unless deployment is authorized. For an authorized deployment, use available Azure preparation/validation/deployment skills or a reviewed official workflow. Test a lower environment first, then use approved slots or blue/green where supported and verified.
- Keep the previous image/configuration available. Verify the agreed rollback and data compatibility before switching production traffic; do not delete the old environment as automatic cleanup.
Limits
- No automatic provisioning, image push, production cutover, database migration, or deletion.
- Do not claim zero downtime or slot support without testing the selected configuration.
- If Windows-specific dependencies prevent App Service hosting, return a blocker and an alternative platform decision instead of forcing ACA or Linux.
- Hand runtime/Linux migration to
dotnet-linux-modernization(skill) as a separate scope.
Output template
## Windows App Service rehost
**Status:** prepared | deployed-and-verified | blocked
**Application/revision:**
**Preserved framework and app model:**
**Windows base/runtime/digest:**
### Configuration
- Windows build runner and host compatibility:
- Plan/SKU/region and evidence:
- IIS/listener, health checks, identity, network, state, and diagnostics:
### Validation
| Check | Evidence | Result or blocker |
| --- | --- | --- |
### Release
- Authorized actions performed:
- Rollout and rollback:
- Deferred modernization:
- Official sources and verification date:
Quality gate
- Rehosting did not silently expand into a framework or app-model rewrite.
- The selected Windows base and App Service eligibility have fresh first-party evidence.
- Legacy build and Windows-container runtime tests ran or are explicitly blocked.
- Identity, network, ports, state, and scale-out behavior were tested at the claimed level.
- No credential, source secret, or private key entered a runtime image or report.
- Deployment and production changes were explicitly authorized; rollback remains available.