.NET-alkalmazáshivatkozás tárolóba helyezése

Ebben a referenciacikkben megtudhatja, hogyan konfigurálhatja a .NET-alkalmazások tárolóként való közzétételekor létrehozott tárolórendszerképet. Ez a cikk a rendszerkép, a végrehajtási környezet és a tároló indításakor futtatott parancsok vezérléséhez beállítható különböző tulajdonságokat ismerteti.

Tárolórendszerkép konfigurálása

A létrehozott tároló számos aspektusát vezérelheti az MSBuild tulajdonságokon keresztül. Általánosságban elmondható, hogy ha egy Dockerfile- parancsával beállíthat néhány konfigurációt, ugyanezt megteheti az MSBuild használatával is.

A .NET SDK-val nem lehet RUN parancsokat végrehajtani. Ezeket a parancsokat gyakran használják operációsrendszer-csomagok telepítéséhez vagy új operációsrendszer-felhasználó létrehozásához, vagy tetszőleges számú dolog létrehozásához. Ha továbbra is a .NET SDK tárolóépítési funkcióját szeretné használni, ehelyett létrehozhat egy egyéni alaprendszerképet ezekkel a módosításokkal, majd használhatja ezt az alaprendszerképet. További információ: ContainerBaseImage.

ContainerArchiveOutputPath

Tárolólemezkép tar.gz archívumban való létrehozásához használja a ContainerArchiveOutputPath tulajdonságot. Ez a funkció akkor hasznos, ha a munkafolyamat nem egyszerű, és például leküldés előtt le kell futtatnia egy ellenőrzőeszközt a képeken. Az archívum létrehozása után áthelyezheti, átvizsgálhatja vagy betöltheti egy helyi Docker-eszközláncba.

Az archívumban való közzétételhez adja hozzá a ContainerArchiveOutputPath tulajdonságot a dotnet publish parancshoz, például:

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

Megadhat egy mappanevet vagy egy adott fájlnévvel rendelkező elérési utat. Ha megadja a mappa nevét, a képarchívumfájlhoz létrehozott fájlnév neve $(ContainerRepository).tar.gz. Ezek az archívumok több címkét is tartalmazhatnak bennük, csak akkor, ha az összes ContainerImageTagsegyetlen fájl jön létre.

Tárolórendszerkép elnevezési konfigurációja

A tárolórendszerképek egy adott elnevezési konvenciót követnek. A rendszerkép neve több részből áll, a beállításjegyzékből, az opcionális portból, az adattárból, valamint az opcionális címkéből és családból.

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

Vegyük például a teljes mcr.microsoft.com/dotnet/runtime:8.0-alpine kép nevét:

• mcr.microsoft.com a beállításjegyzék (ebben az esetben pedig a Microsoft tárolóregisztrációs adatbázisát jelöli).
• dotnet/runtime az adattár (de vannak, akik ezt a user/repository).
• 8.0-alpine a címke és a család (a család egy opcionális kijelölő, amely segít az operációs rendszer csomagolásának egyértelműsítésében).

A következő szakaszokban ismertetett tulajdonságok némelyike megfelel a létrehozott képnév egyes részeinek kezelésének. Vegye figyelembe az alábbi táblázatot, amely a kép neve és a buildtulajdonságok közötti kapcsolatot képezi le:

Az alábbi szakaszok ismertetik a létrehozott tárolólemezkép szabályozására használható különböző tulajdonságokat.

ContainerBaseImage

A tároló alaprendszerkép tulajdonsága szabályozza a rendszerkép alapjául használt rendszerképet. Alapértelmezés szerint a projekt tulajdonságai alapján a következő értékek lesznek kikövetkeztetve:

• Ha a projekt önálló, akkor a mcr.microsoft.com/dotnet/runtime-deps rendszerkép lesz az alaprendszerkép.
• Ha a projekt egy ASP.NET Core-projekt, akkor a rendszer a mcr.microsoft.com/dotnet/aspnet rendszerképet használja alaprendszerképként.
• Ellenkező esetben a rendszer a mcr.microsoft.com/dotnet/runtime rendszerképet használja alapképként.

