Containerisieren einer .NET-App mit dem Befehl „dotnet publish“

• .NET 8+ SDK
  Wenn Sie .NET installiert haben, verwenden Sie den Befehl dotnet --info, um festzustellen, welches SDK Sie verwenden.
• Docker Community Edition

• SDK für .NET ab Version 7
  Wenn Sie .NET installiert haben, verwenden Sie den Befehl dotnet --info, um festzustellen, welches SDK Sie verwenden.
• Docker Community Edition

Hinzufügen des NuGet-Pakets

Das NuGet-Paket Microsoft.NET.Build.Containers ist derzeit erforderlich, um ein Webprojekt als Container zu veröffentlichen. Zum Hinzufügen des NuGet-Pakets Microsoft.NET.Build.Containers zur Workervorlage führen Sie den folgenden Befehl dotnet add package aus:

dotnet add package Microsoft.NET.Build.Containers

Standardmäßig ist der Name des Containerimages der AssemblyName des Projekts. Wenn dieser Name als Containerimagename ungültig ist, können Sie ihn überschreiben, indem Sie einen ContainerRepository wie in der folgenden Projektdatei angeben:

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

Weitere Informationen finden Sie unter ContainerRepository.

Standardmäßig ist der Name des Containerimages der AssemblyName des Projekts. Wenn dieser Name als Containerimagename ungültig ist, können Sie ihn überschreiben, indem Sie einen ContainerImageName (veraltet) oder das bevorzugte ContainerRepository wie in der folgenden Projektdatei angeben:

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

Weitere Informationen finden Sie unter 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

Ab .NET 8 können Sie einen Container direkt als Tar.gz-Archiv erstellen. Diese Funktion ist nützlich, wenn Ihr Workflow nicht einfach ist und erfordert, dass Sie beispielsweise ein Scantool über Ihre Bilder ausführen, bevor Sie diese pushen. Nachdem das Archiv erstellt wurde, können Sie es verschieben, scannen oder in eine lokale Docker-Toolkette laden.

Um sie in einem Archiv zu veröffentlichen, fügen Sie die ContainerArchiveOutputPath Eigenschaft zu Ihrem dotnet publish-Befehl hinzu, z. B.:

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

Sie können entweder einen Ordnernamen oder einen Pfad mit einem bestimmten Dateinamen angeben. Wenn Sie den Ordnernamen angeben, lautet der für die Imagearchivdatei generierte Dateiname $(ContainerRepository).tar.gz. Diese Archive können mehrere Tags enthalten, nur wenn eine einzelne Datei für alle ContainerImageTags erstellt wird.

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

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

ContainerFamily

Ab .NET 8 können Sie die MSBuild-Eigenschaft ContainerFamily verwenden, um eine andere Familie von Microsoft-Containerimages als Basisimage für Ihre App auszuwählen. Wenn dieser Wert festgelegt ist, wird er am Ende des ausgewählten TFM-spezifischen Tags angefügt, wobei das angegebene Tag geändert wird. Um beispielsweise die Alpine Linux-Varianten der .NET-Basisimages zu verwenden, können Sie ContainerFamily auf alpine festlegen:

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

Die vorherige Projektkonfiguration führt zum endgültigen Tag 8.0-alpine für eine .NET 8-App.

Dieses Feld ist ein Freiformfeld und kann häufig verwendet werden, um verschiedene Betriebssystemdistributionen, Standardpaketkonfigurationen oder andere Änderungsflavors für ein Basisimage auszuwählen. Dieses Feld wird ignoriert, wenn ContainerBaseImage festgelegt ist. Weitere Informationen finden Sie unter .NET-Containerimages.

ContainerRepository

Das Containerrepository ist der Name des Images selbst, z. B. dotnet/runtime oder my-app. Standardmäßig wird der AssemblyName des Projekts verwendet.

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

ContainerImageName

Der Name des Containerimages bestimmt den Namen des Images selbst, z. B dotnet/runtime oder my-app. Standardmäßig wird der AssemblyName des Projekts verwendet.

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

