Een .NET-app containeriseren met dotnet publish

  • Artikel

Containers hebben veel functies en voordelen, zoals een onveranderbare infrastructuur, die een draagbare architectuur biedt en schaalbaarheid mogelijk maakt. De installatiekopieën kunnen worden gebruikt om containers te maken voor uw lokale ontwikkelomgeving, privécloud of openbare cloud. In deze zelfstudie leert u hoe u een .NET-toepassing in een container kunt opslaan met behulp van de opdracht dotnet publish .

Vereisten

Installeer de volgende vereisten:

Naast deze vereisten is het raadzaam dat u bekend bent met Worker Services in .NET.

Een .NET-app maken

U hebt een .NET-app nodig om een container in te zetten, dus begin met het maken van een nieuwe app op basis van een sjabloon. Open uw terminal, maak een werkmap (sample-directory) als u dat nog niet hebt gedaan en wijzig mappen zodat u er in bent. Voer in de werkmap de volgende opdracht uit om een nieuw project te maken in een submap met de naam Worker:

dotnet new worker -o Worker -n DotNet.ContainerImage

De mapstructuur ziet er als volgt uit:

📁 sample-directory
    └──📂 Worker
        ├──appsettings.Development.json
        ├──appsettings.json
        ├──DotNet.ContainerImage.csproj
        ├──Program.cs
        ├──Worker.cs
        └──📂 obj
            ├── DotNet.ContainerImage.csproj.nuget.dgspec.json
            ├── DotNet.ContainerImage.csproj.nuget.g.props
            ├── DotNet.ContainerImage.csproj.nuget.g.targets
            ├── project.assets.json
            └── project.nuget.cache

Met de dotnet new opdracht maakt u een nieuwe map met de naam Worker en genereert u een werkrolservice die elke seconde een bericht registreert wanneer deze wordt uitgevoerd. Wijzig vanuit uw terminalsessie mappen en navigeer naar de map Worker . Gebruik de dotnet run opdracht om de app te starten.

dotnet run
Building...
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:00 -05:00
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: .\Worker
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:01 -05:00
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:02 -05:00
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:03 -05:00
info: Microsoft.Hosting.Lifetime[0]
      Application is shutting down...
Attempting to cancel the build...

De werkrolsjabloon wordt voor onbepaalde tijd herhaald. Gebruik de opdracht Annuleren Ctrl+C om deze te stoppen.

NuGet-pakket toevoegen

Het NuGet-pakket Microsoft.NET.Build.Containers is momenteel vereist voor het publiceren van niet-webprojecten als een container. Als u het Microsoft.NET.Build.Containers NuGet-pakket wilt toevoegen aan de werkrolsjabloon, voert u de volgende dotnet-pakketopdracht toe:

dotnet add package Microsoft.NET.Build.Containers

Tip

Als u een web-app bouwt en .NET SDK 7.0.300 of hoger gebruikt, is het pakket niet vereist. De SDK bevat dezelfde functionaliteit.

De naam van de containerinstallatiekopieën instellen

Er zijn verschillende configuratieopties beschikbaar bij het publiceren van een app als een container.

Standaard is de naam van de containerinstallatiekopieën de AssemblyName naam van het project. Als deze naam ongeldig is als de naam van een containerinstallatiekopieën, kunt u deze vervangen door een ContainerRepository zoals wordt weergegeven in het volgende projectbestand op te geven:

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

Zie ContainerRepository voor meer informatie.

Standaard is de naam van de containerinstallatiekopieën de AssemblyName naam van het project. Als deze naam ongeldig is als naam van een containerinstallatiekopieën, kunt u deze overschrijven door een (ContainerImageName verouderd) of de voorkeur op ContainerRepository te geven, zoals wordt weergegeven in het volgende projectbestand:

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

Zie ContainerImageName voor meer informatie.

.NET-app publiceren

Als u de .NET-app als een container wilt publiceren, gebruikt u de volgende dotnet-publicatieopdracht :

dotnet publish --os linux --arch x64 /t:PublishContainer -c Release

De voorgaande .NET CLI-opdracht publiceert de app als een container:

  • Gericht op Linux als het besturingssysteem (--os linux).
  • Een x64-architectuur opgeven (--arch x64).
  • De releaseconfiguratie (-c Release) gebruiken.

