Containerisieren einer .NET-App-Referenz

In diesem Referenzartikel erfahren Sie, wie Sie das Containerimage konfigurieren, das generiert wird, wenn Sie eine .NET-App als Container veröffentlichen. In diesem Artikel werden die verschiedenen Eigenschaften behandelt, die Sie festlegen können, um das Image, die Ausführungsumgebung und die Befehle zu steuern, die beim Starten des Containers ausgeführt werden.

Konfigurieren des Containerimages

Sie können viele Aspekte des generierten Containers über MSBuild-Eigenschaften steuern. Wenn Sie in einem Dockerfile- einen Befehl verwenden können, können Sie dies über MSBuild tun.

Es gibt keine Möglichkeit, RUN Befehle mit dem .NET SDK auszuführen. Diese Befehle werden häufig verwendet, um einige Betriebssystempakete zu installieren oder einen neuen Betriebssystembenutzer oder eine beliebige Anzahl beliebiger Dinge zu erstellen. Wenn Sie das .NET SDK-Containererstellungsfeature beibehalten möchten, können Sie stattdessen ein benutzerdefiniertes Basisimage mit diesen Änderungen erstellen und dann dieses Basisimage verwenden. Weitere Informationen finden Sie unter ContainerBaseImage.

ContainerArchiveOutputPath

Verwenden Sie die ContainerArchiveOutputPath-Eigenschaft, um ein Containerimage in einem tar.gz-Archiv zu erstellen. Dieses Feature ist nützlich, wenn Ihr Workflow nicht einfach ist und erfordert, dass Sie beispielsweise ein Scantool über Ihre Bilder ausführen, bevor Sie sie 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 der dotnet publish-Befehls die eigenschaft ContainerArchiveOutputPath 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, wird der für die Bildarchivdatei generierte Datei $(ContainerRepository).tar.gzbenannt. Diese Archive können mehrere Tags enthalten, nur wenn eine einzelne Datei für alle ContainerImageTagserstellt wird.

Benennungskonfiguration für Containerimages

Containerimages folgen einer bestimmten Benennungskonvention. Der Name des Images besteht aus mehreren Teilen, der Registrierung, optionalen Port, Repository und optionalen Tag und Familie.

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

Betrachten Sie beispielsweise den vollqualifizierten mcr.microsoft.com/dotnet/runtime:8.0-alpine Bildnamen:

• mcr.microsoft.com ist die Registrierung (und stellt in diesem Fall die Microsoft-Containerregistrierung dar).
• dotnet/runtime ist das Repository (aber einige betrachten dies als das user/repository).
• 8.0-alpine ist das Tag und die Familie (die Familie ist ein optionaler Bezeichner, der bei der Mehrdeutigkeit des Betriebssystempakets hilft).

Einige in den folgenden Abschnitten beschriebene Eigenschaften entsprechen dem Verwalten von Teilen des generierten Bildnamens. Beachten Sie die folgende Tabelle, die die Beziehung zwischen dem Bildnamen und den Buildeigenschaften zuordnet:

In den folgenden Abschnitten werden die verschiedenen Eigenschaften beschrieben, die zum Steuern des generierten Containerimages verwendet werden können.

ContainerBaseImage

Die Containerbasisimageeigenschaft steuert das Bild, das als Grundlage für Ihr Image verwendet wird. Standardmäßig werden die folgenden Werte basierend auf den Eigenschaften Ihres Projekts abgeleitet:

• Wenn Ihr Projekt eigenständig ist, wird das mcr.microsoft.com/dotnet/runtime-deps Bild als Basisbild verwendet.
• Wenn es sich bei Ihrem Projekt um ein ASP.NET Core-Projekt handelt, wird das mcr.microsoft.com/dotnet/aspnet Bild als Basisimage verwendet.
• Andernfalls wird das mcr.microsoft.com/dotnet/runtime Bild als Basisbild verwendet.

Das Tag des Bilds wird abgeleitet, um die numerische Komponente der ausgewählten TargetFrameworkzu sein. Ein Projekt für net6.0 führt z. B. zum 6.0 Tag des abgeleiteten Basisimages, und ein net7.0-linux Projekt verwendet das 7.0-Tag usw.

Wenn Sie hier einen Wert festlegen, sollten Sie den vollqualifizierten Namen des Bilds festlegen, das als Basis verwendet werden soll, einschließlich aller tags, die Sie bevorzugen:

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

Mit .NET SDK Version 8.0.200 wird die ContainerBaseImage Rückschlüsse verbessert, um die Größe und Sicherheit zu optimieren:

