Containerize Aspnetcore

ASP.NET Core containerization

Convert an ASP.NET Core project and its containerization settings into Docker-ready Linux artifacts, verify the image builds, and report every configuration choice and remaining blocker.

When to invoke

• "Containerize this ASP.NET Core project."
• "Create a Dockerfile and .dockerignore for this .NET web app."
• "Dockerize my ASP.NET Core API for Linux containers."
• "Make this .NET 8 or .NET 9 app run as a non-root Docker container."
• "Add a Docker health check and verify docker build succeeds."

Containerization settings

Use the user's request and the repository to identify the project path and settings. Defaults apply when the user omits a setting: .NET 8.0, Linux distribution debian, no custom build/run base image, primary HTTP port 8080, ASPNETCORE_URLS=http://+:8080, user $APP_UID, and no extra packages, libraries, tools, copies, volumes, or health check unless specified.

Keep the original settings vocabulary when translating user input: [square brackets], File/directory, Files/directories, [ProjectName (provide path to .csproj file)], [8.0 or 9.0 (Default 8.0)], [Specify base image to use for build stage (Default None)], [Specify base image to use for run stage (Default None)], [e.g., 8080], [List any additional ports, or "None"], [User account, or default to "$APP_UID"], [Specify ASPNETCORE_URLS, or default to "http://+:8080"], [List any specific build steps, or "None"], [Package names for the chosen Linux distribution, or "None"], [Library names and paths, or "None"], [Tool names and versions, or "None"], [Variable names and values, or "Use defaults"], [Paths relative to project root, or "None"], [Container paths, or "Not applicable"], [Paths to exclude, or "None"], [Volume paths for persistent data, or "None"], [List any additional patterns, or "None"], [Health check URL path, or "None"], [Interval and timeout values, or "Use defaults"], [Specific requirements, or "None"], and [Describe any known issues, or "None"]. Mandatory items MUST appear in the final files.

Prerequisites and context

• Docker must be available to run docker build -t aspnetcore-app:latest ..
• The project must contain at least one ASP.NET Core .csproj with TargetFramework or an equivalent user-provided version.
• Use only changes required for Linux Docker container execution: app configuration, Dockerfile, .dockerignore, dependencies, health checks, and container-specific file copies.
• Do not perform infrastructure setup, deployment setup, or unrelated application rewrites.

Procedure

1. Review the containerization settings and discover the target .csproj.
2. Create progress.md in the project directory and update every task from [ ] to [x] as it completes.
3. Determine the .NET version by checking TargetFramework; map net8.0 to 8.0 and net9.0 to 9.0 unless the user overrides it.
4. Select valid Microsoft base images unless custom images are specified. Preserve these documentation sources when choosing tags:
   • SDK image tags: https://github.com/dotnet/dotnet-docker/blob/main/README.sdk.md
   • ASP.NET Core runtime image tags: https://github.com/dotnet/dotnet-docker/blob/main/README.aspnet.md
   • .NET runtime image tags: https://github.com/dotnet/dotnet-docker/blob/main/README.runtime.md
5. Create the Dockerfile in the project root with a build stage and final stage.
6. Create .dockerignore in the project root with the mandatory patterns plus user-specified additional patterns.
7. Add health check support only when an endpoint is specified; install curl or wget only if the selected final image supports and needs it.
8. Verify requirements, run docker build -t aspnetcore-app:latest ., fix build failures, and continue until the image builds or a concrete environmental blocker remains.

Dockerfile rules

FROM mcr.microsoft.com/dotnet/sdk:8.0-bookworm-slim AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["YourProject/YourProject.csproj", "YourProject/"]
COPY ["YourOtherProject/YourOtherProject.csproj", "YourOtherProject/"]
COPY ["NuGet.config", "."]
RUN dotnet restore "YourProject/YourProject.csproj"
COPY . .
WORKDIR "/src/YourProject"
RUN dotnet build "YourProject.csproj" -c $BUILD_CONFIGURATION -o /app/build
RUN dotnet publish "YourProject.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

FROM mcr.microsoft.com/dotnet/aspnet:8.0-bookworm-slim AS final
WORKDIR /app
COPY --from=build /app/publish .
ENV ASPNETCORE_ENVIRONMENT=Production
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1
USER $APP_UID
ENTRYPOINT ["dotnet", "YourProject.dll"]

