Udostępnij przez

Konteneryzowanie dokumentacji aplikacji .NET

Z tego artykułu referencyjnego dowiesz się, jak skonfigurować obraz kontenera wygenerowany podczas publikowania aplikacji platformy .NET jako kontenera. W tym artykule opisano różne właściwości, które można ustawić w celu kontrolowania obrazu, środowiska wykonywania i poleceń uruchamianych po uruchomieniu kontenera.

Konfigurowanie właściwości kontenera

Możesz kontrolować wiele aspektów wygenerowanego kontenera za pomocą właściwości programu MSBuild. Ogólnie rzecz biorąc, jeśli możesz użyć polecenia w pliku Dockerfile w celu ustawienia konfiguracji, możesz to zrobić za pośrednictwem programu MSBuild.

Nuta

Jedynymi wyjątkami od tego są RUN polecenia. Ze względu na sposób tworzenia kontenerów te polecenia nie mogą być emulowane. Jeśli potrzebujesz tej funkcji, rozważ użycie pliku Dockerfile do kompilowania obrazów kontenerów.

Nie ma możliwości wykonywania RUN poleceń za pomocą zestawu SDK platformy .NET. Te polecenia są często używane do instalowania niektórych pakietów systemu operacyjnego lub tworzenia nowego użytkownika systemu operacyjnego lub dowolnej liczby dowolnych elementów. Jeśli chcesz nadal korzystać z funkcji tworzenia kontenera zestawu .NET SDK, możesz zamiast tego utworzyć niestandardowy obraz podstawowy z tymi zmianami, a następnie użyć tego obrazu podstawowego. Aby uzyskać więcej informacji, zobacz ContainerBaseImage.

Flagi kontrolujące obraz podstawowy

Następujące właściwości określają, który obraz podstawowy jest używany dla kontenera i jak jest wybrany:

ContainerBaseImage

Właściwość obrazu podstawowego kontenera kontroluje obraz używany jako podstawa obrazu. Domyślnie następujące wartości są wnioskowane na podstawie właściwości projektu:

  • Jeśli projekt jest samodzielny, obraz mcr.microsoft.com/dotnet/runtime-deps jest używany jako obraz podstawowy.
  • Jeśli projekt jest projektem ASP.NET Core, obraz mcr.microsoft.com/dotnet/aspnet jest używany jako obraz podstawowy.
  • W przeciwnym razie obraz mcr.microsoft.com/dotnet/runtime jest używany jako obraz podstawowy.

Tag obrazu jest wnioskowany jako składnik liczbowy wybranego TargetFramework. Na przykład projekt docelowy net6.0 powoduje, że tag 6.0 wnioskowanego obrazu podstawowego, a projekt net7.0-linux używa tagu 7.0 itd.

Jeśli ustawisz tutaj wartość, należy ustawić w pełni kwalifikowaną nazwę obrazu, która będzie używana jako podstawa, w tym dowolny tag:

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

W przypadku zestawu .NET SDK w wersji 8.0.200 ulepszono wnioskowanie ContainerBaseImage w celu zoptymalizowania rozmiaru i zabezpieczeń:

  • Określanie wartości docelowej identyfikatorów linux-musl-x64 lub identyfikatorów środowiska uruchomieniowego linux-musl-arm64 automatycznie wybiera warianty obrazu alpine, aby upewnić się, że projekt zostanie uruchomiony:
    • Jeśli projekt używa PublishAot=true, nightly/runtime-depsjammy-chiseled-aot wariant obrazu podstawowego w celu uzyskania najlepszego rozmiaru i bezpieczeństwa.
    • Jeśli projekt używa InvariantGlobalization=false, -extra warianty są używane do zapewnienia, że lokalizacja nadal działa.

Aby uzyskać więcej informacji na temat rozmiarów i cech obrazu, zobacz Raport rozmiaru obrazu kontenera platformy .NET 8.0.

ContainerFamily

Począwszy od platformy .NET 8, możesz użyć właściwości ContainerFamily MSBuild, aby wybrać inną rodzinę obrazów kontenerów udostępnianych przez firmę Microsoft jako podstawowy obraz aplikacji. Po ustawieniu ta wartość jest dołączana na końcu wybranego tagu specyficznego dla programu TFM, zmieniając podany tag. Aby na przykład użyć wariantów alpine Linux podstawowych obrazów platformy .NET, można ustawić ContainerFamily na alpine:

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