• Wenn Sie auf die linux-musl-x64- oder linux-musl-arm64 Laufzeit-IDs abzielen, wählen Sie automatisch die alpine Bildvarianten aus, um sicherzustellen, dass Ihr Projekt ausgeführt wird:
  • Wenn das Projekt PublishAot=true verwendet, wird die nightly/runtime-depsjammy-chiseled-aot Variante des Basisimages für optimale Größe und Sicherheit verwendet.
  • Wenn das Projekt InvariantGlobalization=false verwendet, werden die -extra Varianten verwendet, um sicherzustellen, dass die Lokalisierung weiterhin funktioniert.

Weitere Informationen zu den Bildvarianten und -merkmalen finden Sie unter .NET 8.0 Container Image Size Report.

ContainerFamily

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

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

Die vorherige Projektkonfiguration führt zu einem endgültigen Tag von 8.0-alpine für eine .NET 8-Ziel-App.

Dieses Feld ist freiformatiert und kann häufig verwendet werden, um verschiedene Betriebssystemverteilungen, Standardpaketkonfigurationen oder andere Geschmack von Änderungen an einem Basisimage auszuwählen. Dieses Feld wird ignoriert, wenn ContainerBaseImage festgelegt wird. Weitere Informationen finden Sie unter .NET-Containerimages.

ContainerRuntimeIdentifier

Die eigenschaft ContainerRuntimeIdentifier gibt das Betriebssystem und die Architektur für Ihren Container an, wenn die ContainerBaseImage mehrere Plattformen unterstützt. Das mcr.microsoft.com/dotnet/runtime-Bild unterstützt z. B. linux-x64, linux-arm, linux-arm64und win10-x64. Standardmäßig ist dies auf die RuntimeIdentifier festgelegt, die beim Veröffentlichen des Containers verwendet wird. In der Regel müssen Sie diese Eigenschaft nicht explizit festlegen. Verwenden Sie stattdessen die Option -r mit dem Befehl dotnet publish. Wenn das ausgewählte Bild die angegebene RuntimeIdentifiernicht unterstützt, gibt ein Fehler die unterstützten Bezeichner an.

Sie können die ContainerBaseImage-Eigenschaft immer auf einen vollqualifizierten Bildnamen festlegen, einschließlich des Tags, um zu vermeiden, dass diese Eigenschaft überhaupt verwendet werden muss.

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

Weitere Informationen zu den von .NET unterstützten Laufzeit-IDs finden Sie im RID-Katalog.

ContainerRegistry

Die Containerregistrierungseigenschaft steuert die Zielregistrierung, der Ort, an den das neu erstellte Image übertragen wird. Standardmäßig wird er an den lokalen Docker-Daemon übertragen, Sie können aber auch eine Remoteregistrierung angeben. Wenn Sie eine Remoteregistrierung verwenden, die eine Authentifizierung erfordert, authentifizieren Sie sich mithilfe der bekannten docker login Mechanismen. Weitere Informationen finden Sie unter Authentifizierung für Containerregistrierungen weitere Informationen. Betrachten Sie für ein konkretes Beispiel für die Verwendung dieser Eigenschaft das folgende XML-Beispiel:

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

Dieses Tool unterstützt die Veröffentlichung in jeder Registrierung, die die Docker Registry HTTP API V2unterstützt. Dazu gehören die folgenden Registrierungen explizit (und wahrscheinlich viel impliziter):

• Azure Container Registry
• Amazon Elastic Container Registry
• Google Artifact Registry
• Docker Hub-
• GitHub-Pakete
• von GitLab gehostete Containerregistrierung
• Quay.io

Hinweise zum Arbeiten mit diesen Registern finden Sie in den registrierungsspezifischen Notizen.

ContainerRepository

Das Container-Repository 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>

Bildnamen bestehen aus einem oder mehreren durch Schrägstrich getrennten Abschnitten, von denen jedes nur alphanumerische Zeichen, Punkte, Unterstriche und Gedankenstriche enthalten kann und mit einem Buchstaben oder einer Zahl beginnen muss. Alle anderen Zeichen führen zu einem Fehler, der ausgelöst wird.

ContainerImageTag(s)

Die Eigenschaft des Containerimagetags steuert die Tags, die für das Image generiert werden. Um ein einzelnes Tag anzugeben, verwenden Sie ContainerImageTag und für mehrere Tags ContainerImageTags.

Tags werden häufig verwendet, um auf verschiedene Versionen einer App zu verweisen, aber sie können auch auf verschiedene Betriebssystemverteilungen oder sogar auf unterschiedliche Konfigurationen verweisen.

