Conteneuriser une application .NET avec dotnet publish

• SDK .NET 8+
  Si .NET est installé, utilisez la commande dotnet --info pour identifier le Kit SDK que vous utilisez.
• Docker Community Edition

• SDK .NET 7+
  Si .NET est installé, utilisez la commande dotnet --info pour identifier le Kit SDK que vous utilisez.
• Docker Community Edition

Ajouter un package NuGet

Le package NuGet Microsoft.NET.Build.Containers est actuellement nécessaire pour publier un projet non-web en tant que conteneur. Pour ajouter le package NuGet Microsoft.NET.Build.Containers au modèle Worker, exécutez la commande dotnet add package suivante :

dotnet add package Microsoft.NET.Build.Containers

Par défaut, le nom de l’image conteneur est le AssemblyName du projet. Si ce nom n’est pas valide comme nom d’image conteneur, vous pouvez le remplacer en spécifiant un ContainerRepository, comme indiqué dans le fichier projet suivant :

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

Pour plus d’informations, consultez ContainerRepository.

Par défaut, le nom de l’image conteneur est le AssemblyName du projet. Si ce nom n’est pas valide comme nom d’image conteneur, vous pouvez le remplacer en spécifiant un ContainerImageName (obsolète) ou le ContainerRepository préféré, comme indiqué dans le fichier projet suivant :

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

Pour plus d’informations, consultez 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

À compter de .NET 8, vous pouvez créer un conteneur directement en tant qu’archive tar.gz. Cette fonctionnalité est utile si votre workflow n’est pas simple et vous oblige, par exemple, à exécuter un outil d’analyse sur vos images avant de les envoyer (push). Une fois l’archive créée, vous pouvez la déplacer, l’analyser ou la charger dans une chaîne d’outils Docker locale.

Pour publier dans une archive, ajoutez la propriété ContainerArchiveOutputPath à votre commande dotnet publish, par exemple :

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

Vous pouvez spécifier un nom de dossier ou un chemin d’accès avec un nom de fichier spécifique. Si vous spécifiez le nom du dossier, le nom de fichier généré pour le fichier d’archive d’images sera $(ContainerRepository).tar.gz. Ces archives peuvent contenir plusieurs étiquettes à l’intérieur, car un seul fichier est créé pour toutes les ContainerImageTags.

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

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

ContainerFamily

À partir de .NET 8, vous pouvez utiliser la propriété MSBuild ContainerFamily pour choisir une autre famille d’images conteneur fournies par Microsoft comme image de base pour votre application. Une fois définie, cette valeur est ajoutée à la fin de l’étiquette spécifique au TFM sélectionnée, en modifiant l’étiquette fournie. Par exemple, pour utiliser les variantes Alpine Linux des images de base .NET, vous pouvez définir ContainerFamily sur alpine :

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

La configuration du projet précédent entraîne une étiquette finale 8.0-alpine pour une application cible .NET 8.

Ce champ est libre et peut souvent être utilisé pour sélectionner différentes distributions de système d’exploitation, configurations de package par défaut ou toute autre saveur des modifications apportées à une image de base. Ce champ est ignoré quand ContainerBaseImage est défini. Pour plus d’informations, consultez Images conteneur .NET.

ContainerRepository

Le référentiel de conteneur est le nom de l’image elle-même, par exemple dotnet/runtime ou my-app. Par défaut, le AssemblyName du projet est utilisé.

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

ContainerImageName

Le nom de l’image conteneur contrôle le nom de l’image elle-même, par exemple dotnet/runtime ou my-app. Par défaut, le AssemblyName du projet est utilisé.

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

À partir de .NET 8, lorsqu’une étiquette n’est pas fournie, la valeur par défaut est latest.

Par défaut, le Version du projet est utilisé comme valeur d’étiquette.

À partir de .NET 8, ContainerPort est déduite lorsqu’elle n’est pas fournie explicitement en fonction de plusieurs variables d’environnement ASP.NET connues :

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

Si ces variables d’environnement sont présentes, leurs valeurs sont analysées et converties en mappages de ports TCP. Ces variables d’environnement sont lues à partir de votre image de base, le cas échéant, ou à partir des variables d’environnement définies dans votre projet via les éléments ContainerEnvironmentVariable. Pour plus d’informations, consultez ContainerEnvironmentVariable.

Toutefois, vous pouvez contrôler la façon dont votre application est exécutée à l’aide d’une combinaison de ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgset ContainerAppCommandInstruction.

Ces différents points de configuration existent car différentes images de base utilisent différentes combinaisons du conteneur ENTRYPOINT et des propriétés COMMAND, et vous souhaitez pouvoir les prendre en charge. Les valeurs par défaut doivent être utilisables pour la plupart des applications, mais si vous souhaitez personnaliser le comportement de lancement de votre application, vous devez :

• Identifier le fichier binaire à exécuter et le définir comme ContainerAppCommand
• Identifier les arguments requis pour que votre application s’exécute et les définir comme ContainerAppCommandArgs
• Identifier les arguments facultatifs (le cas échéant) et qui peuvent être remplacés par un utilisateur et les définir comme ContainerDefaultArgs
• Paramétrez ContainerAppCommandInstruction sur DefaultArgs

Pour plus d’informations, consultez les éléments de configuration suivants.

ContainerAppCommand

