Como colocar em contêiner uma referência de aplicativo .NET

Neste artigo de referência, você aprenderá a configurar a imagem de contêiner gerada ao publicar 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 propriedades de contêiner

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

Não há como executar comandos RUN com o SDK do .NET. Esses comandos geralmente são usados para instalar alguns pacotes do sistema operacional ou criar um novo usuário do sistema operacional ou qualquer número de itens arbitrários. Se você quiser continuar usando o recurso de construçã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.

Sinalizadores que controlam a imagem base

As propriedades a seguir controlam qual imagem base é usada para seu contêiner e como ela é selecionada:

• ContainerBaseImage
• ContainerFamily
• ContainerRuntimeIdentifier(s)

ContainerBaseImage

A propriedade de imagem base do contêiner 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 projeto for autocontido, a imagem mcr.microsoft.com/dotnet/runtime-deps será usada como a imagem base.
• Se o projeto for um projeto do ASP.NET Core, a imagem mcr.microsoft.com/dotnet/aspnet será usada como a imagem base.
• Caso contrário, a imagem mcr.microsoft.com/dotnet/runtime será usada como a imagem base.

A marca da imagem é inferida para ser o componente numérico do TargetFrameworkescolhido. Por exemplo, um projeto direcionado net6.0 resulta na marca 6.0 da imagem base inferida e um projeto net7.0-linux usa a marca 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 marca que preferir:

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

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

• Direcionando os identificadores linux-musl-x64 ou linux-musl-arm64 Runtime, escolhe automaticamente as variantes de imagem alpine para garantir que o projeto seja executado:
  • Se o projeto usa PublishAot=true então a variante nightly/runtime-depsjammy-chiseled-aot da imagem base para obter o 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 o Relatório de Tamanho da Imagem de Contêiner do .NET 8.0.

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 do aplicativo. Quando definido, esse valor é acrescentado ao final da marca específica de TFM selecionada, alterando a marca fornecida. Por exemplo, para usar as variantes alpinas do 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 do .NET 8.

Esse campo é de forma livre e geralmente pode ser usado para selecionar diferentes distribuições do sistema operacional, configurações de pacote padrão ou qualquer outra 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.

ContainerRuntimeIdentifier(s)

A propriedade ContainerRuntimeIdentifier especifica o sistema operacional e a arquitetura do contêiner se o ContainerBaseImage der suporte a várias plataformas. Por exemplo, a imagem mcr.microsoft.com/dotnet/runtime dá suporte a 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 der suporte à RuntimeIdentifierespecificada, um erro indicará os identificadores com suporte.

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

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

Para especificar vários identificadores de runtime de contêiner para imagens de várias arquiteturas, use um conjunto delimitado por ponto-e-vírgula de identificadores de runtime 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 runtime compatíveis com o .NET, consulte o catálogo RID.

Imagens de várias arquiteturas

As imagens de várias arquiteturas permitem que uma única imagem de contêiner dê suporte a várias arquiteturas, simplificando o desenvolvimento e a implantação multiplataforma. O SDK do .NET dá suporte a isso por meio da ContainerRuntimeIdentifiers propriedade.

A partir das versões do SDK 8.0.405, 9.0.102 e 9.0.2xx, há suporte para publicação de contêiner multi-RID. Ao publicar com /t:PublishContainer:

• Se um único RuntimeIdentifier ou ContainerRuntimeIdentifier for especificado, um contêiner de arquitetura única será gerado como antes.
• Se nenhum único RuntimeIdentifier for especificado, mas vários RuntimeIdentifiers ou ContainerRuntimeIdentifiers forem definidos, o SDK publicará o aplicativo para cada RID especificado e combinará as imagens resultantes em um Índice de Imagem OCI. Esse índice permite que várias imagens específicas da arquitetura compartilhem um único nome.

Esse recurso simplifica os fluxos de trabalho de contêiner em ambientes de arquitetura misturada. Por exemplo, um desenvolvedor em um linux-x64 host pode publicar um contêiner que dá suporte a ambos linux-x64 e linux-arm64habilitar a implantação para a arquitetura sem alterar nomes ou rótulos de imagem.

O Índice de Imagem OCI gerado é amplamente compatível com ferramentas de contêiner modernas, aprimorando a compatibilidade e a facilidade de uso.

Sinalizadores que controlam metadados independentes de imagem gerada