Belangrijk

Als u de container lokaal wilt bouwen, moet de Docker-daemon worden uitgevoerd. Als deze niet wordt uitgevoerd wanneer u de app probeert te publiceren als een container, treedt er een fout op die vergelijkbaar is met de volgende:

..\build\Microsoft.NET.Build.Containers.targets(66,9): error MSB4018:
   The "CreateNewImage" task failed unexpectedly. [..\Worker\DotNet.ContainerImage.csproj]

Tip

Afhankelijk van het type app dat u in een container wilt plaatsen, kunnen de opdrachtregelopties (opties) variëren. Het argument is bijvoorbeeld /t:PublishContainer alleen vereist voor niet-web .NET-apps, zoals console sjablonen.worker Voor websjablonen vervangt u het /t:PublishContainer argument door -p:PublishProfile=DefaultContainer. Zie .NET SDK-container builds, probleem 141 voor meer informatie.

De opdracht produceert uitvoer die vergelijkbaar is met de voorbeelduitvoer:

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

Met deze opdracht wordt uw werkrol-app gecompileerd naar de publicatiemap en wordt de container naar uw lokale Docker-register gepusht.

Containerinstallatiekopieën configureren

U kunt veel aspecten van de gegenereerde container beheren via MSBuild-eigenschappen. Als u in het algemeen een opdracht in een Dockerfile kunt gebruiken om een bepaalde configuratie in te stellen, kunt u hetzelfde doen via MSBuild.

Notitie

De enige uitzonderingen hierop zijn RUN opdrachten. Vanwege de manier waarop containers worden gebouwd, kunnen deze niet worden geëmuleerd. Als u deze functionaliteit nodig hebt, moet u een Dockerfile gebruiken om uw containerinstallatiekopieën te bouwen.

ContainerArchiveOutputPath

Vanaf .NET 8 kunt u rechtstreeks als een tar.gz archief een container maken. Deze functie is handig als uw werkstroom niet eenvoudig is en u bijvoorbeeld een scanprogramma voor uw afbeeldingen moet uitvoeren voordat u ze pusht. Zodra het archief is gemaakt, kunt u het verplaatsen, scannen of laden in een lokale Docker-hulpprogrammaketen.

Als u naar een archief wilt publiceren, voegt u de ContainerArchiveOutputPath eigenschap toe aan uw dotnet publish opdracht, bijvoorbeeld:

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

U kunt een mapnaam of een pad met een specifieke bestandsnaam opgeven. Als u de mapnaam opgeeft, wordt de bestandsnaam die is gegenereerd voor het archiefbestand van de afbeelding.$(ContainerRepository).tar.gz Deze archieven kunnen meerdere tags erin bevatten, alleen omdat er slechts één bestand voor iedereen ContainerImageTagswordt gemaakt.

Naamgevingsconfiguratie voor containerinstallatiekopieën

Containerinstallatiekopieën volgen een specifieke naamconventie. De naam van de installatiekopieën bestaat uit verschillende onderdelen, het register, de optionele poort, opslagplaats en optionele tag en familie.

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

Denk bijvoorbeeld aan de volledig gekwalificeerde mcr.microsoft.com/dotnet/runtime:8.0-alpine naam van de installatiekopieën:

  • mcr.microsoft.com is het register (en in dit geval vertegenwoordigt het Microsoft-containerregister).
  • dotnet/runtimeis de opslagplaats (maar sommigen overwegen dit).user/repository
  • 8.0-alpine is de tag en familie (de familie is een optionele aanduiding die helpt om de verpakking van het besturingssysteem ondubbelzinnig te maken).

Sommige eigenschappen die in de volgende secties worden beschreven, komen overeen met het beheren van onderdelen van de gegenereerde installatiekopieënnaam. Bekijk de volgende tabel waarmee de relatie tussen de naam van de installatiekopieën en de build-eigenschappen wordt toegewezen:

Onderdeel Afbeeldingsnaam MSBuild-eigenschap Voorbeeldwaarden
REGISTRY[:PORT] ContainerRegistry mcr.microsoft.com:443
PORT ContainerPort :443
REPOSITORY ContainerRepository dotnet/runtime
TAG ContainerImageTag 8.0
FAMILY ContainerFamily -alpine
Onderdeel Afbeeldingsnaam MSBuild-eigenschap Voorbeeldwaarden
REGISTRY[:PORT] ContainerRegistry mcr.microsoft.com:443
PORT ContainerPort :443
REPOSITORY ContainerImageName dotnet/runtime
TAG ContainerImageTag 8.0

