Share via

Een .NET-app-verwijzing containeriseren

In dit naslagartikel leert u hoe u de containerinstallatiekopieën configureert die worden gegenereerd wanneer u een .NET-app publiceert als een container. In dit artikel worden de verschillende eigenschappen beschreven die u kunt instellen om de installatiekopieën, de uitvoeringsomgeving en de opdrachten te beheren die worden uitgevoerd wanneer de container wordt gestart.

Containereigenschappen 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 opdrachten niet worden geëmuleerd. Als u deze functionaliteit nodig hebt, kunt u overwegen een Dockerfile te gebruiken om uw containerinstallatiekopieën te bouwen.

Er is geen manier om RUN opdrachten uit te voeren met de .NET SDK. Deze opdrachten worden vaak gebruikt om bepaalde besturingssysteempakketten te installeren of een nieuwe gebruiker van het besturingssysteem te maken, of een willekeurig aantal dingen. Als u de functie voor het bouwen van .NET SDK-containers wilt blijven gebruiken, kunt u in plaats daarvan een aangepaste basisinstallatiekopieën maken met deze wijzigingen en vervolgens deze basisinstallatiekopieën gebruiken. Zie ContainerBaseImagevoor meer informatie.

Vlaggen die de basisinstallatiekopieën beheren

Met de volgende eigenschappen bepaalt u welke basisinstallatiekopieën worden gebruikt voor uw container en hoe deze wordt geselecteerd:

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 op zichzelf staat, 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 installatiekopieën gebruikt als basisinstallatiekopieën.
  • Anders wordt de mcr.microsoft.com/dotnet/runtime-installatiekopieën gebruikt als basisinstallatiekopieën.

De tag van de afbeelding wordt afgeleid als het numerieke onderdeel van uw gekozen TargetFramework. Een project dat is gericht op 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>

Met .NET SDK versie 8.0.200 wordt de ContainerBaseImage deductie verbeterd om de grootte en beveiliging te optimaliseren:

  • Als u de linux-musl-x64 of linux-musl-arm64 Runtime-id's wilt instellen, kiest u automatisch de alpine afbeeldingsvarianten om ervoor te zorgen dat uw project wordt uitgevoerd:
    • Als het project PublishAot=true gebruikt, wordt de nightly/runtime-depsjammy-chiseled-aot variant van de basisinstallatiekopieën gebruikt voor de beste grootte en beveiliging.
    • Als het project InvariantGlobalization=false gebruikt, worden de -extra varianten gebruikt om ervoor te zorgen dat lokalisatie nog steeds werkt.

Zie .NET 8.0 Container Image Size Report voor meer informatie over de grootte en kenmerken van de afbeeldingsvarianten.

ContainerFamily

Vanaf .NET 8 kunt u de eigenschap ContainerFamily 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 ContainerFamily instellen op alpine:

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

De voorgaande projectconfiguratie resulteert in een laatste tag van 8.0-alpine voor 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 is ingesteld. Zie .NET-containerinstallatiekopieën voor meer informatie.

ContainerRuntimeIdentifier(s)

De eigenschap ContainerRuntimeIdentifier geeft het besturingssysteem en de architectuur voor uw container op als de ContainerBaseImage meerdere platforms ondersteunt. De mcr.microsoft.com/dotnet/runtime-installatiekopieën ondersteunen bijvoorbeeld linux-x64, linux-arm, linux-arm64en win10-x64. Dit is standaard ingesteld op de RuntimeIdentifier gebruikt bij het publiceren van de container. Normaal gesproken hoeft u deze eigenschap niet expliciet in te stellen; Gebruik in plaats daarvan de optie -r met de opdracht dotnet publish. Als de gekozen installatiekopieën de opgegeven RuntimeIdentifierniet ondersteunen, geeft een fout de ondersteunde id's aan.

U kunt de eigenschap ContainerBaseImage 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>

Als u meerdere containerruntime-id's voor installatiekopieën met meerdere architectuur wilt opgeven, gebruikt u een door puntkomma's gescheiden set runtime-id's in de eigenschap ContainerRuntimeIdentifiers, vergelijkbaar met het instellen van meerdere TargetFrameworks:

<PropertyGroup>
    <ContainerRuntimeIdentifiers>linux-x64;linux-arm64</ContainerRuntimeIdentifiers>
</PropertyGroup>

Belangrijk

De ContainerRuntimeIdentifiers eigenschap moet een subset van de RuntimeIdentifiers eigenschap zijn. Als niet aan deze voorwaarde wordt voldaan, kunnen kritieke onderdelen van de build-pijplijn mislukken.