Ab .NET 8 lautet der Standardwert latest, wenn kein Tag angegeben wird.

Standardmäßig wird die Version des Projekts als Tagwert verwendet.

Ab .NET 8 wird ContainerPort basierend auf mehreren bekannten ASP.NET-Umgebungsvariablen abgeleitet, wenn der Wert nicht explizit angegeben wird:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

Wenn diese Umgebungsvariablen vorhanden sind, werden ihre Werte analysiert und in TCP-Portzuordnungen konvertiert. Diese Umgebungsvariablen werden aus Ihrem Basisimage gelesen, sofern vorhanden, oder aus den Umgebungsvariablen, die in Ihrem Projekt definiert sind, über ContainerEnvironmentVariable-Elemente. Weitere Informationen finden Sie unter ContainerEnvironmentVariable.

Sie können jedoch steuern, wie Ihre App ausgeführt wird, indem Sie eine Kombination aus ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgs und ContainerAppCommandInstruction verwenden.

Diese unterschiedlichen Konfigurationspunkte sind vorhanden, da unterschiedliche Basisimages unterschiedliche Kombinationen der Containereigenschaften ENTRYPOINT und COMMAND verwenden, und alle davon unterstützt werden sollen. Die Standardwerte sollten von den meisten Apps verwendet werden können. Wenn Sie das App-Startverhalten jedoch anpassen möchten, sollten Sie:

• die auszuführende Binärdatei ermitteln und als ContainerAppCommand festlegen
• ermitteln, welche Argumente für die Ausführung Ihrer Anwendung erforderlich sind, und diese als ContainerAppCommandArgs festlegen
• ermitteln, welche Argumente (falls vorhanden) optional sind und von Benutzer*innen überschrieben werden können und diese als ContainerDefaultArgs festlegen
• Legen Sie ContainerAppCommandInstruction auf DefaultArgs fest.

Weitere Informationen finden Sie in den folgenden Konfigurationselementen.

ContainerAppCommand

Das ContainerAppCommand-Konfigurationselement ist der logische Einstiegspunkt Ihrer App. Für die meisten Apps ist dies der AppHost, die generierte ausführbare Binärdatei für Ihre App. Wenn Ihre App keinen AppHost generiert, lautet dieser Befehl in der Regel dotnet <your project dll>. Diese Werte werden nach jedem ENTRYPOINT-Element in Ihrem Basiscontainer oder direkt angewendet, wenn kein ENTRYPOINT-Element definiert ist.

Die ContainerAppCommand-Konfiguration weist eine einzelne Include-Eigenschaft auf, die den Befehl, die Option oder das Argument darstellt, die im Einstiegspunktbefehl verwendet werden sollen:

<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

Dieses ContainerAppCommandArgs-Konfigurationselement stellt alle logisch erforderlichen Argumente für Ihre App dar, die auf ContainerAppCommand angewendet werden sollen. Standardmäßig werden keine für eine App generiert. Wenn vorhanden, werden die Argumente auf Ihren Container angewendet, wenn er ausgeführt wird.

Die ContainerAppCommandArgs-Konfiguration verfügt über eine einzelne Include-Eigenschaft, die die Option oder das Argument darstellt, die auf den Befehl ContainerAppCommand angewendet werden soll.

<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

Dieses ContainerDefaultArgs-Konfigurationselement stellt alle durch Benutzer*innen überschreibbaren Argumente für Ihre App dar. Das ist eine gute Möglichkeit, Standardwerte anzugeben, die Ihre App benötigt, um leicht gestartet und angepasst werden zu können.

Die ContainerDefaultArgs-Konfiguration verfügt über eine einzelne Include-Eigenschaft, die die Option oder das Argument darstellt, die auf den Befehl ContainerAppCommand angewendet werden soll.

<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

Mit der ContainerAppCommandInstruction-Konfiguration können Sie steuern, wie die ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgs und ContainerDefaultArgs kombiniert werden, um den endgültigen Befehl zu bilden, der im Container ausgeführt wird. Hierbei ist maßgeblich, ob ENTRYPOINT im Basisimage vorhanden ist. Diese Eigenschaft akzeptiert einen von drei Werten: "DefaultArgs", "Entrypoint" oder "None".

