Containerize a .NET app with dotnet publish

• .NET 8+ SDK
  If you have .NET installed, use the dotnet --info command to determine which SDK you're using.
• Docker Community Edition

• .NET 7+ SDK
  If you have .NET installed, use the dotnet --info command to determine which SDK you're using.
• Docker Community Edition

Add NuGet package

Starting with .NET SDK version 8.0.200, the PublishContainer target is available for every project. To avoid depending on the Microsoft.NET.Build.Containers NuGet package, ensure that you're using the latest .NET SDK version. Additionally, your project file needs to have IsPublishable set to true and enable SDK container support.

To enable SDK container support, set the EnableSdkContainerSupport property to true in your project file.

<PropertyGroup>
  <IsPublishable>true</IsPublishable>
  <EnableSdkContainerSupport>true</EnableSdkContainerSupport>
</PropertyGroup>

You need to reference the required Microsoft.NET.Build.Containers NuGet package to publish non-web projects as a container. To add the Microsoft.NET.Build.Containers NuGet package to the worker template, run the following dotnet add package command:

dotnet add package Microsoft.NET.Build.Containers

By default, the container image name is the AssemblyName of the project. If that name is invalid as a container image name, you can override it by specifying a ContainerRepository as shown in the following project file:

<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UserSecretsId>dotnet-DotNet.ContainerImage-2e40c179-a00b-4cc9-9785-54266210b7eb</UserSecretsId>
    <ContainerRepository>dotnet-worker-image</ContainerRepository>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </ItemGroup>
</Project>

For more information, see ContainerRepository.

By default, the container image name is the AssemblyName of the project. If that name is invalid as a container image name, you can override it by specifying a (ContainerImageName obsolete) or the preferred ContainerRepository as shown in the following project file:

<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UserSecretsId>dotnet-DotNet.ContainerImage-2e40c179-a00b-4cc9-9785-54266210b7eb</UserSecretsId>
    <ContainerImageName>dotnet-worker-image</ContainerImageName>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    <PackageReference Include="Microsoft.NET.Build.Containers" Version="7.0.410" />
  </ItemGroup>
</Project>

For more information, see ContainerImageName.

dotnet publish --os linux --arch x64 /t:PublishContainer

The preceding .NET CLI command publishes the app as a container:

• Targeting Linux as the OS (--os linux).
• Specifying an x64 architecture (--arch x64).

dotnet publish --os linux --arch x64 /t:PublishContainer -c Release

The preceding .NET CLI command publishes the app as a container:

• Targeting Linux as the OS (--os linux).
• Specifying an x64 architecture (--arch x64).
• Using the release configuration (-c Release).

Determining projects to restore...
  All projects are up-to-date for restore.
  DotNet.ContainerImage -> .\Worker\bin\Release\net8.0\linux-x64\DotNet.ContainerImage.dll
  DotNet.ContainerImage -> .\Worker\bin\Release\net8.0\linux-x64\publish\
  Building image 'dotnet-worker-image' with tags latest on top of base image mcr.microsoft.com/dotnet/aspnet:8.0
  Pushed container 'dotnet-worker-image:latest' to Docker daemon

Determining projects to restore...
  All projects are up-to-date for restore.
  DotNet.ContainerImage -> .\Worker\bin\Release\net7.0\linux-x64\DotNet.ContainerImage.dll
  DotNet.ContainerImage -> .\Worker\bin\Release\net7.0\linux-x64\publish\
  Building image 'dotnet-worker-image' with tags 1.0.0 on top of base image mcr.microsoft.com/dotnet/aspnet:7.0
  Pushed container 'dotnet-worker-image:1.0.0' to Docker daemon

ContainerArchiveOutputPath

Starting in .NET 8, you can create a container directly as a tar.gz archive. This feature is useful if your workflow isn't straightforward and requires that you, for example, run a scanning tool over your images before pushing them. Once the archive is created, you can move it, scan it, or load it into a local Docker toolchain.

To publish to an archive, add the ContainerArchiveOutputPath property to your dotnet publish command, for example:

dotnet publish \
  -p PublishProfile=DefaultContainer \
  -p ContainerArchiveOutputPath=./images/sdk-container-demo.tar.gz

You can specify either a folder name or a path with a specific file name. If you specify the folder name, the filename generated for the image archive file will be $(ContainerRepository).tar.gz. These archives can contain multiple tags inside them, only as single file is created for all ContainerImageTags.