Het instellen van meerdere ContainerRuntimeIdentifiers resultaten in een installatiekopieën met meerdere architectuur die wordt gemaakt. Zie Installatiekopieën met meerdere architectuur voor meer informatie.

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

Installatiekopieën met meerdere architectuur

Installatiekopieën met meerdere architectuur bieden één containerinstallatiekopieën ondersteuning voor meerdere architecturen, waardoor platformoverschrijdende ontwikkeling en implementatie worden vereenvoudigd. De .NET SDK ondersteunt dit via de ContainerRuntimeIdentifiers eigenschap.

Vanaf SDK-versies 8.0.405, 9.0.102 en 9.0.2xx wordt het publiceren van containers met meerdere RID's ondersteund. Wanneer u publiceert met /t:PublishContainer:

  • Als er één RuntimeIdentifier of ContainerRuntimeIdentifier meer opgegeven is, wordt er net als voorheen een container met één architectuur gegenereerd.
  • Als er geen enkele is RuntimeIdentifier opgegeven maar meerdere RuntimeIdentifiersContainerRuntimeIdentifiers of zijn ingesteld, publiceert de SDK de app voor elke opgegeven RID en worden de resulterende installatiekopieën gecombineerd tot een OCI-installatiekopieënindex. Met deze index kunnen meerdere architectuurspecifieke installatiekopieën één naam delen.

Notitie

De ContainerRuntimeIdentifiers eigenschap moet een subset van de RuntimeIdentifiers eigenschap zijn. Zie ContainerRuntimeIdentifiers voor meer informatie.

Deze functie stroomlijnt containerwerkstromen in omgevingen met gemengde architectuur. Een ontwikkelaar op een linux-x64 host kan bijvoorbeeld een container publiceren die beide linux-x64 ondersteunt en linux-arm64, waardoor implementatie naar architectuur kan worden uitgevoerd zonder de namen of labels van installatiekopieën te wijzigen.

De gegenereerde OCI Image Index wordt veel ondersteund met moderne containerhulpprogramma's, waardoor de compatibiliteit en het gebruiksgemak worden verbeterd.

Vlaggen voor het beheren van gegenereerde installatiekopieën onafhankelijke metagegevens

De volgende eigenschappen bepalen metagegevens en configuratie die van toepassing zijn op de gegenereerde containerinstallatiekopieën, ongeacht de doelruntime-id:

ContainerImageFormat

U kunt de ContainerImageFormat eigenschap MSBuild gebruiken om de afbeeldingsindeling op te geven als of DockerOCI. Standaard wordt met .NET-hulpprogramma's de indeling afgeleid van de basisinstallatiekopie. .NET-basisinstallatiekopieën maken bijvoorbeeld gebruik van de Docker-specifieke indeling application/vnd.docker.distribution.manifest.v2+json. Veel moderne hulpprogramma's geven echter de voorkeur aan de OCI-indeling application/vnd.oci.image.manifest.v1+json. Als u een specifieke indeling wilt afdwingen, stelt u de eigenschap in zoals wordt weergegeven:

<PropertyGroup>
  <ContainerImageFormat>OCI</ContainerImageFormat>
</PropertyGroup>

Beide indelingen zijn grotendeels uitwisselbaar zonder verlies van informatie.

Notitie

Bij het bouwen van een installatiekopieën met meerdere architectuur is de resulterende afbeeldingsindeling altijd OCI.

ContainerImageTag

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

Belangrijk

Wanneer u gebruikt ContainerImageTags, eindigt u met 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 wordt de standaardwaarde niet latestwanneer een tag niet is opgegeven.

Als u de standaardinstelling wilt overschrijven, geeft u een van de volgende eigenschappen 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 eigenschap ContainerImageTags, 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 ContainerImageTags of een MSBuild-eigenschap gebruikt waarvoor -scheidingstekens zijn vereist ;, moet u ervoor zorgen dat u de juiste escape-code gebruikt bij het aanroepen dotnet publish vanaf de opdrachtregel, met name in CI/CD-omgevingen. Escape-regels verschillen tussen PowerShell en Bash. Voorbeeld:

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

In PowerShell moeten zowel de ; als " tekens worden ontsnapt.

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

In Bash hoeft alleen het " teken te worden ontsnapt.

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

Fooi

Als u problemen ondervindt met de eigenschap ContainerImageTags, kunt u in plaats daarvan het bereik van een omgevingsvariabele ContainerImageTags:

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

ContainerLabel

Het containerlabel voegt een metagegevenslabel toe aan de container. Labels 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 knooppunt ContainerLabel 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.

ContainerRepository

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

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

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.

Vlaggen die de metagegevens van de uitvoering beheren