Poprzednia konfiguracja projektu powoduje wyświetlenie końcowego tagu 8.0-alpine dla aplikacji przeznaczonej dla platformy .NET 8.

To pole jest wolne i często może służyć do wybierania różnych dystrybucji systemu operacyjnego, domyślnych konfiguracji pakietów lub innych zmian w obrazie podstawowym. To pole jest ignorowane po ustawieniu ContainerBaseImage. Aby uzyskać więcej informacji, zobacz Obrazy kontenerów platformy .NET.

ContainerRuntimeIdentifier(s)

Właściwość ContainerRuntimeIdentifier określa system operacyjny i architekturę kontenera, jeśli ContainerBaseImage obsługuje wiele platform. Na przykład obraz mcr.microsoft.com/dotnet/runtime obsługuje linux-x64, linux-arm, linux-arm64i win10-x64. Domyślnie jest to ustawienie RuntimeIdentifier używane podczas publikowania kontenera. Zazwyczaj nie trzeba jawnie ustawiać tej właściwości; Zamiast tego użyj opcji -r z poleceniem dotnet publish. Jeśli wybrany obraz nie obsługuje określonego RuntimeIdentifier, błąd wskazuje obsługiwane identyfikatory.

Zawsze można ustawić właściwość ContainerBaseImage na w pełni kwalifikowaną nazwę obrazu, w tym tag, aby uniknąć konieczności używania tej właściwości w ogóle.

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

Aby określić wiele identyfikatorów środowiska uruchomieniowego kontenera dla obrazów z wieloma architekturami, użyj rozdzielanego średnikami zestawu identyfikatorów środowiska uruchomieniowego we właściwości ContainerRuntimeIdentifiers, podobnie jak ustawienie wielu TargetFrameworks:

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

Ważny

Właściwość ContainerRuntimeIdentifiers musi być podzbiorem RuntimeIdentifiers właściwości . Jeśli ten warunek nie zostanie spełniony, krytyczne części potoku kompilacji mogą zakończyć się niepowodzeniem.

Ustawianie wielu ContainerRuntimeIdentifiers wyników w tworzonym obrazie z wieloma architekturami. Aby uzyskać więcej informacji, zobacz Obrazy z wieloma architekturami.

Aby uzyskać więcej informacji na temat identyfikatorów środowiska uruchomieniowego obsługiwanych przez platformę .NET, zobacz w katalogu RID .

Obrazy z wieloma architekturami

Obrazy z wieloma architekturami umożliwiają obsługę wielu architektur w jednym obrazie kontenera, co upraszcza tworzenie i wdrażanie międzyplatformowe. Zestaw .NET SDK obsługuje tę funkcję za pośrednictwem ContainerRuntimeIdentifiers właściwości .

Począwszy od zestawu SDK w wersji 8.0.405, 9.0.102 i 9.0.2xx, obsługiwane jest publikowanie kontenerów z wieloma identyfikatorami RID. Podczas publikowania za pomocą polecenia /t:PublishContainer:

  • Jeśli zostanie określony pojedynczy RuntimeIdentifier kontener lub ContainerRuntimeIdentifier zostanie określony, zostanie wygenerowany kontener z jedną architekturą tak jak poprzednio.
  • Jeśli nie określono pojedynczego elementu RuntimeIdentifier , ale wiele RuntimeIdentifiers lub ContainerRuntimeIdentifiers są ustawione, zestaw SDK publikuje aplikację dla każdego określonego identyfikatora RID i łączy wynikowe obrazy w indeks obrazu OCI. Ten indeks umożliwia udostępnianie pojedynczej nazwy wielu obrazów specyficznych dla architektury.

Nuta

Właściwość ContainerRuntimeIdentifiers musi być podzbiorem RuntimeIdentifiers właściwości . Aby uzyskać więcej informacji, zobacz ContainerRuntimeIdentifiers.