• Entrypoint:
  • In diesem Modus wird der Einstiegspunkt durch ContainerAppCommand, ContainerAppCommandArgs und ContainerDefaultArgs definiert.
• None:
  • In diesem Modus wird der Einstiegspunkt durch ContainerEntrypoint, ContainerEntrypointArgs und ContainerDefaultArgs definiert.
• DefaultArgs:
  • Dies ist der komplexeste Modus. Wenn keines der ContainerEntrypoint[Args]-Elemente vorhanden ist, werden ContainerAppCommand[Args] und ContainerDefaultArgs zum Erstellen des Einstiegspunkts und Befehls verwendet. Wenn der Einstiegspunkt für Basisimages auf dotnet oder /usr/bin/dotnet hartcodiert ist, wird er übersprungen, sodass Sie die vollständige Kontrolle haben.
  • Wenn sowohl ContainerEntrypoint als auch ContainerAppCommand vorhanden sind, wird ContainerEntrypoint zum Einstiegspunkt, und ContainerAppCommand wird zum Befehl.

ContainerUser

Die Benutzerkonfigurationseigenschaft steuert den Standardbenutzer, der den Container ausführt. Dieser wird häufig verwendet, um den Container als Nicht-Root-Benutzer auszuführen, was eine bewährte Methode für die Sicherheit ist. Es gibt einige Einschränkungen für diese Konfiguration, die Sie beachten sollten:

• Sie kann verschiedene Formate aufweisen (Benutzernamen, Linux-Benutzer-IDs, Gruppenname, Linux-Gruppen-ID, username:groupname und andere ID-Varianten).
• Es gibt keine Überprüfung, dass der angegebene Benutzer oder die angegebene Gruppe im Image vorhanden ist.
• Das Ändern des Benutzers kann das Verhalten der App beeinflussen, insbesondere in Bezug auf Aspekte wie Dateisystemberechtigungen.

Der Standardwert dieses Felds variiert je nach Projekt-TFM und Zielbetriebssystem:

• Wenn die Zielversion .NET 8 oder höher ist und Sie Microsoft-Runtimeimages verwenden:
  • Unter Linux wird der Nicht-Root-Benutzer app verwendet (per Benutzer-ID angegeben)
  • Unter Windows wird der Nicht-Root-Benutzer ContainerUser verwendet
• Andernfalls wird standardmäßig kein ContainerUser verwendet.

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

Sie können jedoch mithilfe von ContainerEntrypoint und ContainerEntrypointArgs steuern, wie Ihre App ausgeführt wird.

ContainerEntrypoint

Mithilfe des Containereinstiegspunkts kann der ENTRYPOINT des Containers angepasst werden. Dabei handelt es sich um die ausführbare Datei, die beim Starten des Containers aufgerufen wird. Bei Builds, die einen App-Host erstellen, ist er standardmäßig auf ContainerEntrypoint festgelegt. Bei Builds, die keine ausführbare Datei erstellen, wird dotnet path/to/app.dll als ContainerEntrypoint verwendet.

Der Knoten ContainerEntrypoint hat ein einzelnes Attribut:

• Include: der Befehl, die Option oder das Argument zur Verwendung im Befehl ContainerEntrypoint.

Betrachten Sie beispielsweise das folgende Beispiel einer .NET-Projektelementgruppe:

<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

Der Knoten „Args“ des Containereinstiegspunkts bestimmt die Standardargumente, die ContainerEntrypoint bereitgestellt werden. Er sollte verwendet werden, wenn ContainerEntrypoint ein Programm ist, das der Benutzer möglicherweise eigenständig verwenden möchte. Standardmäßig werden keine ContainerEntrypointArgs in Ihrem Auftrag erstellt.

Der Knoten ContainerEntrypointArg hat ein einzelnes Attribut:

• Include: Die Option oder das Argument, die/das auf den Befehl ContainerEntrypoint angewendet werden soll.

Betrachten Sie die folgende .NET-Projektelementgruppe:

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