De volgende eigenschappen bepalen runtime-specifiek uitvoeringsgedrag en het genereren van installatiekopieën met meerdere architectuur:

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, wordt deze opdracht meestal dotnet <your project dll>. Deze waarden worden toegepast na een ENTRYPOINT in uw basiscontainer of rechtstreeks als er geen ENTRYPOINT is gedefinieerd.

De ContainerAppCommand-configuratie heeft één Include eigenschap, die de opdracht, optie of het argument vertegenwoordigt dat 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 moeten worden toegepast op de ContainerAppCommand. 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 eigenschap Include, die de optie of het argument vertegenwoordigt die moet worden toegepast op de opdracht 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>

ContainerAppCommandInstruction

Met de instructieconfiguratie van de app-opdracht kunt u bepalen hoe de ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgsen ContainerDefaultArgs 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 er geen van de ContainerEntrypoint[Args] items aanwezig zijn, worden de ContainerAppCommand[Args] en ContainerDefaultArgs gebruikt om het invoerpunt en de opdracht te maken. Het ingangspunt van de basisinstallatiekopieën voor basisinstallatiekopieën waarop het in code is vastgelegd om te dotnet of /usr/bin/dotnet wordt overgeslagen, zodat u volledige controle hebt.
    • Als zowel ContainerEntrypoint als ContainerAppCommand aanwezig zijn, wordt ContainerEntrypoint het invoerpunt en wordt ContainerAppCommand de opdracht.

Notitie

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

Belangrijk

Dit is bedoeld voor geavanceerde gebruikers. De meeste apps hoeven hun ingangspunt niet in deze mate aan te passen. Voor meer informatie en als u gebruikssituaties voor uw scenario's wilt opgeven, zie de discussies over .NET SDK-container builds op GitHub .

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 eigenschap Include, die de optie of het argument vertegenwoordigt die moet worden toegepast op de opdracht 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>

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

Notitie

Het is momenteel niet mogelijk om omgevingsvariabelen in te stellen vanuit de .NET CLI bij het publiceren van een containerinstallatiekopieën. Zie GitHub: .NET SDK-container builds voor meer informatie.

ContainerPort

De containerpoort voegt TCP-poorten (Transmission Control Protocol) of UDP-poorten (User Datagram Protocol) 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 knooppunt ContainerPort heeft twee kenmerken:

  • Include: het poortnummer dat moet worden weergegeven.
  • Type: standaard ingesteld op tcp, geldige waarden zijn tcp of udp.
<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

Vanaf .NET 8 wordt de ContainerPort afgeleid wanneer deze niet expliciet wordt verstrekt 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.

ContainerPublishInParallel

Voor containers met meerdere RID's kunnen bepaalde projecttypen (zoals Blazor WebAssembly) te maken krijgen met racevoorwaarden voor bouwen. U kunt dit oplossen door te beginnen met .NET SDK-versies 8.0.408, 9.0.300 en 10.0, kunt u de parallelle uitvoering van het publicatieproces beheren met behulp van de ContainerPublishInParallel eigenschap. Publicatie vindt standaard parallel plaats voor elke RID (Runtime Identifier). Als u deze eigenschap instelt om sequentiële publicatie te false garanderen, waardoor de stabiliteit toeneemt, maar langer kan duren.

<PropertyGroup>
  <ContainerPublishInParallel>false</ContainerPublishInParallel>
</PropertyGroup>

Zie ContainerRuntimeIdentifier(s) voor meer informatie over het publiceren van meerdere RID's.

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-hoofdgebruiker. 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, username:groupnameen andere 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 rootless gebruiker app gebruikt (hoewel ernaar wordt verwezen door de gebruikers-id)
    • in Windows wordt de ContainerUser van de gebruiker zonder hoofdmap gebruikt
  • Anders wordt er geen standaard ContainerUser gebruikt
<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

Fooi

De omgevingsvariabele APP_UID wordt gebruikt om gebruikersgegevens in uw container in te stellen. 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.

Als u uw app wilt configureren voor uitvoering als hoofdgebruiker, stelt u de eigenschap ContainerUser in op root. Voeg in het projectbestand het volgende toe:

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

U kunt deze waarde ook instellen wanneer u dotnet publish aanroept vanaf de opdrachtregel:

dotnet publish -p ContainerUser=root

ContainerWorkingDirectory

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

Standaard wordt de /app mapwaarde gebruikt als werkmap.

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

Vlaggen die de bestemming van de gegenereerde installatiekopieën bepalen

De volgende eigenschappen bepalen waar de gegenereerde containerinstallatiekopieën worden opgeslagen of gepubliceerd:

ContainerArchiveOutputPath