Use actual values in place of YourProject.csproj, YourProject.dll, YourOtherProject, YourOtherProject/YourOtherProject.csproj, your-connection-string, and your_password. For named stages, AS stage-name enables --from=stage-name; the production stage should still be named final. If the application also needs HTTPS or SSL/TLS, expose the HTTPS port and configure certificates through environment variables or mounted secrets.

Base image selection

All official examples come from the mcr.microsoft.com/dotnet repository family. Distinguish build/publish, pre-build, and post-build steps in the report, and state build success/failure.

.dockerignore minimum

The .dockerignore file must include these patterns plus any additional patterns from settings:

bin/
obj/
.dockerignore
Dockerfile
.git/
.github/
.vs/
.vscode/
**/node_modules/
*.user
*.suo
**/.DS_Store
**/Thumbs.db

Progress tracking

Create and maintain this progress.md structure:

# Containerization Progress

## Environment Detection
- [ ] .NET version detection (version: ___)
- [ ] Linux distribution selection (distribution: ___)

## Configuration Changes
- [ ] Application configuration verification for environment variable support
- [ ] NuGet package source configuration (if applicable)

## Containerization
- [ ] Dockerfile creation
- [ ] .dockerignore file creation
- [ ] Build stage created with SDK image
- [ ] csproj file(s) copied for package restore
- [ ] NuGet.config copied if applicable
- [ ] Runtime stage created with runtime image
- [ ] Non-root user configuration
- [ ] Dependency handling (system packages, native libraries, tools, etc.)
- [ ] Health check configuration (if applicable)
- [ ] Special requirements implementation

## Verification
- [ ] Review containerization settings and make sure that all requirements are met
- [ ] Docker build success

Configuration patterns

Gotchas

• Do not use latest: specific image tags make builds reproducible.
• Do not install build dependencies in the final image: multi-stage builds should keep SDK and tooling out of runtime.
• Do not add curl to chiseled images blindly: chiseled images are minimal and may not support package installation; choose a compatible base or different health check strategy.
• Do not pause for confirmation when the user asked to containerize; proceed methodically until all progress checkboxes are marked or a real blocker is documented.
• Completion is binary: preserve the original rule that you are not DONE UNTIL all CHECKBOXES are MARKED, unless a documented blocker prevents completion.

Output template

## ASP.NET Core containerization result — <project>

**Status:** complete | build failed | blocked
**Project file:** `<path/to/project.csproj>`
**Detected .NET version:** `<8.0|9.0|other>`
**Linux distribution:** `<debian|alpine|ubuntu|chiseled|azurelinux|custom>`
**Base images:** `<sdk image>` → `<runtime image>`

### Files changed
- `Dockerfile`: <summary>
- `.dockerignore`: <summary>
- `progress.md`: <all tasks marked or blocker>
- `<app config file>`: <environment variable support, if changed>

### Settings applied
| Setting | Value |
| --- | --- |
| Ports | `<ports>` |
| User | `<user>` |
| ASPNETCORE_URLS | `<value>` |
| Health check | `<endpoint or none>` |
| Extra packages/libraries/tools | `<list or none>` |
| Volumes/copies | `<list or none>` |

### Validation
- `docker build -t aspnetcore-app:latest .`: pass | fail
- Remaining blocker: <none or exact error>

Quality gate

• The Dockerfile uses multi-stage build and publish, then copies /app/publish into AS final.
• The selected SDK and runtime images match the detected .NET version and requested Linux distribution or custom image settings.
• ASPNETCORE_ENVIRONMENT, ASPNETCORE_URLS, APP_UID, BUILD_CONFIGURATION, and any safe custom variables such as FEATURE_FLAG_ENABLED are handled deliberately.
• .dockerignore includes all mandatory patterns and requested additional patterns.
• Health check, system packages, native libraries, .NET tools, volumes, and extra file copies are implemented only when required.
• No secrets or private feed credentials are baked into the image.
• progress.md exists and all checkboxes are marked [x] or a blocker is documented.
• docker build -t aspnetcore-app:latest . was run and passed, or the exact environmental blocker is reported.

References

• Microsoft .NET SDK image tags
• Microsoft ASP.NET Core runtime image tags
• Microsoft .NET runtime image tags