In de volgende secties worden de verschillende eigenschappen beschreven die kunnen worden gebruikt om de gegenereerde containerinstallatiekopieën te beheren.

ContainerBaseImage

De eigenschap containerbasisinstallatiekopieën bepaalt de installatiekopieën die worden gebruikt als basis voor uw installatiekopieën. Standaard worden de volgende waarden afgeleid op basis van de eigenschappen van uw project:

  • Als uw project zelfstandig is, wordt de mcr.microsoft.com/dotnet/runtime-deps installatiekopieën gebruikt als basisinstallatiekopieën.
  • Als uw project een ASP.NET Core-project is, wordt de mcr.microsoft.com/dotnet/aspnet afbeelding gebruikt als basisinstallatiekopieën.
  • Anders wordt de mcr.microsoft.com/dotnet/runtime afbeelding gebruikt als basisinstallatiekopieën.

De tag van de afbeelding wordt afgeleid als het numerieke onderdeel van uw keuze TargetFramework. Een project dat als doel heeft, net6.0 resulteert bijvoorbeeld in de 6.0 tag van de uitgestelde basisinstallatiekopieën, en een net7.0-linux project maakt gebruik van de 7.0 tag, enzovoort.

Als u hier een waarde instelt, moet u de volledig gekwalificeerde naam van de installatiekopieën instellen voor gebruik als basis, inclusief een tag die u wilt gebruiken:

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

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

ContainerFamily

Vanaf .NET 8 kunt u de ContainerFamily eigenschap MSBuild gebruiken om een andere familie van door Microsoft geleverde containerinstallatiekopieën te kiezen als basisinstallatiekopieën voor uw app. Wanneer deze waarde is ingesteld, wordt deze waarde toegevoegd aan het einde van de geselecteerde TFM-specifieke tag en wordt de opgegeven tag gewijzigd. Als u bijvoorbeeld de Alpine Linux-varianten van de .NET-basisinstallatiekopieën wilt gebruiken, kunt u instellen ContainerFamily op alpine:

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

De voorgaande projectconfiguratie resulteert in een laatste tag van 8.0-alpine een .NET 8-doel-app.

Dit veld is vrij en kan vaak worden gebruikt om verschillende distributies van besturingssystemen, standaardpakketconfiguraties of andere wijzigingen in een basisinstallatiekopieën te selecteren. Dit veld wordt genegeerd wanneer ContainerBaseImage dit is ingesteld. Zie .NET-containerinstallatiekopieën voor meer informatie.

ContainerRuntimeIdentifier

De eigenschap containerruntime-id bepaalt het besturingssysteem en de architectuur die door uw container wordt gebruikt als uw ContainerBaseImage meer dan één platform ondersteunt. De installatiekopieën ondersteunen linux-x64momenteel bijvoorbeeld mcr.microsoft.com/dotnet/runtime , linux-armlinux-arm64 en win10-x64 afbeeldingen achter dezelfde tag, dus de tooling heeft een manier nodig om te worden verteld welke van deze versies u wilt gebruiken. Dit is standaard ingesteld op de waarde van de RuntimeIdentifier waarde die u hebt gekozen bij het publiceren van de container. Deze eigenschap hoeft zelden expliciet te worden ingesteld. Gebruik in plaats daarvan de -r optie voor de dotnet publish opdracht. Als de installatiekopieën die u hebt gekozen niet worden ondersteund RuntimeIdentifier , resulteert dit in een fout die de RuntimeIdentifiers beschrijft die door de installatiekopieën worden ondersteund.

U kunt de ContainerBaseImage eigenschap altijd instellen op een volledig gekwalificeerde installatiekopieënnaam, inclusief de tag, om te voorkomen dat u deze eigenschap helemaal hoeft te gebruiken.

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

Zie de RID-catalogus voor meer informatie over de runtime-id's die worden ondersteund door .NET.

ContainerRegistry