Ab .NET 8 wird die Standardeinstellung nicht latest, wenn ein Tag nicht bereitgestellt wird.

Um den Standardwert außer Kraft zu setzen, geben Sie eine der folgenden Optionen an:

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

Um mehrere Tags anzugeben, verwenden Sie einen durch Semikolons getrennten Satz von Tags in der ContainerImageTags-Eigenschaft, ähnlich wie das Festlegen mehrerer TargetFrameworks:

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

Tags können nur bis zu 127 alphanumerische Zeichen, Punkte, Unterstriche und Gedankenstriche enthalten. Sie müssen mit einem alphanumerischen Zeichen oder einem Unterstrich beginnen. Jedes andere Formular führt zu einem Fehler, der ausgelöst wird.

dotnet publish -p ContainerImageTags='"1.2.3-alpha2;latest"'

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

ContainerLabel

Die Containerbezeichnung fügt dem Container eine Metadatenbezeichnung hinzu. Bezeichnungen werden häufig verwendet, um Versions- und Erstellungsmetadaten für die Verwendung durch Sicherheitsscanner und andere Infrastrukturtools zu speichern. Sie können eine beliebige Anzahl von Containerbezeichnungen angeben.

Der knoten ContainerLabel hat zwei Attribute:

• Include: Der Schlüssel der Bezeichnung.
• Value: Der Wert der Bezeichnung (dies kann leer sein).

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

Eine Liste der Standardmäßig erstellten Bezeichnungen finden Sie unter Standardcontainerbeschriftungen.

Konfigurieren der Containerausführung

Um die Ausführung des Containers zu steuern, können Sie die folgenden MSBuild-Eigenschaften verwenden.

ContainerWorkingDirectory

Der Containerarbeitsverzeichnisknoten steuert das Arbeitsverzeichnis des Containers, das Verzeichnis, in dem Befehle ausgeführt werden, wenn kein anderer Befehl ausgeführt wird.

Standardmäßig wird der /app Verzeichniswert als Arbeitsverzeichnis verwendet.

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

ContainerPort

Der Containerport fügt tcp (Transmission Control Protocol) oder UDP-Ports (User Datagram Protocol) zur Liste der bekannten Ports für den Container hinzu. Dadurch können Containerlaufzeiten wie Docker diese Ports automatisch dem Hostcomputer zuordnen. Dies wird häufig als Dokumentation für den Container verwendet, kann aber auch verwendet werden, um die automatische Portzuordnung zu aktivieren.

Der knoten ContainerPort hat zwei Attribute:

• Include: Die portnummer, die verfügbar gemacht werden soll.
• Type: Standardwerte für tcp, gültige Werte sind entweder tcp oder udp.

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

Ab .NET 8 wird der ContainerPort abgeleitet, wenn er nicht explizit basierend auf mehreren bekannten ASP.NET Umgebungsvariablen bereitgestellt 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.

ContainerEnvironmentVariable

Mit dem Variablenknoten der Containerumgebung können Sie dem Container Umgebungsvariablen hinzufügen. Umgebungsvariablen sind sofort für die im Container ausgeführte App zugänglich und werden häufig verwendet, um das Laufzeitverhalten der ausgeführten App zu ändern.

Der knoten ContainerEnvironmentVariable hat zwei Attribute:

• Include: Der Name der Umgebungsvariable.
• Value: Der Wert der Umgebungsvariable.

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

Weitere Informationen finden Sie unter .NET-Umgebungsvariablen.

Konfigurieren von Containerbefehlen

Standardmäßig starten die Containertools Ihre App entweder mit der generierten AppHost-Binärdatei für Ihre App (wenn Ihre App einen AppHost verwendet) oder den dotnet Befehl plus der DLL Ihrer App.

Sie können jedoch steuern, wie Ihre App ausgeführt wird, indem Sie eine Kombination aus ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgsund ContainerAppCommandInstructionverwenden.

Diese verschiedenen Konfigurationspunkte sind vorhanden, da unterschiedliche Basisimages unterschiedliche Kombinationen des Containers ENTRYPOINT und COMMAND Eigenschaften verwenden, und Sie möchten alle unterstützen können. Die Standardwerte sollten für die meisten Apps verwendet werden können. Wenn Sie das App-Startverhalten jedoch anpassen möchten, sollten Sie:

