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

Nota

As únicas exceções a isso são comandos RUN. Devido à forma como os contêineres são criados, eles não podem ser emulados. Se você precisar dessa funcionalidade, talvez considere usar uma do Dockerfile para criar suas imagens de contêiner.

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.

ContainerArchiveOutputPath

Para criar uma imagem de contêiner em um arquivo tar.gz, use a propriedade ContainerArchiveOutputPath. 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.

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:

Parte do nome da imagem	Propriedade MSBuild	Valores de exemplo
REGISTRY[:PORT]	ContainerRegistry	mcr.microsoft.com:443
PORT	ContainerPort	:443
REPOSITORY	ContainerRepository	dotnet/runtime
TAG	ContainerImageTag	8.0
FAMILY	ContainerFamily	-alpine

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 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 relatório de tamanho de imagem do contêiner .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 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 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
• hub do Docker
• 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 .

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.

ContainerImageTag(s)

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.

Importante

Ao usar ContainerImageTags, você acabará com várias imagens, uma por marca exclusiva.

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 um dos seguintes:

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

Nota

Ao usar ContainerImageTags ou qualquer propriedade do MSBuild que precise configurar ; valores delimitados. Se você estiver chamando dotnet publish da linha de comando (como é o caso da maioria dos ambientes de CI/CD), precisará entender as limitações da incapacidade do ambiente de desambiguar delimitadores e aspas, exigindo assim o escape adequado. Isso difere entre o PowerShell e o Bash. Considere os seguintes comandos dotnet publish em seus respectivos ambientes:

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

No PowerShell, os caracteres ; e " precisam ser escapados.

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

No Bash, apenas o " caractere precisa ser escapado.

Isso resulta na geração de duas imagens: my-app:1.2.3-alpha2 e my-app:latest.

Ponta

Se você tiver problemas com a propriedade ContainerImageTags, considere o escopo de uma variável de ambiente ContainerImageTags em vez disso:

$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 rótulos de contêiner padrão.

Configurar a execução do 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 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>

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.

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 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 do .NET.

Nota

No momento, não é possível definir variáveis de ambiente da CLI do .NET ao publicar uma imagem de contêiner. Para obter mais informações, consulte GitHub: compilações de contêiner do SDK do .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 o aplicativo usa um AppHost) ou o comando dotnet mais a DLL do 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 base usam combinações diferentes do contêiner ENTRYPOINT e COMMAND propriedades, e você deseja ser capaz de dar suporte a todas elas. Os padrões devem ser utilizáveis para a maioria dos aplicativos, mas se você quiser personalizar o comportamento de inicialização do aplicativo, deverá:

• 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
• Identificar quais argumentos (se houver) são opcionais e podem ser substituídos por um usuário e defini-los como ContainerDefaultArgs
• Definir ContainerAppCommandInstruction como DefaultArgs

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

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>

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>

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.

Nota

Os itens de configuração ContainerEntrypoint e ContainerEntrypointArgs são preteridos a partir do .NET 8.

Importante

Isso é para usuários avançados, a maioria dos aplicativos não deve precisar personalizar seu ponto de entrada nesse grau. Para obter mais informações e se você quiser fornecer casos de uso para seus cenários, consulte GitHub: o contêiner do SDK do .NET cria discussões.

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>

Ponta

A variável de ambiente APP_UID é usada para definir informações do usuário em seu contêiner. Esse valor pode vir de variáveis de ambiente definidas em sua imagem base (como as imagens do Microsoft .NET) ou você pode defini-lo por meio da sintaxe ContainerEnvironmentVariable.

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

Rótulos de contêiner padrão

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

• org.opencontainers.image.created é definido como 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ótulo existente.

Consulte também

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