L’élément de configuration de la commande d’application est le point d’entrée logique de votre application. Pour la plupart des applications, il s’agit d’AppHost, le fichier binaire exécutable généré pour votre application. Si votre application ne génère pas d’AppHost, cette commande est généralement dotnet <your project dll>. Ces valeurs sont appliquées après n’importe quel ENTRYPOINT dans votre conteneur de base, ou directement si aucun ENTRYPOINT n’est défini.

La configuration ContainerAppCommand a une propriété Include unique, qui représente la commande, l’option ou l’argument à utiliser dans la commande 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

Cet élément de configuration d’arguments de commande d’application représente tous les arguments logiquement requis pour votre application qui doivent être appliqués à ContainerAppCommand. Par défaut, aucun n’est généré pour une application. Lorsqu’il sont présents, les arguments sont appliqués à votre conteneur lorsqu’il est exécuté.

La configuration ContainerAppCommandArgs a une propriété unique Include, qui représente l’option ou l’argument à appliquer à la commande 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

Cet élément de configuration d’arguments par défaut représente tous les arguments remplçables par l’utilisateur pour votre application. Il s’agit d’un bon moyen de fournir des valeurs par défaut que votre application peut avoir besoin d’exécuter de manière à faciliter le démarrage, mais toujours facile à personnaliser.

La configuration ContainerDefaultArgs a une propriété unique Include, qui représente l’option ou l’argument à appliquer à la commande 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

La configuration des instructions de commande d’application permet de contrôler la façon dont ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgs, et ContainerDefaultArgs sont combinés pour former la commande finale exécutée dans le conteneur. Cela dépend considérablement de si un ENTRYPOINT est présent dans l’image de base. Cette propriété peut prendre une des trois valeurs : "DefaultArgs", "Entrypoint", ou "None".

• Entrypoint:
  • Dans ce mode, le point d’entrée est défini par ContainerAppCommand, ContainerAppCommandArgs, et ContainerDefaultArgs.
• None :
  • Dans ce mode, le point d’entrée est défini par ContainerEntrypoint, ContainerEntrypointArgs, et ContainerDefaultArgs.
• DefaultArgs :
  • Il s’agit du mode le plus complexe. Si aucun des éléments ContainerEntrypoint[Args] n’est présent, ContainerAppCommand[Args] et ContainerDefaultArgs sont utilisés pour créer le point d’entrée et la commande. Le point d’entrée de l’image de base pour les images de base qui ont été codées en dur vers dotnet ou /usr/bin/dotnet est ignoré afin que vous disposiez d’un contrôle total.
  • Si ContainerEntrypoint et ContainerAppCommand sont présents, alors ContainerEntrypoint devient le point d’entrée et ContainerAppCommand devient la commande.

ContainerUser

La propriété de configuration utilisateur contrôle l’utilisateur par défaut sur lequel le conteneur s’exécute. Il est souvent utilisé pour exécuter le conteneur en tant qu’utilisateur non-racine, ce qui est une bonne pratique pour la sécurité. Il existe quelques contraintes à connaître pour cette configuration :

• Elle peut prendre différentes formes : nom d’utilisateur, identifiant utilisateur Linux, nom du groupe, identifiant de groupe Linux, username:groupname, et autres variantes d’identifiant.
• Il n’y a pas de vérification de l’existence de l’utilisateur ou du groupe spécifié sur l’image.
• La modification de l’utilisateur peut modifier le comportement de l’application, en particulier en ce qui concerne les éléments tels que les autorisations du Système de fichiers.

La valeur par défaut de ce champ varie selon le TFM du projet et le système d’exploitation cible :

• Si vous ciblez .NET 8 ou une version ultérieure et que vous utilisez les images de runtime Microsoft, alors :
  • sur Linux, l’utilisateur sans racine app est utilisé (bien qu’il soit référencé par son identifiant utilisateur)
  • sur Windows, l’utilisateur sans racine ContainerUser est utilisé
• Sinon, aucun ContainerUser par défaut n’est utilisé

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

Toutefois, vous pouvez contrôler la façon dont votre application est exécutée à l’aide de ContainerEntrypoint et ContainerEntrypointArgs.

ContainerEntrypoint

Le point d’entrée du conteneur peut être utilisé pour personnaliser le ENTRYPOINT du conteneur, qui est l’exécutable appelé au démarrage du conteneur. Par défaut, pour les builds qui créent un hôte d’application, il est défini comme ContainerEntrypoint. Pour les builds qui ne créent pas d’exécutable, le dotnet path/to/app.dll est utilisé comme ContainerEntrypoint.

Le nœud ContainerEntrypoint a un attribut unique :

• Include : commande, option ou argument à utiliser dans la commande ContainerEntrypoint.

Par exemple, considérez l’exemple suivant de groupe d’éléments de projet .NET :

<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

Le nœud args du point d’entrée du conteneur contrôle les arguments par défaut fournis au ContainerEntrypoint. Il doit être utilisé lorsque le ContainerEntrypoint est un programme que l’utilisateur peut vouloir utiliser seul. Par défaut, aucun ContainerEntrypointArgs n’est créé en votre nom.

Le nœud ContainerEntrypointArg a un attribut unique :

• Include : option ou argument à appliquer à la commande ContainerEntrypoint.

Considérez l’exemple suivant de groupe d’éléments de projet .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>