Contentorizar uma referência de aplicação .NET

Neste artigo de referência, você aprenderá a configurar a imagem de contêiner gerada quando você publica um aplicativo .NET como um contêiner. Este artigo aborda as várias propriedades que você pode definir para controlar a imagem, o ambiente de execução e os comandos que são executados quando o contêiner é iniciado.

Configurar imagem de contêiner

Você pode controlar muitos aspetos do contêiner gerado por meio das propriedades do MSBuild. Em geral, se você pode usar um comando em um Dockerfile para definir alguma configuração, você pode fazer o mesmo via MSBuild.

Não é possível executar comandos RUN com o SDK do .NET. Esses comandos são frequentemente usados para instalar alguns pacotes do sistema operacional ou criar um novo usuário do sistema operacional, ou qualquer número de coisas arbitrárias. Se você quiser continuar usando o recurso de criação de contêiner do SDK do .NET, poderá criar uma imagem base personalizada com essas alterações e, em seguida, usar essa imagem base. Para obter mais informações, consulte ContainerBaseImage.

ContainerArchiveOutputPath

Para criar uma imagem de contêiner dentro de um arquivo tar.gz, use a propriedade ContainerArchiveOutputPath. 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 propriedade ContainerArchiveOutputPath 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á nomeado $(ContainerRepository).tar.gz. Esses arquivos podem conter várias tags dentro deles, apenas como um único arquivo é criado para todos os ContainerImageTags.

Configuração de nomenclatura de imagem de contêiner

As imagens de contêiner seguem uma convenção de nomenclatura específica. O nome da imagem é composto por várias partes, o registro, porta opcional, repositório e tag opcional e família.

REGISTRY[:PORT]/REPOSITORY[:TAG[-FAMILY]]

Por exemplo, considere o nome da imagem mcr.microsoft.com/dotnet/runtime:8.0-alpine totalmente qualificado:

• mcr.microsoft.com é o registro (e, neste caso, representa o registro de contêiner da Microsoft).
• dotnet/runtime é o repositório (mas alguns consideram isso o user/repository).
• 8.0-alpine é a tag e a família (a família é um especificador opcional que ajuda a desambiguar o empacotamento do sistema operacional).

Algumas propriedades descritas nas seções a seguir correspondem ao gerenciamento de partes do nome da imagem gerada. Considere a tabela a seguir que mapeia a relação entre o nome da imagem e as propriedades de compilação:

As seções a seguir descrevem as várias propriedades que podem ser usadas para controlar a imagem de contêiner gerada.

ContainerBaseImage

A propriedade container base image controla a imagem usada como base para sua imagem. Por padrão, os seguintes valores são inferidos com base nas propriedades do seu projeto:

• Se o seu projeto for independente, a imagem mcr.microsoft.com/dotnet/runtime-deps será usada como imagem base.
• Se o seu projeto for um projeto ASP.NET Core, a imagem mcr.microsoft.com/dotnet/aspnet será usada como imagem base.
• Caso contrário, a imagem mcr.microsoft.com/dotnet/runtime é usada como imagem base.

A tag da imagem é inferida como sendo o componente numérico do TargetFrameworkescolhido. Por exemplo, um projeto direcionado a net6.0 resulta na tag 6.0 da imagem base inferida e um projeto net7.0-linux usa a tag 7.0 e assim por diante.

Se você definir um valor aqui, deverá definir o nome totalmente qualificado da imagem para usar como base, incluindo qualquer tag de sua preferência:

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

Com o .NET SDK versão 8.0.200, a inferência de ContainerBaseImage é melhorada para otimizar o tamanho e a segurança:

• Direcionando os identificadores de tempo de execução linux-musl-x64 ou linux-musl-arm64, escolhe automaticamente as variantes de imagem alpine para garantir que seu projeto seja executado:
  • Se o projeto usa PublishAot=true então a nightly/runtime-depsjammy-chiseled-aot variante da imagem base para melhor tamanho e segurança.
  • Se o projeto usar InvariantGlobalization=false, as variantes de -extra serão usadas para garantir que a localização ainda funcione.

Para obter mais informações sobre os tamanhos e características das variantes de imagem, consulte .NET 8.0 Container Image Size Report.

ContainerFamily

A partir do .NET 8, você pode usar a propriedade ContainerFamily 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 é 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 para alpine:

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

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

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 de sabor de alterações em uma imagem base. Este campo é ignorado quando ContainerBaseImage é definido. Para obter mais informações, consulte imagens de contêiner .NET.

ContainerRuntimeIdentifier(s)