As seguintes propriedades controlam metadados e a configuração que se aplicam à imagem de contêiner gerada, independentemente do identificador de runtime de destino:

• ContainerImageFormat
• ContainerImageTag
• ContainerLabel
• ContainerRepository

ContainerImageFormat

Você pode usar a ContainerImageFormat propriedade MSBuild para especificar o formato de imagem como um Docker ou OCI. Por padrão, a ferramenta .NET infere o formato da imagem base. Por exemplo, as imagens base do .NET usam o formato application/vnd.docker.distribution.manifest.v2+jsonespecífico do Docker. No entanto, muitas ferramentas modernas preferem o formato application/vnd.oci.image.manifest.v1+jsonOCI. Para forçar um formato específico, defina a propriedade conforme mostrado:

<PropertyGroup>
  <ContainerImageFormat>OCI</ContainerImageFormat>
</PropertyGroup>

Ambos os formatos são em grande parte intercambiáveis sem perda de informações.

ContainerImageTag

A propriedade de marca de imagem de contêiner controla as marcas geradas para a imagem. Para especificar uma única marca, use ContainerImageTag e, para várias marcas, use ContainerImageTags.

As marcas 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 a configurações diferentes.

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

Para substituir o padrão, especifique uma das seguintes propriedades:

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

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

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

As marcas só podem conter até 127 caracteres alfanuméricos, períodos, sublinhados e traços. Eles devem começar com um caractere alfanumérico ou um sublinhado. Qualquer outro formulário resulta em um erro sendo gerado.

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 de contêiner adiciona um rótulo de metadados ao contêiner. Os rótulos geralmente são 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 os rótulos de contêiner padrão.

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 de imagem consistem em um ou mais segmentos delimitados por barra, cada um deles pode conter apenas caracteres alfanuméricos minúsculos, períodos, sublinhados e traços e deve começar com uma letra ou número. Quaisquer outros caracteres resultam em um erro sendo gerado.

Sinalizadores que controlam metadados de execução

As propriedades a seguir controlam o comportamento de execução específico do runtime e a geração de imagens de várias arquiteturas:

• ContainerAppCommand
• ContainerAppCommandArgs
• ContainerAppCommandInstruction
• ContainerDefaultArgs
• ContainerEnvironmentVariable
• ContainerPort
• ContainerPublishInParallel
• ContainerUser
• ContainerWorkingDirectory

ContainerAppCommand

O item de configuração de 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 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 for definido.

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

Este item de configuração de args de 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 contêiner quando ele é executado.

A configuração de 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>

ContainerAppCommandInstruction

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

• Entrypoint:
  • Nesse modo, o ponto de entrada é definido por ContainerAppCommand, ContainerAppCommandArgse ContainerDefaultArgs.
• None:
  • Nesse modo, o ponto de entrada é definido por ContainerEntrypoint, ContainerEntrypointArgse ContainerDefaultArgs.
• DefaultArgs:
  • Esse é o modo mais complexo, se nenhum dos itens de ContainerEntrypoint[Args] estiver presente, o ContainerAppCommand[Args] e ContainerDefaultArgs serão usados para criar o ponto de entrada e o comando. O ponto de entrada de imagem base para imagens base que o têm embutido em código para dotnet ou /usr/bin/dotnet é ignorado para que você tenha controle completo.
  • Se ContainerEntrypoint e ContainerAppCommand estiverem presentes, ContainerEntrypoint se tornará o ponto de entrada e ContainerAppCommand se tornará o comando.

ContainerDefaultArgs

Esse item de configuração de 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 maneira que facilite o início, mas ainda assim fácil de personalizar.

A configuração de 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>

ContainerEnvironmentVariable

O nó de variável de ambiente de contêiner permite que você adicione 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 de runtime 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 do .NET.

ContainerPort

A porta de contêiner adiciona portas TCP (Protocolo de Controle de Transmissão) ou UDP (User Datagram Protocol) à lista de portas conhecidas do contêiner. Isso permite que runtimes de contêiner como o Docker mapeiem essas portas para o computador 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 porta.

O nó ContainerPort tem dois atributos:

• Include: o número da porta a ser exposto.
• Type: padrões para 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 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 presentes, ou das variáveis de ambiente definidas em seu projeto por meio de itens ContainerEnvironmentVariable. Para obter mais informações, consulte ContainerEnvironmentVariable.