De eigenschap containerregister bepaalt het doelregister, de plaats waarnaar de zojuist gemaakte installatiekopieën worden gepusht. Standaard wordt deze naar de lokale Docker-daemon gepusht, maar u kunt ook een extern register opgeven. Wanneer u een extern register gebruikt waarvoor verificatie is vereist, moet u zich verifiëren met behulp van de bekende docker login mechanismen. Zie verificatie bij containerregisters voor meer informatie. Bekijk het volgende XML-voorbeeld voor een concreet voorbeeld van het gebruik van deze eigenschap:

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

Deze hulpprogramma's ondersteunen het publiceren naar elk register dat ondersteuning biedt voor de HTTP API V2 van Docker Registry. Dit omvat expliciet de volgende registers (en waarschijnlijk nog veel meer impliciet):

Zie de registerspecifieke notities voor opmerkingen over het werken met deze registers.

ContainerRepository

De containeropslagplaats is bijvoorbeeld de naam van de installatiekopieën zelf, dotnet/runtime of my-app. Standaard wordt het AssemblyName project gebruikt.

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

ContainerImageName

De naam van de containerinstallatiekopieën bepaalt bijvoorbeeld de naam van de installatiekopieën zelf of dotnet/runtimemy-app. Standaard wordt het AssemblyName project gebruikt.

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

Notitie

Vanaf .NET 8 wordt ContainerImageName afgeschaft ten gunste van ContainerRepository.

Afbeeldingsnamen bestaan uit een of meer segmenten met slash-scheidingstekens, die elk alleen alfanumerieke tekens, punten, onderstrepingstekens en streepjes mogen bevatten en moeten beginnen met een letter of cijfer. Alle andere tekens leiden tot een fout die wordt gegenereerd.

ContainerImageTag(s)

De tageigenschap containerinstallatiekopieën bepaalt de tags die worden gegenereerd voor de installatiekopieën. Als u één taggebruik ContainerImageTag wilt opgeven en voor meerdere tags wilt gebruiken ContainerImageTags.

Belangrijk

Wanneer u gebruikt ContainerImageTags, krijgt u uiteindelijk meerdere afbeeldingen, één per unieke tag.

Tags worden vaak gebruikt om te verwijzen naar verschillende versies van een app, maar ze kunnen ook verwijzen naar verschillende besturingssysteemdistributies of zelfs verschillende configuraties.

Vanaf .NET 8 geldt dat wanneer een tag niet is opgegeven, de standaardwaarde is latest.

Standaard wordt het Version project gebruikt als de tagwaarde.

Als u de standaardwaarde wilt overschrijven, geeft u een van de volgende opties op:

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

Als u meerdere tags wilt opgeven, gebruikt u een door puntkomma's gescheiden set tags in de ContainerImageTags eigenschap, vergelijkbaar met het instellen van meerdere TargetFrameworks:

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

Tags mogen maximaal 127 alfanumerieke tekens, punten, onderstrepingstekens en streepjes bevatten. Ze moeten beginnen met een alfanumerieke teken of een onderstrepingsteken. Elk ander formulier resulteert in een fout die wordt gegenereerd.

Notitie

Wanneer u deze gebruikt ContainerImageTags, worden de tags gescheiden door een ; teken. Als u aanroept dotnet publish vanaf de opdrachtregel (zoals het geval is bij de meeste CI/CD-omgevingen), moet u de waarden in één ' en binnenste terugloop verpakken met dubbele aanhalingstekens ", bijvoorbeeld (='"tag-1;tag-2"'). Houd rekening met de volgende dotnet publish opdracht:

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

Dit resulteert in twee afbeeldingen die worden gegenereerd: my-app:1.2.3-alpha2 en my-app:latest.

Tip

Als u problemen ondervindt met de ContainerImageTags eigenschap, kunt u overwegen om in plaats daarvan een omgevingsvariabele te verkennen ContainerImageTags :

ContainerImageTags='1.2.3;latest' dotnet publish

ContainerLabel

Het containerlabel voegt een metagegevenslabel toe aan de container. Labels hebben geen invloed op de container tijdens runtime, maar worden vaak gebruikt voor het opslaan van versie- en ontwerpmetagegevens voor gebruik door beveiligingsscanners en andere infrastructuurhulpprogramma's. U kunt een willekeurig aantal containerlabels opgeven.