A propriedade ContainerRuntimeIdentifier especifica o sistema operacional e a arquitetura do contêiner se o ContainerBaseImage oferecer suporte a várias plataformas. Por exemplo, a imagem mcr.microsoft.com/dotnet/runtime suporta linux-x64, linux-arm, linux-arm64e win10-x64. Por padrão, isso é definido como o RuntimeIdentifier usado ao publicar o contêiner. Normalmente, você não precisa definir essa propriedade explicitamente; Em vez disso, use a opção -r com o comando dotnet publish. Se a imagem escolhida não suportar o RuntimeIdentifierespecificado, um erro indica os identificadores suportados.

Você sempre pode definir a propriedade ContainerBaseImage como um nome de imagem totalmente qualificado, incluindo a tag , para evitar a necessidade de usar essa propriedade.

<PropertyGroup>
    <ContainerRuntimeIdentifier>linux-arm64</ContainerRuntimeIdentifier>
</PropertyGroup>

Para especificar vários identificadores de tempo de execução de contêiner para imagens de várias arquiteturas, use um conjunto delimitado por ponto-e-vírgula de identificadores de tempo de execução na propriedade ContainerRuntimeIdentifiers, semelhante à configuração de vários TargetFrameworks:

<PropertyGroup>
    <ContainerRuntimeIdentifiers>linux-x64;linux-arm64</ContainerRuntimeIdentifiers>
</PropertyGroup>

Para obter mais informações sobre os identificadores de tempo de execução suportados pelo .NET, consulte catálogo RID.

ContainerRegistry

A propriedade do registro de contêiner controla o registro de destino, o local para o qual a imagem recém-criada será enviada. Por padrão, ele é enviado por push para o daemon Docker local, mas você também pode especificar um registro remoto. Ao usar um registro remoto que requer autenticação, você autentica usando os mecanismos de docker login conhecidos. Para obter mais informações, consulte autenticação em registros de contêiner para obter mais detalhes. Para obter um exemplo concreto de uso dessa propriedade, considere o seguinte exemplo XML:

<PropertyGroup>
    <ContainerRegistry>registry.mycorp.com:1234</ContainerRegistry>
</PropertyGroup>

Esta ferramenta suporta a publicação em qualquer registo que suporte o Docker Registry HTTP API V2. Isto inclui os seguintes registos explicitamente (e provavelmente muitos mais implicitamente):

• Registro de Contêiner do Azure
• de registro do Amazon Elastic Container
• de Registro de Artefatos do Google
• do Docker Hub
• Pacotes GitHub
• Registro de contêiner hospedado no GitLab
• Quay.io

Para obter notas sobre como trabalhar com esses registros, consulte o notas específicas do registro.

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>

Os nomes das imagens consistem em um ou mais segmentos delimitados por barras, cada um dos quais só pode conter caracteres alfanuméricos minúsculos, pontos, sublinhados e traços, e devem começar com uma letra ou número. Quaisquer outros caracteres resultam em um erro sendo lançado.

ContainerImageTag(s)

A propriedade container image tag controla as tags geradas para a imagem. Para especificar uma única tag use ContainerImageTag e para várias tags use ContainerImageTags.

As tags geralmente são usadas para se referir a diferentes versões de um aplicativo, mas também podem se referir a diferentes distribuições do sistema operacional ou até mesmo configurações diferentes.

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

Para substituir o padrão, especifique uma das seguintes opções:

<PropertyGroup>
    <ContainerImageTag>1.2.3-alpha2</ContainerImageTag>
</PropertyGroup>

Para especificar várias tags, use um conjunto de tags delimitado por ponto-e-vírgula na propriedade ContainerImageTags, semelhante à configuração de várias TargetFrameworks:

<PropertyGroup>
    <ContainerImageTags>1.2.3-alpha2;latest</ContainerImageTags>
</PropertyGroup>