A rendszer a kép címkéjét a kiválasztott TargetFrameworknumerikus összetevőjének jelöli. Egy net6.0 célzó projekt például a következtetett alaprendszerkép 6.0 címkéjét eredményezi, egy net7.0-linux projekt pedig a 7.0 címkét használja stb.

Ha itt állít be egy értéket, állítsa be a kép teljes nevét alapként, beleértve a kívánt címkét is:

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

A .NET SDK 8.0.200-es verziójával a ContainerBaseImage következtetés javul a méret és a biztonság optimalizálása érdekében:

• A linux-musl-x64 vagy linux-musl-arm64 futtatókörnyezet-azonosítók megcélzása automatikusan kiválasztja a alpine rendszerképvariánsokat a projekt futtatásának biztosítása érdekében:
  • Ha a projekt PublishAot=true használ, akkor az alaprendszerkép nightly/runtime-depsjammy-chiseled-aot változata a legjobb méret és biztonság érdekében.
  • Ha a projekt InvariantGlobalization=false használ, akkor a -extra változatokkal biztosíthatja, hogy a honosítás továbbra is működjön.

A képvariánsok méretével és jellemzőivel kapcsolatos további információkért lásd .NET 8.0 tárolólemezkép-méretjelentés.

ContainerFamily

A .NET 8-tól kezdve az ContainerFamily MSBuild tulajdonsággal választhatja ki a Microsoft által biztosított tárolólemezképek egy másik családját az alkalmazás alapképeként. Ha be van állítva, a rendszer hozzáfűzi ezt az értéket a kijelölt TFM-specifikus címke végéhez, módosítva a megadott címkét. A .NET-alaprendszerképek Alpine Linux-változatainak használatához például beállíthatja ContainerFamilyalpine:

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

Az előző projektkonfiguráció eredménye egy .NET 8-célzási alkalmazás 8.0-alpine végleges címkéje.

Ez a mező szabad formátumú, és gyakran használható különböző operációsrendszer-disztribúciók, alapértelmezett csomagkonfigurációk vagy bármely más alaprendszerkép módosításainak kiválasztására. Ez a mező ContainerBaseImage beállításakor figyelmen kívül lesz hagyva. További információ: .NET-tárolórendszerképek.

ContainerRuntimeIdentifier(s)

A ContainerRuntimeIdentifier tulajdonság határozza meg a tároló operációs rendszerét és architektúráját, ha a ContainerBaseImage több platformot is támogat. A mcr.microsoft.com/dotnet/runtime kép például támogatja a linux-x64, linux-arm, linux-arm64és win10-x64. Alapértelmezés szerint ez a tároló közzétételekor használt RuntimeIdentifier van beállítva. Általában nem kell explicit módon beállítania ezt a tulajdonságot; ehelyett használja a -r lehetőséget a dotnet publish paranccsal. Ha a kiválasztott rendszerkép nem támogatja a megadott RuntimeIdentifier, hiba jelzi a támogatott azonosítókat.

A ContainerBaseImage tulajdonságot mindig beállíthatja teljes képnévre, beleértve a címkét is, hogy egyáltalán ne kelljen használnia ezt a tulajdonságot.

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

Ha több tároló futásidejű azonosítót szeretne megadni több architektúrarendszerképhez, használjon pontosvesszővel tagolt futtatókörnyezet-azonosítókat a ContainerRuntimeIdentifiers tulajdonságban, hasonlóan a több TargetFrameworksbeállításához:

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

A .NET által támogatott futtatókörnyezet-azonosítókkal kapcsolatos további információkért lásd RID-katalógus.

ContainerRegistry

A tárolóregisztrációs adatbázis tulajdonsága szabályozza a célregisztrációs adatbázist, azt a helyet, ahová az újonnan létrehozott rendszerképet leküldi a rendszer. Alapértelmezés szerint a rendszer leküldi a helyi Docker-démonba, de megadhat egy távoli beállításjegyzéket is. Ha hitelesítést igénylő távoli beállításjegyzéket használ, a hitelesítést a jól ismert docker login mechanizmusok használatával végezheti el. További információ: tárolóregisztrációs adatbázisok hitelesítése további részletekért. A tulajdonság használatának konkrét példájához tekintse meg az alábbi XML-példát:

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

