Colocar em contêiner um aplicativo .NET com dotnet publish

• SDK do .NET 8+
  Se você tiver o .NET instalado, use o comando dotnet --info para determinar qual SDK está usando.
• Docker Community Edition

• SDK do .NET 7+
  Se você tiver o .NET instalado, use o comando dotnet --info para determinar qual SDK está usando.
• Docker Community Edition

Adicionar pacote NuGet

No momento, o pacote NuGet Microsoft.NET.Build.Containers é necessário para publicar projetos que não sejam da Web como um contêiner. Para adicionar o pacote NuGet Microsoft.NET.Build.Containers ao modelo de trabalho, execute o seguinte comando dotnet add package:

dotnet add package Microsoft.NET.Build.Containers

Por padrão, o nome da imagem de contêiner é o AssemblyName do projeto. Se esse nome for inválido como um nome de imagem de contêiner, substitua-o especificando ContainerRepository, conforme mostrado no seguinte arquivo de projeto:

<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>

Para obter mais informações, confira ContainerRepository.

Por padrão, o nome da imagem de contêiner é o AssemblyName do projeto. Se esse nome for inválido como um nome de imagem de contêiner, você poderá substituí-lo especificando um (ContainerImageName obsoleto) ou o preferido ContainerRepository, conforme mostrado no seguinte arquivo do projeto:

<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="7.0.1" />
    <PackageReference Include="Microsoft.NET.Build.Containers" Version="7.0.401" />
  </ItemGroup>
</Project>

Para obter mais informações, confira ContainerImageName.

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

A partir do .NET 8, você pode criar um contêiner diretamente como um arquivo tar.gz. Esse recurso será útil se o fluxo de trabalho não for simples e exigir que você, por exemplo, execute uma ferramenta de verificação em suas imagens antes de efetuar push delas. Depois que o arquivo é criado, você pode movê-lo, examiná-lo ou carregá-lo em uma cadeia de ferramentas local do Docker.

Para publicar em um arquivo morto, adicione a propriedade ContainerArchiveOutputPath ao seu comando dotnet publish, por exemplo:

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

Você pode especificar um nome de pasta ou um caminho com um nome de arquivo específico. Se você especificar o nome da pasta, o nome do arquivo gerado para o arquivo de imagem será $(ContainerRepository).tar.gz. Esses arquivos podem conter várias tags dentro deles, apenas como um único arquivo é criado para todos os arquivos ContainerImageTags.

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

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

ContainerFamily

A partir do .NET 8, você pode usar a propriedade ContainerFamily do MSBuild para escolher uma família diferente de imagens de contêiner fornecidas pela Microsoft como a imagem base para seu aplicativo. Quando definido, esse valor é acrescentado ao final da marca específica do TFM selecionado, alterando a marca fornecida. Por exemplo, para usar as variantes do Alpine Linux das imagens base do .NET, defina ContainerFamily como alpine:

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

A configuração do projeto anterior resulta em uma marca final igual a 8.0-alpine para um aplicativo direcionado ao .NET 8.

Esse campo é de forma livre e, em geral, pode ser usado para selecionar diferentes distribuições do sistema operacional, configurações de pacote padrão ou qualquer outra variante de alterações em uma imagem base. Esse campo é ignorado quando ContainerBaseImage é definido. Para obter mais informações, consulte imagens de contêiner do .NET.

ContainerRepository

O repositório de contêiner é o nome da própria imagem, por exemplo, dotnet/runtime ou my-app. Por padrão, o AssemblyName do projeto é usado.

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

ContainerImageName

O nome da imagem de contêiner controla o nome da própria imagem, por exemplo, dotnet/runtime ou my-app. Por padrão, o AssemblyName do projeto é usado.

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

A partir do .NET 8, quando uma marca não é fornecida, o padrão é latest.

Por padrão, o Version do projeto é usado como o valor da tag.

A partir do .NET 8, a ContainerPort é inferida quando não é fornecida explicitamente com base em diversas variáveis de ambiente conhecidas do ASP.NET:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

Se essas variáveis de ambiente estiverem presentes, os respectivos valores serão analisados e convertidos em mapeamentos de porta TCP. Essas variáveis de ambiente são lidas da imagem base, se houver, ou das variáveis de ambiente definidas no projeto por meio de itens ContainerEnvironmentVariable. Para obter mais informações, confira ContainerEnvironmentVariable.

No entanto, você pode controlar como o aplicativo é executado usando uma combinação de ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgs e ContainerAppCommandInstruction.

Esses diferentes pontos de configuração existem porque imagens base diferentes usam combinações distintas do contêiner ENTRYPOINT e das propriedades COMMAND, e o ideal é conseguir dar suporte a todas elas. Os padrões devem ser utilizáveis na maioria dos aplicativos, mas caso deseje personalizar o comportamento de inicialização do aplicativo, você deve:

• Identificar o binário a ser executado e defini-lo como ContainerAppCommand
• Identificar quais argumentos são obrigatórios para que o aplicativo seja executado e defini-los como ContainerAppCommandArgs
• Identificar quais argumentos (se houver) são opcionais e podem ser substituídos por um usuário e defini-los como ContainerDefaultArgs
• Defina ContainerAppCommandInstruction como DefaultArgs