ContainerPublishInParallel

Para contêineres multi-RID, determinados tipos de projeto (como Blazor WebAssembly) podem encontrar condições de corrida de build. Para resolver isso, começando com as versões do SDK do .NET 8.0.408, 9.0.300 e 10.0, você pode controlar o paralelismo do processo de publicação usando a ContainerPublishInParallel propriedade. Por padrão, a publicação ocorre em paralelo para cada RID (Identificador de Runtime). Definir essa propriedade para garantir a false publicação sequencial, o que aumenta a estabilidade, mas pode levar mais tempo.

<PropertyGroup>
  <ContainerPublishInParallel>false</ContainerPublishInParallel>
</PropertyGroup>

Para obter mais informações sobre a publicação multi-RID, consulte ContainerRuntimeIdentifier(s).

ContainerUser

A propriedade de configuração do usuário controla o usuário padrão como o 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 a segurança. Há algumas restrições para que essa configuração esteja ciente de:

• Ele pode usar vários formulários: nome de usuário, IDs de usuário linux, nome de grupo, ID do grupo linux, username:groupnamee outras variantes de ID.
• Não há nenhuma verificação de que o usuário ou grupo especificado exista na imagem.
• Alterar o usuário pode alterar o comportamento do aplicativo, especialmente em relação a itens como permissões de 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 você estiver direcionando o .NET 8 ou superior e usando as imagens de runtime da Microsoft, então:
  • no Linux, o usuário sem raiz app é usado (embora seja referenciado por sua 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 da linha de comando:

dotnet publish -p ContainerUser=root

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 não houver outro comando executado.

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

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

Sinalizadores que controlam o destino da imagem gerada

O seguinte controle de propriedades em que a imagem de contêiner gerada é armazenada ou publicada:

• ContainerArchiveOutputPath
• ContainerRegistry
• LocalRegistry

ContainerArchiveOutputPath

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

ContainerRegistry

A propriedade do registro de contêiner controla o registro de destino, o local para o qual a imagem recém-criada deve ser enviada por push. Por padrão, ele é enviado por push para o daemon local do Docker, mas você também pode especificar um registro remoto. Ao usar um registro remoto que requer autenticação, você se 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 como usar essa propriedade, considere o seguinte exemplo XML:

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

Essa ferramenta dá suporte à publicação em qualquer registro que dê suporte ao de API HTTP do Registro do Docker V2. Isso inclui os seguintes registros explicitamente (e provavelmente muitos mais implicitamente):

• Registro de Contêiner do Azure
• do Registro de Contêiner Elástico do Amazon
• do Registro de Artefatos do Google
• Docker Hub
• Pacotes do GitHub
• Registro de Contêiner hospedado no GitLab
• Quay.io

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

LocalRegistry

A LocalRegistry propriedade MSBuild especifica as ferramentas de contêiner locais a serem usadas ao enviar por push para fontes locais. Os valores com suporte são docker e podman. Se não estiver definido, o SDK determinará a ferramenta com base na disponibilidade:

• Se ambos docker e podman existirem, e docker for um alias para podman, então podman será usado.
• Se existir apenas docker , docker será usado.
• Se existir apenas podman , podman será usado.
• Se nenhum dos dois existir, um erro será gerado.

Para definir explicitamente a ferramenta de registro local, use a seguinte configuração:

<PropertyGroup>
  <LocalRegistry>podman</LocalRegistry>
</PropertyGroup>

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, a porta opcional, o repositório e a marca e a família opcionais.

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

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

• mcr.microsoft.com é o registro (e, nesse 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 marca 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 build:

Rótulos de contêiner padrão

Os rótulos geralmente são usados para fornecer metadados consistentes em imagens de contêiner. As ferramentas de contêiner internas fornecem alguns rótulos padrão para aumentar a qualidade das imagens geradas. Toda a geração de rótulo padrão pode ser desabilitada definindo ContainerGenerateLabels como false. Além disso, cada rótulo padrão tem um sinalizador de habilitação individual que pode ser definido para false desabilitar esse rótulo específico.

Sempre que possível, as propriedades existentes do MSBuild fornecem os valores para esses rótulos. Outras propriedades permitem o controle explícito de seus valores.

Consulte também

• Conteinerizar um aplicativo .NET com a publicação dotnet
• Imagens de contêiner do .NET