Ta funkcja usprawnia przepływy pracy kontenerów w środowiskach architektury mieszanej. Na przykład deweloper na linux-x64 hoście może opublikować kontener obsługujący zarówno architekturę, jak linux-x64 i linux-arm64, umożliwiając wdrożenie w architekturze bez zmieniania nazw obrazów lub etykiet.

Wygenerowany indeks obrazów OCI jest powszechnie obsługiwany za pomocą nowoczesnych narzędzi kontenerów, zwiększając zgodność i łatwość użycia.

Flagi kontrolujące metadane niezależne od obrazu

Następujące właściwości kontrolują metadane i konfigurację, które mają zastosowanie do wygenerowanego obrazu kontenera niezależnie od docelowego identyfikatora środowiska uruchomieniowego:

ContainerImageFormat

Możesz użyć ContainerImageFormat właściwości MSBuild, aby określić format obrazu jako Docker lub OCI. Domyślnie narzędzia platformy .NET wywnioskuje format z obrazu podstawowego. Na przykład podstawowe obrazy platformy .NET używają formatu application/vnd.docker.distribution.manifest.v2+jsonspecyficznego dla platformy Docker. Jednak wiele nowoczesnych narzędzi preferuje format application/vnd.oci.image.manifest.v1+jsonOCI . Aby wymusić określony format, ustaw właściwość w następujący sposób:

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

Oba formaty są w dużej mierze wymienne bez utraty informacji.

Nuta

Podczas tworzenia obrazu z wieloma architekturami wynikowy format obrazu jest zawsze OCI.

ContainerImageTag

Właściwość tagu obrazu kontenera steruje tagami wygenerowanymi dla obrazu. Aby określić pojedynczy tag, użyj ContainerImageTag, a w przypadku wielu tagów użyj ContainerImageTags.

Ważny

Gdy używasz metody ContainerImageTags, kończy się to wieloma obrazami, po jednym na unikatowy tag.

Tagi są często używane do odwoływania się do różnych wersji aplikacji, ale mogą również odwoływać się do różnych dystrybucji systemu operacyjnego, a nawet różnych konfiguracji.

Począwszy od platformy .NET 8, jeśli tag nie jest podany, wartość domyślna to latest.

Aby zastąpić wartość domyślną, określ jedną z następujących właściwości:

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

Aby określić wiele tagów, użyj rozdzielanego średnikami zestawu tagów we właściwości ContainerImageTags, podobnie jak w przypadku ustawiania wielu TargetFrameworks:

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

Tagi mogą zawierać maksymalnie 127 znaków alfanumerycznych, kropki, podkreślenia i kreski. Muszą zaczynać się od znaku alfanumerycznego lub podkreślenia. Każdy inny formularz powoduje zgłoszenie błędu.

Nuta

W przypadku używania ContainerImageTags lub dowolnej właściwości MSBuild wymagającej ;wartości rozdzielanych upewnij się, że podczas wywoływania wywołania dotnet publish z wiersza polecenia, szczególnie w środowiskach ciągłej integracji/ciągłego wdrażania. Reguły ucieczki różnią się między programem PowerShell i powłoką Bash. Przykład:

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

W programie PowerShell należy stosować znaki ; i ".

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

W powłoce Bash należy stosować tylko znak ".

Spowoduje to wygenerowanie dwóch obrazów: my-app:1.2.3-alpha2 i my-app:latest.

Napiwek

Jeśli występują problemy z właściwością ContainerImageTags, rozważ określenie zakresu zmiennej środowiskowej ContainerImageTags zamiast tego:

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

ContainerLabel

Etykieta kontenera dodaje etykietę metadanych do kontenera. Etykiety są często używane do przechowywania wersji i tworzenia metadanych do użycia przez skanery zabezpieczeń i inne narzędzia infrastruktury. Można określić dowolną liczbę etykiet kontenera.

Węzeł ContainerLabel ma dwa atrybuty:

  • Include: klucz etykiety.
  • Value: wartość etykiety (może to być puste).
<ItemGroup>
    <ContainerLabel Include="org.contoso.businessunit" Value="contoso-university" />
</ItemGroup>

Aby uzyskać listę etykiet, które są tworzone domyślnie, zobacz domyślne etykiety kontenerów.