Ez az eszközkészlet minden olyan beállításjegyzékben támogatja a közzétételt, amely támogatja a Docker Registry HTTP API V2. Ez explicit módon (és valószínűleg több implicit módon) tartalmazza a következő regisztrációs adatbázisokat:

• Azure Container Registry-
• Amazon Elastic Container Registry
• Google Artifact Registry-
• Docker Hub
• GitHub Packages
• GitLab által üzemeltetett Tárolóregisztrációs adatbázis
• Quay.io

A jegyzékek használatával kapcsolatos megjegyzésekért tekintse meg a beállításjegyzék-specifikus jegyzeteket.

ContainerRepository

A tárolóadattár maga a rendszerkép neve, például dotnet/runtime vagy my-app. Alapértelmezés szerint a program a projekt AssemblyName használja.

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

A képnevek egy vagy több perjellel tagolt szegmensből állnak, amelyek mindegyike csak kisbetűs alfanumerikus karaktereket, pontokat, aláhúzásjeleket és kötőjeleket tartalmazhat, és betűvel vagy számmal kell kezdődnie. Minden más karakter hibát eredményez.

ContainerImageTag(s)

A tárolórendszerképcímke tulajdonság szabályozza a rendszerképhez létrehozott címkéket. Ha egyetlen címkét szeretne megadni, használja ContainerImageTag és több címke esetén használja a ContainerImageTags.

A címkék gyakran hivatkoznak az alkalmazások különböző verzióira, de különböző operációsrendszer-disztribúciókra vagy akár különböző konfigurációkra is hivatkozhatnak.

A .NET 8-tól kezdve, ha egy címke nincs megadva, az alapértelmezett latest.

Az alapértelmezett beállítás felülbírálásához adja meg az alábbiak egyikét:

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

Több címke megadásához használjon pontosvesszővel tagolt címkéket a ContainerImageTags tulajdonságban, hasonlóan a több TargetFrameworksbeállításához:

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

A címkék legfeljebb 127 alfanumerikus karaktert, pontot, aláhúzásjelet és kötőjelet tartalmazhatnak. A karaktereknek alfanumerikus karakterrel vagy aláhúzásjellel kell kezdődniük. Minden más űrlap hibát eredményez.

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

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

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

ContainerLabel

A tárolócímke metaadatcímkét ad hozzá a tárolóhoz. A címkéket gyakran használják a biztonsági szkennerek és más infrastruktúra-eszközök által használt verzió és metaadatok tárolására. Tetszőleges számú tárolócímkét megadhat.

A ContainerLabel csomópont két attribútummal rendelkezik:

• Include: A címke kulcsa.
• Value: A címke értéke (ez üres lehet).

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

Az alapértelmezés szerint létrehozott címkék listáját alapértelmezett tárolócímkékcímű témakörben találja.

Tárolóvégrehajtás konfigurálása

A tároló végrehajtásának szabályozásához az alábbi MSBuild tulajdonságokat használhatja.

ContainerWorkingDirectory

A tároló munkakönyvtár-csomópontja szabályozza a tároló munkakönyvtárát, azt a könyvtárat, amelyen belül a parancsok futnak, ha nem más parancsok futnak.

Alapértelmezés szerint a /app könyvtárértéket használja a rendszer munkakönyvtárként.

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

ContainerPort

A tárolóport hozzáadja a Transmission Control Protocol (TCP) vagy a User Datagram Protocol (UDP) portokat a tároló ismert portjainak listájához. Ez lehetővé teszi, hogy a Dockerhez hasonló tároló-futtatókörnyezetek automatikusan megfeleltetik ezeket a portokat a gazdagépnek. Ezt gyakran használják a tároló dokumentációjaként, de az automatikus portleképezés engedélyezésére is használható.

A ContainerPort csomópont két attribútummal rendelkezik:

• Include: A közzéteendő portszám.
• Type: Az alapértelmezett érték tcp, az érvényes értékek tcp vagy udp.

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

A .NET 8-tól kezdődően a ContainerPort akkor következtetünk, ha a rendszer több jól ismert ASP.NET környezeti változó alapján nem adja meg explicit módon:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

Ha ezek a környezeti változók jelen vannak, az értékeiket a rendszer elemzi és TCP-portleképezésekké alakítja. Ezek a környezeti változók az alaprendszerképből, ha vannak, vagy a projektben definiált környezeti változókból olvasnak be ContainerEnvironmentVariable elemeken keresztül. További információ: ContainerEnvironmentVariable.

ContainerEnvironmentVariable

A tároló környezeti változó csomópontja lehetővé teszi környezeti változók hozzáadását a tárolóhoz. A környezeti változók azonnal elérhetők a tárolóban futó alkalmazás számára, és gyakran használják a futó alkalmazás futásidejének módosítására.

A ContainerEnvironmentVariable csomópont két attribútummal rendelkezik:

• Include: A környezeti változó neve.
• Value: A környezeti változó értéke.

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

További információ: .NET környezeti változók.

Tárolóparancsok konfigurálása

Alapértelmezés szerint a tárolóeszközök elindítják az alkalmazást az alkalmazáshoz létrehozott AppHost bináris fájllal (ha az alkalmazás AppHostot használ), vagy a dotnet parancsot, valamint az alkalmazás DLL-jét.

Az alkalmazás végrehajtásának módját azonban a ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgsés ContainerAppCommandInstructionkombinációjával szabályozhatja.

Ezek a különböző konfigurációs pontok azért léteznek, mert a különböző alaprendszerképek a tároló ENTRYPOINT és COMMAND tulajdonságainak különböző kombinációit használják, és mindegyiket támogatni szeretné. Az alapértelmezett beállításoknak a legtöbb alkalmazáshoz használhatóknak kell lenniük, de ha testre szeretné szabni az alkalmazásindítási viselkedést, tegye a következőt:

• Azonosítsa a futtatandó bináris fájlt, és állítsa be ContainerAppCommand
• Határozza meg, hogy mely argumentumokat szükséges az alkalmazás futtatásához, és állítsa be őket ContainerAppCommandArgs
• Határozza meg, hogy mely argumentumok (ha vannak ilyenek) választható, amelyeket egy felhasználó felülírhat, és beállíthatja őket ContainerDefaultArgs
• ContainerAppCommandInstruction beállítása DefaultArgs

További információkért tekintse meg a következő konfigurációelemeket.

ContainerAppCommand

Az alkalmazás parancskonfigurációs eleme az alkalmazás logikai belépési pontja. A legtöbb alkalmazás esetében ez az AppHost, az alkalmazáshoz létrehozott végrehajtható bináris fájl. Ha az alkalmazás nem hoz létre AppHost-ot, akkor ez a parancs általában dotnet <your project dll>. Ezek az értékek az alaptárolóban lévő ENTRYPOINT után, vagy közvetlenül akkor lesznek alkalmazva, ha nincs definiálva ENTRYPOINT.

A ContainerAppCommand konfiguráció egyetlen Include tulajdonságot tartalmaz, amely az entrypoint parancsban használandó parancsot, beállítást vagy argumentumot jelöli:

<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

Ez az alkalmazásparancs args konfigurációeleme az alkalmazáshoz logikailag szükséges argumentumokat jelöl, amelyeket a ContainerAppCommandkell alkalmazni. Alapértelmezés szerint egyik sem jön létre egy alkalmazáshoz. Ha jelen van, az argek a tárolóra lesznek alkalmazva a futtatáskor.

A ContainerAppCommandArgs konfiguráció egyetlen Include tulajdonságot tartalmaz, amely a ContainerAppCommand parancsra alkalmazandó beállítást vagy argumentumot jelöli.

<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

Ez az alapértelmezett args konfigurációelem az alkalmazás felhasználó által felülírható argumentumait jelöli. Ez egy jó módja annak, hogy olyan alapértelmezett beállításokat biztosítson, amelyeket az alkalmazásnak olyan módon kell futtatnia, amely megkönnyíti az indítást, de mégis könnyen testre szabható.