Para obter mais informações, confira os itens de configuração a seguir.

ContainerAppCommand

O item de configuração do comando do aplicativo é o ponto de entrada lógico do aplicativo. Na maioria dos aplicativos, esse é o AppHost, o binário executável gerado para o aplicativo. Se o aplicativo não gerar um AppHost, esse comando normalmente será dotnet <your project dll>. Esses valores são aplicados após qualquer ENTRYPOINT no contêiner base ou diretamente se nenhum ENTRYPOINT foi definido.

A configuração ContainerAppCommand tem uma propriedade Include individual, que representa o comando, a opção ou o argumento a ser usado no comando de ponto de entrada:

<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

Esse item de configuração de argumentos do comando do aplicativo representa todos os argumentos logicamente necessários para o aplicativo que devem ser aplicados ao ContainerAppCommand. Por padrão, não é gerado nenhum para um aplicativo. Quando presentes, os argumentos são aplicados ao contêiner quando ele é executado.

A configuração ContainerAppCommandArgs tem uma propriedade Include individual, que representa a opção ou o argumento a ser aplicado ao comando ContainerAppCommand.

<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

Esse item de configuração de argumentos padrão representa todos os argumentos substituíveis pelo usuário para o aplicativo. Essa é uma boa maneira de fornecer padrões dos quais o aplicativo poderá precisar para ser executado de uma forma que facilite a inicialização, mas ainda seja fácil de personalizar.

A configuração ContainerDefaultArgs tem uma propriedade Include individual, que representa a opção ou o argumento a ser aplicado ao comando ContainerAppCommand.

<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

A configuração de instrução do comando do aplicativo ajuda a controlar a maneira como ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgs e ContainerDefaultArgs são combinados para formar o comando final que é executado no contêiner. Isso depende muito de um ENTRYPOINT estar presente na imagem base. Essa propriedade usa um destes três valores: "DefaultArgs", "Entrypoint" ou "None".

• Entrypoint:
  • Nesse modo, o ponto de entrada é definido por ContainerAppCommand, ContainerAppCommandArgs e ContainerDefaultArgs.
• None:
  • Nesse modo, o ponto de entrada é definido por ContainerEntrypoint, ContainerEntrypointArgs e ContainerDefaultArgs.
• DefaultArgs:
  • Esse é o modo mais complexo, caso nenhum dos itens ContainerEntrypoint[Args] esteja presente, ContainerAppCommand[Args] e ContainerDefaultArgs são usados para criar o ponto de entrada e o comando. O ponto de entrada para as imagens base que o têm codificado em dotnet ou /usr/bin/dotnet é ignorado, para que você tenha controle completo.
  • Se ContainerEntrypoint e ContainerAppCommand estiverem presentes, ContainerEntrypoint passará a ser o ponto de entrada e ContainerAppCommand passará a ser o comando.

ContainerUser

A propriedade de configuração do usuário controla o usuário padrão como o qual o contêiner é executado. Em geral, isso é usado para executar o contêiner como um usuário não raiz, o que é uma melhor prática de segurança. Há algumas restrições a essa configuração das quais você deve estar ciente:

• Ela pode assumir várias formas: nome de usuário, IDs de usuário do Linux, nome do grupo, ID de grupo do Linux, username:groupname e outras variantes de ID.
• Não há nenhuma verificação de que o usuário ou o grupo especificado existe na imagem.
• A alteração o usuário pode alterar o comportamento do aplicativo, especialmente em relação a itens como permissões do sistema de arquivos.

O valor padrão desse campo varia de acordo com o TFM do projeto e o sistema operacional de destino:

• Se o destino for o .NET 8 ou versão superior e você estiver usando as imagens de runtime da Microsoft:
  • no Linux, o usuário sem raiz app é usado (embora seja referenciado pela identificação de usuário)
  • no Windows, o usuário sem raiz ContainerUser é usado
• Caso contrário, nenhum ContainerUser padrão é usado

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

No entanto, você pode controlar como seu aplicativo é executado usando ContainerEntrypoint e ContainerEntrypointArgs.

ContainerEntrypoint

O ponto de entrada do contêiner pode ser usado para personalizar o ENTRYPOINT do contêiner, que é o executável chamado quando o contêiner é iniciado. Por padrão, para builds que criam um host de aplicativo, ele é definido como o ContainerEntrypoint. Para builds que não criam um executável, o dotnet path/to/app.dll é usado como o ContainerEntrypoint.

O nó ContainerEntrypoint tem um único atributo:

• Include: o comando, a opção ou o argumento a ser usado no comando ContainerEntrypoint.

Por exemplo, considere o seguinte grupo de itens de projeto .NET de exemplo:

<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

O nó args do ponto de entrada do contêiner controla os argumentos padrão fornecidos para o ContainerEntrypoint. Isso deve ser usado quando o ContainerEntrypoint é um programa que o usuário pode querer usar por conta própria. Por padrão, nenhum ContainerEntrypointArgs é criado em seu nome.

O nó ContainerEntrypointArg tem um único atributo:

• Include: a opção ou o argumento a ser aplicado ao comando ContainerEntrypoint.

Considere o seguinte grupo de itens de projeto .NET de exemplo:

<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>