ContainerRepository

Repozytorium kontenerów jest nazwą samego obrazu, na przykład dotnet/runtime lub my-app. Domyślnie jest używana AssemblyName projektu.

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

Nazwy obrazów składają się z co najmniej jednego segmentu rozdzielanego ukośnikiem, z których każda może zawierać tylko małe litery alfanumeryczne znaki, kropki, podkreślenia i kreski, i musi zaczynać się literą lub cyfrą. Wszelkie inne znaki powodują zgłoszenie błędu.

Flagi kontrolujące metadane wykonywania

Następujące właściwości kontrolują zachowanie wykonywania specyficzne dla środowiska uruchomieniowego i generowanie obrazów z wieloma architekturami:

ContainerAppCommand

Element konfiguracji polecenia aplikacji jest logicznym punktem wejścia aplikacji. W przypadku większości aplikacji jest to host AppHost, wygenerowany plik binarny pliku wykonywalnego dla aplikacji. Jeśli aplikacja nie generuje hosta AppHost, to polecenie jest zwykle dotnet <your project dll>. Te wartości są stosowane po każdym ENTRYPOINT w kontenerze podstawowym lub bezpośrednio, jeśli nie zdefiniowano ENTRYPOINT.

Konfiguracja ContainerAppCommand ma pojedynczą właściwość Include, która reprezentuje polecenie, opcję lub argument do użycia w poleceniu punktu wejścia:

<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

To polecenie aplikacji args element konfiguracji reprezentuje wszystkie logicznie wymagane argumenty dla aplikacji, które powinny być stosowane do ContainerAppCommand. Domyślnie żadna z nich nie jest generowana dla aplikacji. Gdy element args jest obecny, są stosowane do kontenera podczas jego uruchamiania.

Konfiguracja ContainerAppCommandArgs ma jedną właściwość Include, która reprezentuje opcję lub argument do zastosowania do polecenia 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

Konfiguracja instrukcji polecenia aplikacji pomaga kontrolować sposób, w jaki ContainerEntrypoint, , ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgsi ContainerDefaultArgs są łączone w celu utworzenia końcowego polecenia, które jest uruchamiane w kontenerze. Jest to bardzo zależne od tego, czy ENTRYPOINT znajduje się na obrazie podstawowym. Ta właściwość przyjmuje jedną z trzech wartości: "DefaultArgs", "Entrypoint"lub "None".

  • Entrypoint:
    • W tym trybie punkt wejścia jest definiowany przez ContainerAppCommand, ContainerAppCommandArgsi ContainerDefaultArgs.
  • None:
    • W tym trybie punkt wejścia jest definiowany przez ContainerEntrypoint, ContainerEntrypointArgsi ContainerDefaultArgs.
  • DefaultArgs:
    • Jest to najbardziej złożony tryb — jeśli żaden z elementów ContainerEntrypoint[Args] nie istnieje, ContainerAppCommand[Args] i ContainerDefaultArgs są używane do tworzenia punktu wejścia i polecenia. Punkt wejścia obrazu podstawowego dla obrazów bazowych, których kodowanie jest trudne do dotnet lub /usr/bin/dotnet, jest pomijane, aby mieć pełną kontrolę.
    • Jeśli istnieją zarówno ContainerEntrypoint, jak i ContainerAppCommand, ContainerEntrypoint staje się punktem wejścia, a ContainerAppCommand staje się poleceniem .

Nuta

Elementy konfiguracji ContainerEntrypoint i ContainerEntrypointArgs są przestarzałe od platformy .NET 8.

Ważny

Jest to przeznaczone dla zaawansowanych aplikacji korzystających z większości użytkowników, które nie powinny dostosowywać punktu wejścia do tego stopnia. Aby uzyskać więcej informacji i jeśli chcesz podać przypadki użycia dla Twoich scenariuszy, zobacz GitHub: kontener .NET SDK tworzy dyskusje.

ContainerDefaultArgs

Ten domyślny element konfiguracji args reprezentuje wszystkie argumenty, które można zastąpić użytkownika dla aplikacji. Jest to dobry sposób zapewnienia domyślnych ustawień domyślnych, które aplikacja może wymagać uruchomienia w sposób, który ułatwia rozpoczęcie pracy, ale nadal jest łatwy do dostosowania.