A ContainerDefaultArgs konfiguráció egyetlen Include tulajdonságot tartalmaz, amely a ContainerAppCommand parancsra alkalmazandó beállítást vagy argumentumot jelöli.

<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

Az alkalmazásparancs utasításkonfigurációja segít szabályozni a ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgsés ContainerDefaultArgs együttes használatát a tárolóban futtatott utolsó parancs létrehozásához. Ez nagyban függ attól, hogy egy ENTRYPOINT szerepel-e az alaprendszerképben. Ez a tulajdonság a következő három érték egyikét veszi fel: "DefaultArgs", "Entrypoint"vagy "None".

• Entrypoint:
  • Ebben a módban a belépési pontot ContainerAppCommand, ContainerAppCommandArgsés ContainerDefaultArgshatározza meg.
• None:
  • Ebben a módban a belépési pontot ContainerEntrypoint, ContainerEntrypointArgsés ContainerDefaultArgshatározza meg.
• DefaultArgs:
  • Ez a legösszetettebb mód – ha a ContainerEntrypoint[Args] elemek egyike sem található meg, akkor a ContainerAppCommand[Args] és a ContainerDefaultArgs használják a belépési pont és a parancs létrehozásához. A rendszer kihagyja a nehezen kódolt alapképek belépési pontját dotnet vagy /usr/bin/dotnet, hogy teljes mértékben szabályozhassa a rendszer.
  • Ha ContainerEntrypoint és ContainerAppCommand is jelen van, akkor ContainerEntrypoint lesz a belépési pont, és ContainerAppCommand lesz a parancs.

ContainerUser

A felhasználó konfigurációs tulajdonsága vezérli azt az alapértelmezett felhasználót, akiként a tároló fut. Ezt gyakran használják a tároló nem gyökérfelhasználóként való futtatására, ami a biztonság szempontjából ajánlott eljárás. Ennek a konfigurációnak néhány korlátozást figyelembe kell vennie:

• Különböző űrlapokat vehet fel, például felhasználónevet, linuxos felhasználói azonosítókat, csoportnevet, linuxos csoportazonosítót, username:groupnameés egyéb azonosítóvariánsokat.
• Nincs ellenőrzés arról, hogy a megadott felhasználó vagy csoport létezik-e a képen.
• A felhasználó módosítása megváltoztathatja az alkalmazás viselkedését, különösen az olyan dolgok tekintetében, mint fájlrendszer engedélyek.

A mező alapértelmezett értéke a projekt TFM-étől és a cél operációs rendszertől függően változik:

• Ha a .NET 8-at vagy újabb verziót célozza meg, és a Microsoft futtatókörnyezeti rendszerképeket használja, akkor:
  • Linux rendszeren a rendszer a gyökér nélküli app használja (bár a felhasználói azonosítója hivatkozik rá)
  • Windows rendszeren a rendszer a gyökér nélküli felhasználói ContainerUser használja
• Ellenkező esetben a rendszer nem használ alapértelmezett ContainerUser

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

Ha úgy szeretné konfigurálni az alkalmazást, hogy gyökérfelhasználóként fusson, állítsa a ContainerUser tulajdonságot root. A projektfájlban adja hozzá a következőket:

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

Ezt az értéket a parancssorból dotnet publish hívásakor is beállíthatja:

dotnet publish -p ContainerUser=root

Alapértelmezett tárolófeliratok

A címkék gyakran konzisztens metaadatokat biztosítanak a tárolólemezképeken. Ez a csomag néhány alapértelmezett címkét biztosít a létrehozott képek jobb karbantarthatóságának elősegítése érdekében.

• org.opencontainers.image.created a DateTime.UtcNowaktuális értékének ISO 8601 formátumára van állítva.

További információ: Hagyományos címkék implementálása a meglévő címkeinfrastruktúra.

Lásd még:

• .NET-alkalmazás tárolóba helyezése dotnet közzétételi
• .NET-tárolórendszerképek