Het ContainerLabel knooppunt heeft twee kenmerken:

  • Include: De sleutel van het label.
  • Value: De waarde van het label (dit kan leeg zijn).
<ItemGroup>
    <ContainerLabel Include="org.contoso.businessunit" Value="contoso-university" />
</ItemGroup>

Zie de standaardcontainerlabels voor een lijst met labels die standaard worden gemaakt.

Containeruitvoering configureren

Als u de uitvoering van de container wilt beheren, kunt u de volgende MSBuild-eigenschappen gebruiken.

ContainerWorkingDirectory

Het containerwerkmapknooppunt bepaalt de werkmap van de container, de map waarin opdrachten worden uitgevoerd als er geen andere opdracht wordt uitgevoerd.

De mapwaarde wordt standaard /app gebruikt als de werkmap.

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

ContainerPort

De containerpoort voegt TCP- of UDP-poorten toe aan de lijst met bekende poorten voor de container. Hierdoor kunnen containerruntimes zoals Docker deze poorten automatisch toewijzen aan de hostcomputer. Dit wordt vaak gebruikt als documentatie voor de container, maar kan ook worden gebruikt om automatische poorttoewijzing in te schakelen.

Het ContainerPort knooppunt heeft twee kenmerken:

  • Include: het poortnummer dat moet worden weergegeven.
  • Type: Standaardwaarden tcpzijn geldige waarden tcp of udp.
<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

Vanaf .NET 8 wordt de ContainerPort afgeleid wanneer deze niet expliciet wordt opgegeven op basis van verschillende bekende ASP.NET omgevingsvariabelen:

  • ASPNETCORE_URLS
  • ASPNETCORE_HTTP_PORTS
  • ASPNETCORE_HTTPS_PORTS

Als deze omgevingsvariabelen aanwezig zijn, worden de waarden geparseerd en geconverteerd naar TCP-poorttoewijzingen. Deze omgevingsvariabelen worden gelezen uit uw basisinstallatiekopieën, indien aanwezig, of uit de omgevingsvariabelen die in uw project zijn gedefinieerd via ContainerEnvironmentVariable items. Zie ContainerEnvironmentVariable voor meer informatie.

ContainerEnvironmentVariable

Met het knooppunt voor de containeromgevingsvariabele kunt u omgevingsvariabelen toevoegen aan de container. Omgevingsvariabelen zijn onmiddellijk toegankelijk voor de app die in de container wordt uitgevoerd en worden vaak gebruikt om het runtimegedrag van de actieve app te wijzigen.

Het ContainerEnvironmentVariable knooppunt heeft twee kenmerken:

  • Include: De naam van de omgevingsvariabele.
  • Value: De waarde van de omgevingsvariabele.
<ItemGroup>
  <ContainerEnvironmentVariable Include="LOGGER_VERBOSITY" Value="Trace" />
</ItemGroup>

Zie .NET-omgevingsvariabelen voor meer informatie.

Containeropdrachten configureren

Standaard starten de containerhulpprogramma's uw app met behulp van het gegenereerde binaire AppHost-bestand voor uw app (als uw app een AppHost gebruikt) of de opdracht plus het dotnet DLL-bestand van uw app.

U kunt echter bepalen hoe uw app wordt uitgevoerd met behulp van een combinatie van ContainerAppCommand, ContainerAppCommandArgsen ContainerDefaultArgsContainerAppCommandInstruction.

Deze verschillende configuratiepunten bestaan omdat verschillende basisinstallatiekopieën verschillende combinaties van de container ENTRYPOINT en COMMAND eigenschappen gebruiken en u deze allemaal wilt kunnen ondersteunen. De standaardwaarden moeten worden gebruikt voor de meeste apps, maar als u het startgedrag van uw app wilt aanpassen, moet u het volgende doen:

  • Identificeer het binaire bestand dat moet worden uitgevoerd en stel het in als ContainerAppCommand
  • Bepalen welke argumenten vereist zijn om uw toepassing uit te voeren en in te stellen alsContainerAppCommandArgs
  • Bepalen welke argumenten (indien aanwezig) optioneel zijn en kunnen worden overschreven door een gebruiker en deze instellen alsContainerDefaultArgs
  • Stel ContainerAppCommandInstruction in op DefaultArgs