Konfiguracja ContainerDefaultArgs ma jedną właściwość Include, która reprezentuje opcję lub argument do zastosowania do polecenia 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

Węzeł zmiennej środowiskowej kontenera umożliwia dodawanie zmiennych środowiskowych do kontenera. Zmienne środowiskowe są natychmiast dostępne dla aplikacji uruchomionej w kontenerze i często są używane do zmiany zachowania środowiska uruchomieniowego uruchomionej aplikacji.

Węzeł ContainerEnvironmentVariable ma dwa atrybuty:

  • Include: nazwa zmiennej środowiskowej.
  • Value: wartość zmiennej środowiskowej.
<ItemGroup>
  <ContainerEnvironmentVariable Include="LOGGER_VERBOSITY" Value="Trace" />
</ItemGroup>

Aby uzyskać więcej informacji, zobacz Zmienne środowiskowe platformy .NET.

Nuta

Obecnie nie można ustawić zmiennych środowiskowych z interfejsu wiersza polecenia platformy .NET podczas publikowania obrazu kontenera. Aby uzyskać więcej informacji, zobacz GitHub: kompilacje kontenera zestawu .NET SDK.

ContainerPort

Port kontenera dodaje porty Protokołu TCP (Transmission Control Protocol) lub User Datagram Protocol (UDP) do listy znanych portów dla kontenera. Dzięki temu środowiska uruchomieniowe kontenera, takie jak Platforma Docker, automatycznie mapują te porty na maszynę hosta. Jest to często używane jako dokumentacja kontenera, ale może być również używane do włączania automatycznego mapowania portów.

Węzeł ContainerPort ma dwa atrybuty:

  • Include: numer portu do uwidocznienia.
  • Type: wartości domyślne tcp, prawidłowe wartości to tcp lub udp.
<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

Począwszy od platformy .NET 8, ContainerPort jest wnioskowana, gdy nie jest jawnie podana na podstawie kilku dobrze znanych zmiennych środowiskowych ASP.NET:

  • ASPNETCORE_URLS
  • ASPNETCORE_HTTP_PORTS
  • ASPNETCORE_HTTPS_PORTS

Jeśli te zmienne środowiskowe są obecne, ich wartości są analizowane i konwertowane na mapowania portów TCP. Te zmienne środowiskowe są odczytywane z obrazu podstawowego, jeśli istnieje, lub ze zmiennych środowiskowych zdefiniowanych w projekcie za pośrednictwem elementów ContainerEnvironmentVariable. Aby uzyskać więcej informacji, zobacz ContainerEnvironmentVariable.

ContainerPublishInParallel

W przypadku kontenerów z wieloma identyfikatorami RID niektóre typy projektów (takie jak Zestaw WebAssembly platformy Blazor) mogą napotkać warunki wyścigu kompilacji. Aby rozwiązać ten problem, począwszy od zestawu .NET SDK w wersji 8.0.408, 9.0.300 i 10.0, można kontrolować równoległość procesu publikowania przy użyciu ContainerPublishInParallel właściwości . Domyślnie publikowanie odbywa się równolegle dla każdego identyfikatora środowiska uruchomieniowego (RID). Ustawienie tej właściwości w celu false zapewnienia sekwencyjnego publikowania, co zwiększa stabilność, ale może trwać dłużej.

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

Aby uzyskać więcej informacji na temat publikowania wielu identyfikatorów RID, zobacz ContainerRuntimeIdentifier(s).

ContainerUser

Właściwość konfiguracji użytkownika steruje domyślnym użytkownikiem, na który działa kontener. Jest to często używane do uruchamiania kontenera jako użytkownik niebędący użytkownikiem głównym, co jest najlepszym rozwiązaniem w zakresie zabezpieczeń. Istnieje kilka ograniczeń dotyczących tej konfiguracji, o których należy pamiętać:

  • Może ona mieć różne formy — nazwy użytkownika, identyfikatorów użytkowników systemu Linux, nazwy grupy, identyfikatora grupy systemu Linux, username:groupnamei innych wariantów identyfikatorów.
  • Nie ma weryfikacji, czy określony użytkownik lub grupa istnieje na obrazie.
  • Zmiana użytkownika może zmienić zachowanie aplikacji, zwłaszcza w odniesieniu do takich rzeczy, jak uprawnienia systemu plików .

