Contentorizar uma aplicação .NET com dotnet publish

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

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

Adicionar pacote NuGet

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

dotnet add package Microsoft.NET.Build.Containers

Por padrão, o nome da imagem do 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 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, consulte ContainerRepository.

Por padrão, o nome da imagem do 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 de 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, consulte 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 é útil se o fluxo de trabalho não for simples e exigir que você, por exemplo, execute uma ferramenta de digitalização sobre suas imagens antes de enviá-las. Depois que o arquivo é criado, você pode movê-lo, digitalizá-lo ou carregá-lo em uma cadeia de ferramentas local do Docker.

Para publicar em um arquivo, adicione a ContainerArchiveOutputPath propriedade ao 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 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 MSBuild para escolher uma família diferente de imagens de contêiner fornecidas pela Microsoft como a ContainerFamily imagem base para seu aplicativo. Quando definido, esse valor é anexado ao final da tag específica do TFM selecionada, alterando a tag fornecida. Por exemplo, para usar as variantes do Alpine Linux das imagens base do .NET, você pode definir ContainerFamily como alpine:

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

A configuração do projeto anterior resulta em uma marca final de para um aplicativo de destino .NET 8.8.0-alpine

Este campo é de forma livre e muitas vezes pode ser usado para selecionar diferentes distribuições do sistema operacional, configurações de pacote padrão ou qualquer outro tipo de alterações em uma imagem base. Este campo é ignorado quando ContainerBaseImage é definido. Para obter mais informações, consulte Imagens de contêiner .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 do 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 tag não é fornecida, o padrão é latest.

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

A partir do .NET 8, o ContainerPort é inferido quando não é fornecido explicitamente com base em várias variáveis de ambiente ASP.NET bem conhecidas:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

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

No entanto, você pode controlar como seu aplicativo é executado usando alguma combinação de ContainerAppCommand, , ContainerDefaultArgsContainerAppCommandArgse ContainerAppCommandInstruction.

Esses diferentes pontos de configuração existem porque diferentes imagens de base usam combinações diferentes do contêiner ENTRYPOINT e das propriedades, e COMMAND você deseja ser capaz de suportar todos eles. Os padrões devem ser utilizáveis para a maioria dos aplicativos, mas se você quiser personalizar o comportamento de inicialização do aplicativo, deve:

• Identifique o binário a ser executado e defina-o como ContainerAppCommand
• Identifique quais argumentos são necessários para que seu aplicativo seja executado e defina-os como ContainerAppCommandArgs
• Identifique quais argumentos (se houver) são opcionais e podem ser substituídos por um usuário e defina-os como ContainerDefaultArgs
• Defina ContainerAppCommandInstruction como DefaultArgs

Para obter mais informações, consulte os seguintes itens de configuração.

ContainerAppCommand

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

A ContainerAppCommand configuração tem uma única Include propriedade, que representa o comando, opção ou argumento a ser usado no comando entrypoint:

<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

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

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

<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

Este item de configuração args padrão representa quaisquer argumentos substituíveis pelo usuário para seu aplicativo. Essa é uma boa maneira de fornecer padrões que seu aplicativo pode precisar executar de uma forma que facilite a inicialização, mas ainda assim fácil de personalizar.

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

<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ções de comando do aplicativo ajuda a controlar a maneira como o , , ContainerAppCommand, ContainerAppCommandArgsContainerEntrypointArgse ContainerDefaultArgs são combinados para formar o ContainerEntrypointcomando final que é executado no contêiner. Isso depende muito se um ENTRYPOINT está presente na imagem base. Esta propriedade usa um dos três valores: "DefaultArgs", , "Entrypoint"ou "None".

• Entrypoint:
  • Neste modo, o ponto de entrada é definido por ContainerAppCommand, ContainerAppCommandArgse ContainerDefaultArgs.
• None:
  • Neste modo, o ponto de entrada é definido por ContainerEntrypoint, ContainerEntrypointArgse ContainerDefaultArgs.
• DefaultArgs:
  • Este é o modo mais complexo — se nenhum dos ContainerEntrypoint[Args] itens estiver presente, o e será usado para criar o ponto de entrada e ContainerDefaultArgs o ContainerAppCommand[Args] comando. O ponto de entrada da imagem base para imagens base que a codificam ou /usr/bin/dotnet são ignoradas para dotnet que você tenha controle total.
  • Se ambos ContainerEntrypoint estiverem ContainerAppCommand presentes, então ContainerEntrypoint torna-se o ponto de entrada e ContainerAppCommand torna-se o comando.

ContainerUser

A propriedade de configuração do usuário controla o usuário padrão no qual o contêiner é executado. Isso geralmente é usado para executar o contêiner como um usuário não raiz, o que é uma prática recomendada para segurança. Há algumas restrições para essa configuração estar ciente:

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

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

• Se você estiver direcionando o .NET 8 ou superior e usando as imagens de tempo de execução da Microsoft, então:
  • no Linux o usuário sem raiz é usado (embora seja referenciado por seu ID de usuário app )
  • no Windows o usuário ContainerUser sem raiz é usado
• Caso contrário, nenhum padrão ContainerUser será 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 que é chamado quando o contêiner é iniciado. Por padrão, para compilações que criam um host de aplicativo, ele é definido como o ContainerEntrypoint. Para compilações que não criam um executável, o é usado como o dotnet path/to/app.dllContainerEntrypoint.

O ContainerEntrypoint nó tem um único atributo:

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

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 ao ContainerEntrypoint. Isso deve ser usado quando o é um programa que o ContainerEntrypoint usuário pode querer usar por conta própria. Por padrão, não ContainerEntrypointArgs são criados em seu nome.

O ContainerEntrypointArg nó tem um único atributo:

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

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

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