<PropertyGroup>
    <ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:8.0</ContainerBaseImage>
</PropertyGroup>

Starting with .NET SDK version 8.0.200, the ContainerBaseImage inference has been improved to optimize the size and security:

• Targeting the linux-musl-x64 or linux-musl-arm64 Runtime Identifiers, automatically chooses the alpine image variants to ensure your project runs:
  • If the project uses PublishAot=true then the nightly/runtime-deps jammy-chiseled-aot variant of the base image for best size and security.
  • If the project uses InvariantGlobalization=false then the -extra variants is used to ensure localization still works.

For more information regarding the image variants sizes and characteristics, see .NET 8.0 Container Image Size Report.

<PropertyGroup>
    <ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:7.0</ContainerBaseImage>
</PropertyGroup>

ContainerFamily

Starting with .NET 8, you can use the ContainerFamily MSBuild property to choose a different family of Microsoft-provided container images as the base image for your app. When set, this value is appended to the end of the selected TFM-specific tag, changing the tag provided. For example, to use the Alpine Linux variants of the .NET base images, you can set ContainerFamily to alpine:

<PropertyGroup>
    <ContainerFamily>alpine</ContainerFamily>
</PropertyGroup>

The preceding project configuration results in a final tag of 8.0-alpine for a .NET 8-targeting app.

This field is free-form, and often can be used to select different operating system distributions, default package configurations, or any other flavor of changes to a base image. This field is ignored when ContainerBaseImage is set. For more information, see .NET container images.

ContainerRepository

The container repository is the name of the image itself, for example, dotnet/runtime or my-app. By default, the AssemblyName of the project is used.

<PropertyGroup>
    <ContainerRepository>my-app</ContainerRepository>
</PropertyGroup>

ContainerImageName

The container image name controls the name of the image itself, for example, dotnet/runtime or my-app. By default, the AssemblyName of the project is used.

<PropertyGroup>
    <ContainerImageName>my-app</ContainerImageName>
</PropertyGroup>

Starting with .NET 8, when a tag isn't provided the default is latest.

By default, the Version of the project is used as the tag value.

Starting with .NET 8, the ContainerPort is inferred when not explicitly provided based on several well-known ASP.NET environment variables:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

If these environment variables are present, their values are parsed and converted to TCP port mappings. These environment variables are read from your base image, if present, or from the environment variables defined in your project through ContainerEnvironmentVariable items. For more information, see ContainerEnvironmentVariable.

However, you can control how your app is executed by using some combination of ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgs, and ContainerAppCommandInstruction.

These different configuration points exist because different base images use different combinations of the container ENTRYPOINT and COMMAND properties, and you want to be able to support all of them. The defaults should be useable for most apps, but if you want to customize your app launch behavior you should:

• Identify the binary to run and set it as ContainerAppCommand
• Identify which arguments are required for your application to run and set them as ContainerAppCommandArgs
• Identify which arguments (if any) are optional and could be overridden by a user and set them as ContainerDefaultArgs
• Set ContainerAppCommandInstruction to DefaultArgs

For more information, see the following configuration items.

ContainerAppCommand

The app command configuration item is the logical entry point of your app. For most apps, this is the AppHost, the generated executable binary for your app. If your app doesn't generate an AppHost, then this command will typically be dotnet <your project dll>. These values are applied after any ENTRYPOINT in your base container, or directly if no ENTRYPOINT is defined.

The ContainerAppCommand configuration has a single Include property, which represents the command, option, or argument to use in the entrypoint command:

<ItemGroup Label="ContainerAppCommand Assignment">
  <!-- This is how you would start the dotnet ef tool in your container -->
  <ContainerAppCommand Include="dotnet" />
  <ContainerAppCommand Include="ef" />

  <!-- This shorthand syntax means the same thing, note the semicolon separating the tokens. -->
  <ContainerAppCommand Include="dotnet;ef" />
</ItemGroup>

ContainerAppCommandArgs

This app command args configuration item represents any logically required arguments for your app that should be applied to the ContainerAppCommand. By default, none are generated for an app. When present, the args are applied to your container when it's run.

The ContainerAppCommandArgs configuration has a single Include property, which represents the option or argument to apply to the ContainerAppCommand command.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above, 
       this would be the way to force the database to update.
  -->
  <ContainerAppCommandArgs Include="database" />
  <ContainerAppCommandArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerAppCommandArgs Include="database;update" />