Wartość domyślna tego pola różni się w zależności od programu PROJECT TFM i docelowego systemu operacyjnego:

  • Jeśli wybierasz platformę .NET 8 lub nowszą i używasz obrazów środowiska uruchomieniowego firmy Microsoft, wykonaj następujące działania:
    • w systemie Linux jest używany app użytkownika bez root (choć jest przywołyny przez jego identyfikator użytkownika)
    • w systemie Windows jest używany ContainerUser użytkownika bez root
  • W przeciwnym razie nie jest używana żadna domyślna ContainerUser
<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

Napiwek

Zmienna środowiskowa APP_UID służy do ustawiania informacji o użytkowniku w kontenerze. Ta wartość może pochodzić ze zmiennych środowiskowych zdefiniowanych w obrazie podstawowym (tak jak w przypadku obrazów platformy Microsoft .NET) lub można ustawić ją samodzielnie za pomocą składni ContainerEnvironmentVariable.

Aby skonfigurować aplikację do uruchamiania jako użytkownik główny, ustaw właściwość ContainerUser na root. W pliku projektu dodaj następujące elementy:

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

Alternatywnie tę wartość można ustawić podczas wywoływania dotnet publish z wiersza polecenia:

dotnet publish -p ContainerUser=root

ContainerWorkingDirectory

Węzeł katalogu roboczego kontenera kontroluje katalog roboczy kontenera, katalog, w ramach którego są wykonywane polecenia, jeśli nie zostanie uruchomione inne polecenie.

Domyślnie wartość katalogu /app jest używana jako katalog roboczy.

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

Flagi kontrolujące miejsce docelowe wygenerowanego obrazu

Następująca kontrolka właściwości, w której jest przechowywany lub publikowany wygenerowany obraz kontenera:

ContainerArchiveOutputPath

Aby utworzyć obraz kontenera w tar.gz archiwum, użyj ContainerArchiveOutputPath właściwości . Ta funkcja jest przydatna, jeśli przepływ pracy nie jest prosty i wymaga na przykład uruchomienia narzędzia do skanowania obrazów przed ich wypchnięciem. Po utworzeniu archiwum można go przenieść, zeskanować lub załadować do lokalnego łańcucha narzędzi platformy Docker.

Aby opublikować w archiwum, dodaj właściwość ContainerArchiveOutputPath do polecenia dotnet publish, na przykład:

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

Możesz określić nazwę folderu lub ścieżkę o określonej nazwie pliku. Jeśli określisz nazwę folderu, nazwa pliku wygenerowana dla pliku archiwum obrazów nosi nazwę $(ContainerRepository).tar.gz. Te archiwa mogą zawierać wiele tagów w nich, tylko w przypadku utworzenia pojedynczego pliku dla wszystkich ContainerImageTags.

ContainerRegistry

Właściwość rejestru kontenerów kontroluje rejestr docelowy— miejsce, do którego ma zostać wypchnięty nowo utworzony obraz. Domyślnie jest on wypychany do lokalnego demona platformy Docker, ale można również określić rejestr zdalny. W przypadku korzystania z rejestru zdalnego wymagającego uwierzytelniania należy uwierzytelnić się przy użyciu dobrze znanych mechanizmów docker login. Aby uzyskać więcej informacji, zobacz Uwierzytelnianie w rejestrach kontenerów , aby uzyskać więcej informacji. Aby uzyskać konkretny przykład użycia tej właściwości, rozważmy następujący przykład XML:

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

To narzędzie obsługuje publikowanie w dowolnym rejestrze, który obsługuje interfejs API HTTP rejestru platformy Docker w wersji 2. Obejmuje to jawnie następujące rejestry (i prawdopodobnie znacznie więcej niejawnie):

  • usługi Azure Container Registry
  • usługi Amazon Elastic Container Registry
  • usługi Google Artifact Registry
  • Docker Hub
  • Pakiety GitHub
  • usługi Container Registry hostowanej w narzędziu GitLab
  • Quay.io