As tags só podem conter até 127 caracteres alfanuméricos, pontos, sublinhados e traços. Devem começar com um caractere alfanumérico ou um sublinhado. Qualquer outro formulário resulta em um erro sendo lançado.

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=`"1.2.3-alpha2`;latest`"

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=\"1.2.3-alpha2;latest\"

$Env:ContainerImageTags='1.2.3;latest'; dotnet publish --os linux --arch x64 /t:PublishContainer

ContainerLabel

O rótulo do contêiner adiciona um rótulo de metadados ao contêiner. Os rótulos são frequentemente usados para armazenar metadados de versão e criação para uso por scanners de segurança e outras ferramentas de infraestrutura. Você pode especificar qualquer número de rótulos de contêiner.

O nó ContainerLabel tem dois atributos:

• Include: A chave do rótulo.
• Value: O valor do rótulo (pode estar vazio).

<ItemGroup>
    <ContainerLabel Include="org.contoso.businessunit" Value="contoso-university" />
</ItemGroup>

Para obter uma lista de rótulos criados por padrão, consulte rótulos de contêiner padrão.

Configurar a execução de contêiner

Para controlar a execução do contêiner, você pode usar as seguintes propriedades do MSBuild.

ContainerWorkingDirectory

O nó do diretório de trabalho do contêiner controla o diretório de trabalho do contêiner, o diretório no qual os comandos são executados se nenhum outro comando for executado.

Por padrão, o valor do diretório /app é usado como o diretório de trabalho.

<PropertyGroup>
    <ContainerWorkingDirectory>/bin</ContainerWorkingDirectory>
</PropertyGroup>

ContainerPort

A porta do contêiner adiciona portas TCP (Transmission Control Protocol) ou UDP (User Datagram Protocol) à lista de portas conhecidas para o contêiner. Isso permite que tempos de execução de contêineres, como o Docker, mapeiem essas portas para a máquina host automaticamente. Isso geralmente é usado como documentação para o contêiner, mas também pode ser usado para habilitar o mapeamento automático de portas.

O nó ContainerPort tem dois atributos:

• Include: O número da porta a ser exposta.
• Type: O padrão é tcp, os valores válidos são tcp ou udp.

<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

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 através de itens ContainerEnvironmentVariable. Para obter mais informações, consulte ContainerEnvironmentVariable.

ContainerEnvironmentVariable

O nó da variável de ambiente do contêiner permite adicionar variáveis de ambiente ao contêiner. As variáveis de ambiente são acessíveis ao aplicativo em execução no contêiner imediatamente e geralmente são usadas para alterar o comportamento em tempo de execução do aplicativo em execução.

O nó ContainerEnvironmentVariable tem dois atributos:

• Include: O nome da variável de ambiente.
• Value: O valor da variável de ambiente.

<ItemGroup>
  <ContainerEnvironmentVariable Include="LOGGER_VERBOSITY" Value="Trace" />
</ItemGroup>

Para obter mais informações, consulte variáveis de ambiente .NET.

Configurar comandos de contêiner

Por padrão, as ferramentas de contêiner iniciam seu aplicativo usando o binário AppHost gerado para seu aplicativo (se seu aplicativo usa um AppHost) ou o comando dotnet mais a DLL do seu aplicativo.

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

Esses diferentes pontos de configuração existem porque diferentes imagens de base usam combinações diferentes do ENTRYPOINT do contêiner e COMMAND propriedades, e 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
• Definir ContainerAppCommandInstruction para 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 é dotnet <your project dll>. Esses valores são aplicados após qualquer ENTRYPOINT em seu contêiner de base ou diretamente se nenhum ENTRYPOINT for definido.

A configuração ContainerAppCommand tem uma única propriedade Include, 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 args do comando do aplicativo 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 configuração ContainerAppCommandArgs tem uma única propriedade Include, que representa a opção ou 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

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 configuração ContainerDefaultArgs tem uma única propriedade Include, que representa a opção ou 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ções de comando do aplicativo ajuda a controlar a maneira como os ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgse ContainerDefaultArgs são combinados para formar o comando 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 itens ContainerEntrypoint[Args] estiver presente, o ContainerAppCommand[Args] e o ContainerDefaultArgs serão usados para criar o ponto de entrada e o comando. O ponto de entrada da imagem base para imagens base que a codificam para dotnet ou /usr/bin/dotnet é ignorado para que você tenha controle total.
  • Se ContainerEntrypoint e ContainerAppCommand estiverem presentes, ContainerEntrypoint se tornará o ponto de entrada e ContainerAppCommand se tornará 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-root, 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, username:groupnamee outras variantes de ID.
• 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 sistema de arquivos permissões.

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 app de usuário sem raiz é usado (embora seja referenciado por seu ID de usuário)
  • no Windows, o ContainerUser de usuário sem raiz é usado
• Caso contrário, nenhum ContainerUser padrão será usado

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

Para configurar seu aplicativo para ser executado como um usuário raiz, defina a propriedade ContainerUser como root. No arquivo de projeto, adicione o seguinte:

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

Como alternativa, você pode definir esse valor ao chamar dotnet publish a partir da linha de comando:

dotnet publish -p ContainerUser=root

Rótulos de contêiner padrão

Os rótulos são frequentemente usados para fornecer metadados consistentes em imagens de contêiner. Este pacote fornece alguns rótulos padrão para incentivar uma melhor manutenção das imagens geradas.

• org.opencontainers.image.created é definido para o formato ISO 8601 do valor atual de DateTime.UtcNow.

Para obter mais informações, consulte Implementar rótulos convencionais sobre a infraestrutura de rótulos existente.

Ver também

• Containerize um aplicativo .NET com dotnet publish
• imagens de contêiner .NET