</ItemGroup>

ContainerDefaultArgs

This default args configuration item represents any user-overridable arguments for your app. This is a good way to provide defaults that your app might need to run in a way that makes it easy to start, yet still easy to customize.

The ContainerDefaultArgs configuration has a single Include property, which represents the option or argument to apply to the ContainerAppCommand command.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above, 
       this would be the way to force the database to update.
  -->
  <ContainerDefaultArgs Include="database" />
  <ContainerDefaultArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerDefaultArgs Include="database;update" />
</ItemGroup>

ContainerAppCommandInstruction

The app command instruction configuration helps control the way the ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgs, and ContainerDefaultArgs are combined to form the final command that is run in the container. This depends greatly on if an ENTRYPOINT is present in the base image. This property takes one of three values: "DefaultArgs", "Entrypoint", or "None".

• Entrypoint:
  • In this mode, the entrypoint is defined by ContainerAppCommand, ContainerAppCommandArgs, and ContainerDefaultArgs.
• None:
  • In this mode, the entrypoint is defined by ContainerEntrypoint, ContainerEntrypointArgs, and ContainerDefaultArgs.
• DefaultArgs:
  • This is the most complex mode—if none of the ContainerEntrypoint[Args] items are present, the ContainerAppCommand[Args] and ContainerDefaultArgs are used to create the entrypoint and command. The base image entrypoint for base images that have it hard-coded to dotnet or /usr/bin/dotnet is skipped so that you have complete control.
  • If both ContainerEntrypoint and ContainerAppCommand are present, then ContainerEntrypoint becomes the entrypoint, and ContainerAppCommand becomes the command.

ContainerUser

The user configuration property controls the default user that the container runs as. This is often used to run the container as a non-root user, which is a best practice for security. There are a few constraints for this configuration to be aware of:

• It can take various forms—username, linux user ids, group name, linux group id, username:groupname, and other ID variants.
• There's no verification that the user or group specified exists on the image.
• Changing the user can alter the behavior of the app, especially in regards to things like File System permissions.

The default value of this field varies by project TFM and target operating system:

• If you're targeting .NET 8 or higher and using the Microsoft runtime images, then:
  • on Linux the rootless user app is used (though it's referenced by its user ID)
  • on Windows the rootless user ContainerUser is used
• Otherwise, no default ContainerUser is used

<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

To configure your app to run as a root user, set the ContainerUser property to root. In your project file, add the following:

<PropertyGroup>
  <ContainerUser>root</ContainerUser>
</PropertyGroup>

Alternatively, you can set this value when calling dotnet publish from the command line:

dotnet publish -p ContainerUser=root

However, you can control how your app is executed by using ContainerEntrypoint and ContainerEntrypointArgs.

ContainerEntrypoint

The container entry point can be used to customize the ENTRYPOINT of the container, which is the executable that is called when the container is started. By default, for builds that create an app host, it's set as the ContainerEntrypoint. For builds that don't create an executable, the dotnet path/to/app.dll is used as the ContainerEntrypoint.

The ContainerEntrypoint node has a single attribute:

• Include: The command, option, or argument to use in the ContainerEntrypoint command.

For example, consider the following sample .NET project item group:

<ItemGroup Label="Entrypoint Assignment">
  <!-- This is how you would start the dotnet ef tool in your container -->
  <ContainerEntrypoint Include="dotnet" />
  <ContainerEntrypoint Include="ef" />

  <!-- This shorthand syntax means the same thing.
       Note the semicolon separating the tokens. -->
  <ContainerEntrypoint Include="dotnet;ef" />
</ItemGroup>

ContainerEntrypointArgs

The container entry point args node controls the default arguments provided to the ContainerEntrypoint. This should be used when the ContainerEntrypoint is a program that the user might want to use on its own. By default, no ContainerEntrypointArgs are created on your behalf.

The ContainerEntrypointArg node has a single attribute:

• Include: The option or argument to apply to the ContainerEntrypoint command.

Consider the following example .NET project item group:

<ItemGroup>
  <!-- Assuming the ContainerEntrypoint defined above,
       this would be the way to update the database by
       default, but let the user run a different EF command. -->
  <ContainerEntrypointArgs Include="database" />
  <ContainerEntrypointArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerEntrypointArgs Include="database;update" />
</ItemGroup>