Uwagi dotyczące pracy z tymi rejestrami można znaleźć w uwagach specyficznych dla rejestru.

LocalRegistry

Właściwość LocalRegistry MSBuild określa narzędzia kontenera lokalnego do użycia podczas wypychania do źródeł lokalnych. Obsługiwane wartości to docker i podman. Jeśli nie zostanie ustawiona, zestaw SDK określi narzędzie na podstawie dostępności:

  • Jeśli zarówno docker , jak i podman istnieje, i docker jest alias dla podman, podman jest używany.
  • Jeśli istnieje tylko docker , docker jest używany.
  • Jeśli istnieje tylko podman , podman jest używany.
  • Jeśli żadna z nich nie istnieje, zostanie zgłoszony błąd.

Aby jawnie ustawić narzędzie rejestru lokalnego, użyj następującej konfiguracji:

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

Konfiguracja nazewnictwa obrazów kontenera

Obrazy kontenerów są zgodne z konkretną konwencją nazewnictwa. Nazwa obrazu składa się z kilku części, rejestru, opcjonalnego portu, repozytorium oraz opcjonalnego tagu i rodziny.

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

Rozważmy na przykład w pełni kwalifikowaną nazwę obrazu mcr.microsoft.com/dotnet/runtime:8.0-alpine:

  • mcr.microsoft.com jest rejestrem (a w tym przypadku reprezentuje rejestr kontenerów firmy Microsoft).
  • dotnet/runtime to repozytorium (ale niektórzy uważają to za user/repository).
  • 8.0-alpine to tag i rodzina (rodzina jest opcjonalnym specyfikatorem, który pomaga uściślać pakowanie systemu operacyjnego).

Niektóre właściwości opisane w poniższych sekcjach odpowiadają zarządzaniu częściami wygenerowanej nazwy obrazu. Rozważmy następującą tabelę, która mapuje relację między nazwą obrazu a właściwościami kompilacji:

Część nazwy obrazu Właściwość MSBuild Przykładowe wartości
REGISTRY[:PORT] ContainerRegistry mcr.microsoft.com:443
PORT ContainerPort :443
REPOSITORY ContainerRepository dotnet/runtime
TAG ContainerImageTag 8.0
FAMILY ContainerFamily -alpine

Domyślne etykiety kontenerów

Etykiety są często używane do zapewnienia spójnych metadanych na obrazach kontenerów. Wbudowane narzędzia kontenerów udostępniają niektóre etykiety domyślne, aby zwiększyć jakość wygenerowanych obrazów. Wszystkie domyślne generowanie etykiet można wyłączyć, ustawiając wartość ContainerGenerateLabelsfalse. Ponadto każda etykieta domyślna ma pojedynczą flagę włączania, którą można ustawić, aby false wyłączyć tę konkretną etykietę.

Jeśli to możliwe, istniejące właściwości programu MSBuild zawierają wartości dla tych etykiet. Inne właściwości umożliwiają jawną kontrolę ich wartości.

Adnotacja Wartość domyślna Nazwa właściwości dedykowanej Nazwa właściwości rezerwowej Nazwa właściwości włączonej Notatki
org.opencontainers.image.created i org.opencontainers.artifact.created Format RFC 3339 bieżącej daty/godziny UTC ContainerGenerateLabelsImageCreated
org.opencontainers.artifact.description i 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 Jest to skrót SHA wybranego obrazu podstawowego. Dostępne od wersji 9.0.100 zestawu .NET SDK.
org.opencontainers.image.source PrivateRepositoryUrl ContainerGenerateLabelsImageSource Napisane tylko wtedy, gdy PublishRepositoryUrl ma wartość true. Opiera się również na infrastrukturze Sourcelink będącej częścią kompilacji.
org.opencontainers.image.revision SourceRevisionId ContainerGenerateLabelsImageRevision Napisane tylko wtedy, gdy PublishRepositoryUrl ma wartość true. Opiera się również na infrastrukturze Sourcelink będącej częścią kompilacji.

Zobacz też

  • Last updated on