Zie de volgende configuratie-items voor meer informatie.

ContainerAppCommand

Het configuratie-item voor de app-opdracht is het logische toegangspunt van uw app. Voor de meeste apps is dit de AppHost, het gegenereerde binaire bestand voor uw app. Als uw app geen AppHost genereert, is dotnet <your project dll>deze opdracht meestal. Deze waarden worden toegepast na elke ENTRYPOINT waarde in uw basiscontainer of direct als er geen ENTRYPOINT is gedefinieerd.

De ContainerAppCommand configuratie heeft één Include eigenschap, die de opdracht, optie of argument vertegenwoordigt die moet worden gebruikt in de invoerpuntopdracht:

<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

Met deze app-opdracht wordt een configuratie-item gebruikt dat alle logisch vereiste argumenten vertegenwoordigt voor uw app die op de ContainerAppCommandapp moeten worden toegepast. Standaard worden er geen gegenereerd voor een app. Wanneer deze aanwezig is, worden de argumenten toegepast op uw container wanneer deze wordt uitgevoerd.

De ContainerAppCommandArgs configuratie heeft één Include eigenschap, die de optie of het argument vertegenwoordigt die moet worden toegepast op de ContainerAppCommand opdracht.

<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

Dit standaardargumentenconfiguratie-item vertegenwoordigt alle argumenten die door de gebruiker kunnen worden overschreven voor uw app. Dit is een goede manier om standaardinstellingen te bieden die uw app mogelijk moet uitvoeren op een manier waarmee u eenvoudig kunt beginnen, maar nog steeds eenvoudig kunt aanpassen.

De ContainerDefaultArgs configuratie heeft één Include eigenschap, die de optie of het argument vertegenwoordigt die moet worden toegepast op de ContainerAppCommand opdracht.

<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

De instructieconfiguratie van de app-opdracht helpt bij het beheren van de manier waarop de ContainerEntrypoint, ContainerAppCommandContainerEntrypointArgs, en ContainerAppCommandArgsContainerDefaultArgs worden gecombineerd om de uiteindelijke opdracht te vormen die in de container wordt uitgevoerd. Dit is sterk afhankelijk van of een ENTRYPOINT aanwezig is in de basisinstallatiekopieën. Deze eigenschap heeft een van de drie waarden: "DefaultArgs", "Entrypoint"of "None".

  • Entrypoint:
    • In deze modus wordt het invoerpunt gedefinieerd door ContainerAppCommand, ContainerAppCommandArgsen ContainerDefaultArgs.
  • None:
    • In deze modus wordt het invoerpunt gedefinieerd door ContainerEntrypoint, ContainerEntrypointArgsen ContainerDefaultArgs.
  • DefaultArgs:
    • Dit is de meest complexe modus: als geen van de ContainerEntrypoint[Args] items aanwezig is, worden de ContainerAppCommand[Args] items gebruikt om ContainerDefaultArgs het invoerpunt en de opdracht te maken. Het basisinstallatiekopieëninvoerpunt voor basisinstallatiekopieën waarop deze in code is vastgelegd dotnet of /usr/bin/dotnet wordt overgeslagen, zodat u volledige controle hebt.
    • Als beide ContainerEntrypoint aanwezig ContainerAppCommand zijn, wordt dit ContainerEntrypoint het invoerpunt en ContainerAppCommand wordt de opdracht.

Notitie

De ContainerEntrypoint en ContainerEntrypointArgs configuratie-items zijn afgeschaft vanaf .NET 8.

Belangrijk

Dit is bedoeld voor geavanceerde gebruikers. De meeste apps hoeven hun ingangspunt niet in deze mate aan te passen. Zie GitHub: .NET SDK-container bouwt discussies voor meer informatie en als u use cases voor uw scenario's wilt opgeven.

ContainerUser

De eigenschap gebruikersconfiguratie bepaalt de standaardgebruiker die door de container wordt uitgevoerd. Dit wordt vaak gebruikt om de container uit te voeren als een niet-basisgebruiker. Dit is een aanbevolen procedure voor beveiliging. Er zijn enkele beperkingen voor deze configuratie om rekening mee te houden:

  • Het kan verschillende vormen aannemen: gebruikersnaam, linux-gebruikers-id's, groepsnaam, linux-groeps-id en username:groupnameandere id-varianten.
  • Er is geen verificatie dat de gebruiker of groep die is opgegeven op de installatiekopie bestaat.
  • Als u de gebruiker wijzigt, kan het gedrag van de app worden gewijzigd, met name met betrekking tot zaken als bestandssysteemmachtigingen .