Als u een containerinstallatiekopieën in een tar.gz archief wilt maken, gebruikt u de ContainerArchiveOutputPath eigenschap. 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 eigenschap ContainerArchiveOutputPath toe aan de opdracht dotnet publish, 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 installatiekopieën $(ContainerRepository).tar.gzgenoemd. Deze archieven kunnen meerdere tags bevatten, alleen omdat er slechts één bestand wordt gemaakt voor alle ContainerImageTags.

ContainerRegistry

De eigenschap containerregister bepaalt het doelregister, de plaats waarnaar de zojuist gemaakte installatiekopieën moeten 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 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.

LocalRegistry

De LocalRegistry eigenschap MSBuild geeft de lokale containerhulpprogramma's op die moeten worden gebruikt bij het pushen naar lokale bronnen. Ondersteunde waarden zijn docker en podman. Als deze niet is ingesteld, bepaalt de SDK het hulpprogramma op basis van beschikbaarheid:

  • Als beide docker en podman bestaan en docker een alias voor podmanis, wordt deze podman gebruikt.
  • Als dit alleen docker bestaat, docker wordt deze gebruikt.
  • Als dit alleen podman bestaat, podman wordt deze gebruikt.
  • Als er geen van beide bestaat, wordt er een fout gegenereerd.

Als u het lokale registerprogramma expliciet wilt instellen, gebruikt u de volgende configuratie:

<PropertyGroup>
  <LocalRegistry>podman</LocalRegistry>
</PropertyGroup>

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 het Microsoft-containerregister).
  • dotnet/runtime is de opslagplaats (maar sommigen beschouwen dit als de user/repository).
  • 8.0-alpine is de tag en familie (de familie is een optionele aanduiding die helpt bij het ondubbelzinnig maken van os-pakketten).

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

Standaardcontainerlabels

Labels worden vaak gebruikt om consistente metagegevens op containerinstallatiekopieën te bieden. De ingebouwde containerhulpprogramma's bieden enkele standaardlabels om de kwaliteit van de gegenereerde installatiekopieën te verhogen. Alle standaardlabelgeneraties kunnen worden uitgeschakeld door in te stellen ContainerGenerateLabels op false. Daarnaast heeft elk standaardlabel een afzonderlijke activeringsvlag die kan worden ingesteld om dat specifieke label uit te false schakelen.

Waar mogelijk bieden bestaande MSBuild-eigenschappen de waarden voor deze labels. Andere eigenschappen bieden expliciete controle over hun waarden.

Aantekening Standaardwaarde Naam van toegewezen eigenschap Naam van terugvaleigenschap Naam van eigenschap ingeschakeld Opmerkingen
org.opencontainers.image.created en org.opencontainers.artifact.created De RFC 3339-indeling van de huidige UTC-datum/tijd ContainerGenerateLabelsImageCreated
org.opencontainers.artifact.description en org.opencontainers.image.description ContainerDescription Description ContainerGenerateLabelsImageDescription
org.opencontainers.image.authors ContainerAuthors Authors ContainerGenerateLabelsImageAuthors
org.opencontainers.image.url ContainerInformationUrl PackageProjectUrl ContainerGenerateLabelsImageUrl
org.opencontainers.image.documentation ContainerDocumentationUrl PackageProjectUrl ContainerGenerateLabelsImageDocumentation
org.opencontainers.image.version ContainerVersion PackageVersion ContainerGenerateLabelsImageVersion
org.opencontainers.image.vendor ContainerVendor ContainerGenerateLabelsImageVendor
org.opencontainers.image.licenses ContainerLicenseExpression PackageLicenseExpression ContainerGenerateLabelsImageLicenses
org.opencontainers.image.title ContainerTitle Title ContainerGenerateLabelsImageTitle
org.opencontainers.image.base.name ContainerBaseImage ContainerGenerateLabelsImageBaseName
org.opencontainers.image.base.digest ContainerGenerateLabelsImageBaseDigest Dit is de SHA-samenvatting van de gekozen basisinstallatiekopieën. Beschikbaar vanaf .NET SDK 9.0.100 en hoger.
org.opencontainers.image.source PrivateRepositoryUrl ContainerGenerateLabelsImageSource Alleen geschreven als PublishRepositoryUrl dat het is true. Is ook afhankelijk van sourcelink-infrastructuur die deel uitmaakt van de build.
org.opencontainers.image.revision SourceRevisionId ContainerGenerateLabelsImageRevision Alleen geschreven als PublishRepositoryUrl dat het is true. Is ook afhankelijk van sourcelink-infrastructuur die deel uitmaakt van de build.

Zie ook

  • Last updated on