.NET SDK Container Publishing

When to Use This Skill

Use this skill when:

• You want a container image for a .NET service and do not want to hand-write a Dockerfile
• You want to know how to tag, name, or expose ports on an SDK-built image without a Dockerfile
• You are wiring container publishing into CI / CD or a release pipeline
• An SDK-built image pushes to the wrong registry, gets the wrong tag, or picks the wrong base image
• You need a tarball of an image for scanning or air-gapped loading

Do not use it when:

• You need a RUN step or arbitrary layer customization in the image. The SDK tooling cannot emulate RUN; write a Dockerfile instead.

What This Is

Since .NET 7, dotnet publish builds a container image natively. The Microsoft.NET.Build.Containers tooling ships with the SDK, so no Dockerfile is required and no Docker install is needed to produce an image. Docker or Podman is only required to run the image locally. This is documented in the containerize with dotnet publish tutorial.

The quickest path is one command:

dotnet publish /t:PublishContainer -c Release

That compiles the app and emits an image in one step. The image name defaults to the project's AssemblyName. Override it with ContainerRepository (renamed from ContainerImageName in earlier versions - see the sdk-container-builds customization notes).

The Three Output Modes

The tooling writes the image in one of three ways. Pick based on where the image ends up.

See the containerize a .NET app reference for the full property surface.

Key Facts

• No Docker required to build. The SDK creates the image itself; a runtime is only needed to run it. See the SDK publish tutorial.
• Image name defaults to AssemblyName. Set ContainerRepository to override.
• Base image is inferred. Self-contained projects get mcr.microsoft.com/dotnet/runtime-deps, ASP.NET Core gets dotnet/aspnet, other apps get dotnet/runtime, tagged for the TFM. Since SDK 8.0.200 the inference is size and security aware: musl RIDs pick Alpine variants, PublishAot=true picks the chiseled AOT runtime-deps variant. See the base image inference notes.
• Since .NET 8, the SDK tags images latest when you do not set a tag. If your publish relies on the version tag you must set ContainerImageTag (single tag) or ContainerImageTags (list) explicitly. This is a real footgun in CI - see the tag drift entry in references/troubleshooting.md.
• Windows images need an explicit base image. Microsoft no longer includes Windows variants in the manifest list. To target Windows, set ContainerBaseImage to a specific nanoserver tag (for example mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-ltsc2022). See the Windows note.
• Multi-architecture images come from ContainerRuntimeIdentifiers (semicolon-delimited, a subset of RuntimeIdentifiers). The output is an OCI image index. Supported from SDK 8.0.405, 9.0.102, and 9.0.2xx onward.
• Insecure registries are passed via the DOTNET_CONTAINER_INSECURE_REGISTRIES env var (comma-separated) starting in SDK 9.0.100. Since .NET 8.0.400 the SDK reads standard Docker / Podman config to decide HTTP vs HTTPS.

The Minimal Property Set (the pattern we use)

Most of our services only override what they need and let the SDK infer the rest. A minimal csproj looks like this:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ContainerRepository>my-service</ContainerRepository>
    <ContainerImageTags>$(VersionPrefix);latest</ContainerImageTags>
  </PropertyGroup>

  <ItemGroup>
    <ContainerPort Include="8080" Type="tcp" />
  </ItemGroup>
</Project>

Notes:

• No ContainerRegistry, no ContainerBaseImage, no ContainerUser. The SDK defaults these correctly for most ASP.NET services.
• ContainerPort items expose ports without a Dockerfile.
• Tags follow semver: the package version plus a floating latest - but only when $(VersionPrefix) is set before this file is evaluated (on the command line, in Directory.Build.props, or earlier in the project file). The SDK applies its 1.0.0 default after the project body, so a plain local publish resolves $(VersionPrefix) to empty and tags the image latest only. See the VersionPrefix ordering entry in references/troubleshooting.md.

For the full property catalog, see references/property-reference.md.

CI / CD Publishing

In CI, publish against a registry and tag with the release name. The tag-driven pattern we use:

dotnet publish src/MyService/MyService.csproj \
  -p:VersionPrefix=${{ github.ref_name }} \
  -p:ContainerRegistry=docker.example.internal \
  -c Release /t:PublishContainer

-p:VersionPrefix feeds the ContainerImageTags list set in the project, so the image is tagged with the release name and latest. Do not also pass -p:ContainerImageTag - the SDK rejects ContainerImageTag and ContainerImageTags together (CONTAINER2008). See references/ci-cd.md for the full workflow and registry auth notes.

If you centralize image settings across a repo, put them in a Directory.Build.props with CI conditionals. We do this for version tags and labels. See references/real-world-examples.md.

Troubleshooting

The common failures (tag drift, wrong image name or registry, unavailable RUN, no daemon on the build host, insecure registry rejection, multi-RID publish races, and multi-target publishing) are covered in depth in references/troubleshooting.md. In short: set your tag (ContainerImageTag or ContainerImageTags) explicitly, set ContainerRepository and ContainerRegistry explicitly, and use ContainerArchiveOutputPath when no daemon is available.

Tag drift

Symptom: Your pipeline publishes an image but you cannot find the version you expect, only latest.

Cause: Since .NET 8, when neither ContainerImageTag nor ContainerImageTags is set, the SDK tags the image latest instead of $(Version). VersionPrefix stamps the assembly version but not the image tag.

Fix: Set ContainerImageTag (single tag) or ContainerImageTags (list) explicitly in the publish step.

Wrong image name or registry

Symptom: The image pushes somewhere unexpected.

Cause: The SDK derives the repository name from AssemblyName and pushes to the local daemon by default.

Fix: Set ContainerRepository and ContainerRegistry explicitly.

RUN unavailable

Symptom: You need to run a command inside the image and the SDK will not do it.

Cause: The SDK tooling cannot execute RUN steps without a Dockerfile.

Fix: Use a custom base image via ContainerBaseImage, or write a Dockerfile.

No daemon on the build host

Symptom: Publishing fails because no Docker / Podman daemon is reachable.

Cause: The default output mode pushes to a local daemon, which must be present.

Fix: Set ContainerArchiveOutputPath to write a tarball instead. No daemon needed.

For more, see references/troubleshooting.md.

Self-Contained and AOT

Self-contained projects default to the runtime-deps base image. AOT projects get a chiseled AOT runtime-deps variant for smaller, more secure images. See references/self-contained-and-aot.md.

Verification

Confirm the image built and exists:

# Image in the local daemon
docker images | grep <repository>

# Tarball produced
ls -la <ContainerArchiveOutputPath>

# Push succeeded (registry mode)
docker pull <ContainerRegistry>/<ContainerRepository>:<tag>

Related Skills

• dotnet-skills:testcontainers - running containers in tests
• dotnet-skills:aot-trimming - AOT and trimming, relevant to base-image selection