De standaardwaarde van dit veld varieert per project TFM en het doelbesturingssysteem:

  • Als u zich richt op .NET 8 of hoger en de Installatiekopieën van Microsoft Runtime gebruikt, doet u het volgende:
    • in Linux wordt de gebruiker zonder app hoofdmap gebruikt (hoewel ernaar wordt verwezen door de gebruikers-id)
    • in Windows wordt de gebruiker ContainerUser zonder hoofdmap gebruikt
  • Anders wordt er geen standaard ContainerUser gebruikt
<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

Tip

De APP_UID omgevingsvariabele wordt gebruikt om gebruikersgegevens in te stellen in uw container. Deze waarde kan afkomstig zijn van omgevingsvariabelen die zijn gedefinieerd in uw basisinstallatiekopieën (zoals die van Microsoft .NET-installatiekopieën), of u kunt deze zelf instellen via de ContainerEnvironmentVariable syntaxis.

U kunt echter bepalen hoe uw app wordt uitgevoerd met behulp van ContainerEntrypoint en ContainerEntrypointArgs.

ContainerEntrypoint

Het containerinvoerpunt kan worden gebruikt om de ENTRYPOINT container aan te passen. Dit is het uitvoerbare bestand dat wordt aangeroepen wanneer de container wordt gestart. Voor builds die een app-host maken, wordt deze standaard ingesteld als de ContainerEntrypoint. Voor builds die geen uitvoerbaar bestand maken, wordt het dotnet path/to/app.dll gebruikt als de ContainerEntrypoint.

Het ContainerEntrypoint knooppunt heeft één kenmerk:

  • Include: de opdracht, optie of het argument dat u in de ContainerEntrypoint opdracht wilt gebruiken.

Bekijk bijvoorbeeld de volgende voorbeeldprojectitemgroep van .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

Het containerinvoerpunt args-knooppunt bepaalt de standaardargumenten die aan de ContainerEntrypoint. Dit moet worden gebruikt wanneer het ContainerEntrypoint een programma is dat de gebruiker mogelijk zelfstandig wil gebruiken. Standaard worden er geen ContainerEntrypointArgs namens u gemaakt.

Het ContainerEntrypointArg knooppunt heeft één kenmerk:

  • Include: de optie of het argument die moet worden toegepast op de ContainerEntrypoint opdracht.

Bekijk het volgende voorbeeld van een .NET-projectitemgroep:

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

Standaardcontainerlabels

Labels worden vaak gebruikt om consistente metagegevens op containerinstallatiekopieën te bieden. Dit pakket biedt enkele standaardlabels om de gegenereerde installatiekopieën beter te onderhouden.

  • org.opencontainers.image.created is ingesteld op de ISO 8601-indeling van de huidige UTC DateTime.

Zie Conventionele labels op bestaande labelinfrastructuur implementeren voor meer informatie.

Resources opschonen

In dit artikel hebt u een .NET-werkrol gepubliceerd als een containerinstallatiekopieën. Verwijder deze resource desgewenst. Gebruik de docker images opdracht om een lijst met geïnstalleerde installatiekopieën weer te geven.

docker images

Bekijk de volgende voorbeelduitvoer:

REPOSITORY            TAG       IMAGE ID       CREATED          SIZE
dotnet-worker-image   1.0.0     25aeb97a2e21   12 seconds ago   191MB

Tip

Afbeeldingsbestanden kunnen groot zijn. Normaal gesproken verwijdert u tijdelijke containers die u hebt gemaakt tijdens het testen en ontwikkelen van uw app. Meestal houdt u de basisinstallatiekopieën bij de runtime geïnstalleerd als u van plan bent om andere installatiekopieën te bouwen op basis van die runtime.

Als u de installatiekopie wilt verwijderen, kopieert u de installatiekopie-id en voert u de docker image rm opdracht uit:

docker image rm 25aeb97a2e21

Volgende stappen