• Identifizieren sie die auszuführende Binärdatei, und legen Sie sie als ContainerAppCommand
• Identifizieren Sie, welche Argumente erforderlich sind,, damit Ihre Anwendung ausgeführt werden kann, und legen Sie sie als ContainerAppCommandArgs
• Identifizieren Sie, welche Argumente (falls vorhanden) optional sind und von einem Benutzer überschrieben werden können, und legen Sie sie als ContainerDefaultArgs
• Festlegen von ContainerAppCommandInstruction auf DefaultArgs

Weitere Informationen finden Sie in den folgenden Konfigurationselementen.

ContainerAppCommand

Das Konfigurationselement des App-Befehls 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 kein AppHost generiert, wird dieser Befehl in der Regel dotnet <your project dll>. Diese Werte werden nach jedem ENTRYPOINT in Ihrem Basiscontainer oder direkt angewendet, wenn keine ENTRYPOINT 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 Konfigurationselement für App-Befehlsargumente stellt alle logisch erforderlichen Argumente für Ihre App dar, die auf die ContainerAppCommandangewendet 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 Standardargumentkonfigurationselement stellt alle benutzerüberschreibbaren Argumente für Ihre App dar. Dies ist eine gute Möglichkeit, Standardwerte bereitzustellen, die Ihre App möglicherweise auf eine Weise ausführen muss, die das Starten erleichtert, aber dennoch einfach anzupassen.

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 Befehlsanweisungskonfiguration der App können Sie steuern, wie die ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgsund ContainerDefaultArgs kombiniert werden, um den endgültigen Befehl zu bilden, der im Container ausgeführt wird. Dies hängt stark davon ab, ob ein ENTRYPOINT im Basisimage vorhanden ist. Diese Eigenschaft verwendet einen von drei Werten: "DefaultArgs", "Entrypoint"oder "None".

• Entrypoint:
  • In diesem Modus wird der Einstiegspunkt durch ContainerAppCommand, ContainerAppCommandArgsund ContainerDefaultArgsdefiniert.
• None:
  • In diesem Modus wird der Einstiegspunkt durch ContainerEntrypoint, ContainerEntrypointArgsund ContainerDefaultArgsdefiniert.
• DefaultArgs:
  • Dies ist der komplexeste Modus – wenn keines der ContainerEntrypoint[Args] Elemente vorhanden ist, werden die ContainerAppCommand[Args] und ContainerDefaultArgs verwendet, um den Einstiegspunkt und befehl zu erstellen. Der Basisbildeintragspunkt für Basisbilder, für die es hartcodiert ist, um dotnet zu dotnet oder /usr/bin/dotnet wird ü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, den der Container ausführt. Dies wird häufig verwendet, um den Container als Nicht-Stammbenutzer 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:

• Es kann verschiedene Formen annehmen – Benutzername, Linux-Benutzer-IDs, Gruppenname, Linux-Gruppen-ID, username:groupnameund andere ID-Varianten.
• Es gibt keine Überprüfung, dass der angegebene Benutzer oder die angegebene Gruppe im Bild vorhanden ist.
• Durch das Ändern des Verhaltens der App kann der Benutzer das Verhalten der App ändern, insbesondere in Bezug auf Elemente wie Dateisystem Berechtigungen.

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

• Wenn Sie .NET 8 oder höher verwenden und die Microsoft-Laufzeitimages verwenden, dann:
  • unter Linux wird der rootlose Benutzer app verwendet (es wird jedoch von seiner Benutzer-ID referenziert)
  • unter Windows wird der ContainerUser ohne Stammbenutzer verwendet.
• Andernfalls wird keine Standard-ContainerUser verwendet.

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

Legen Sie die eigenschaft ContainerUser auf rootfest, um die App so zu konfigurieren, dass sie als Stammbenutzer ausgeführt wird. Fügen Sie in Ihrer Projektdatei Folgendes hinzu:

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

Alternativ können Sie diesen Wert festlegen, wenn Sie dotnet publish über die Befehlszeile aufrufen:

dotnet publish -p ContainerUser=root

Standardcontainerbeschriftungen

Bezeichnungen werden häufig verwendet, um konsistente Metadaten für Containerimages bereitzustellen. Dieses Paket bietet einige Standardbezeichnungen, um eine bessere Wartungsfreundlichkeit der generierten Bilder zu fördern.

• org.opencontainers.image.created wird auf das ISO 8601-Format des aktuellen Werts von DateTime.UtcNowfestgelegt.

Weitere Informationen finden Sie unter Implementieren herkömmlicher Bezeichnungen über vorhandene Bezeichnungsinfrastruktur.

Siehe auch

• Containerisieren einer .NET-App mit dotnet publish
• .NET-Containerimages