Контейнеризация ссылки на приложение .NET

В этой справочной статье вы узнаете, как настроить образ контейнера, созданный при публикации приложения .NET в качестве контейнера. В этой статье рассматриваются различные свойства, которые можно задать для управления изображением, средой выполнения и командами, выполняемыми при запуске контейнера.

Настройка образа контейнера

Вы можете управлять многими аспектами созданного контейнера с помощью свойств MSBuild. Как правило, если вы можете использовать команду в Dockerfile для задания определенной конфигурации, можно сделать это с помощью MSBuild.

Заметка

Единственными исключениями являются команды RUN. Из-за того, как создаются контейнеры, они не могут быть эмулированы. Если вам нужна эта функция, можно использовать Dockerfile для создания образов контейнеров.

Нет способа выполнения RUN команд с помощью пакета SDK для .NET. Эти команды часто используются для установки некоторых пакетов ОС или создания нового пользователя ОС или любого количества произвольных вещей. Если вы хотите продолжать использовать функцию создания контейнеров пакета SDK для .NET, можно создать настраиваемый базовый образ с этими изменениями, а затем использовать этот базовый образ. Дополнительные сведения см. в ContainerBaseImage.

ContainerArchiveOutputPath

Чтобы создать образ контейнера в архиве tar.gz, используйте свойство ContainerArchiveOutputPath. Эта функция полезна, если рабочий процесс не прост и требует, чтобы вы, например, запустите средство сканирования по изображениям, прежде чем отправлять их. После создания архива его можно переместить, проверить или загрузить его в локальную цепочку инструментов Docker.

Чтобы опубликовать в архиве, добавьте свойство ContainerArchiveOutputPath в команду dotnet publish, например:

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

Можно указать имя папки или путь с определенным именем файла. Если указать имя папки, имя файла, созданное для файла архива образа, называется $(ContainerRepository).tar.gz. Эти архивы могут содержать несколько тегов внутри них, только так как один файл создается для всех ContainerImageTags.

Конфигурация именования образов контейнера

Образы контейнеров соответствуют определенному соглашению об именовании. Имя образа состоит из нескольких частей, реестра, необязательного порта, репозитория и дополнительного тега и семейства.

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

Например, рассмотрим полное имя образа mcr.microsoft.com/dotnet/runtime:8.0-alpine:

• mcr.microsoft.com является реестром (в данном случае представляет реестр контейнеров Майкрософт).
• dotnet/runtime — это репозиторий (но некоторые считают это user/repository).
• 8.0-alpine — это тег и семейство (семейство является необязательным описателям, помогающим использовать упаковку ОС дизамбигуата).

Некоторые свойства, описанные в следующих разделах, соответствуют управлению частями созданного имени образа. Рассмотрим следующую таблицу, которая сопоставляет связь между именем образа и свойствами сборки:

Часть имени изображения	Свойство MSBuild	Примеры значений
REGISTRY[:PORT]	ContainerRegistry	mcr.microsoft.com:443
PORT	ContainerPort	:443
REPOSITORY	ContainerRepository	dotnet/runtime
TAG	ContainerImageTag	8.0
FAMILY	ContainerFamily	-alpine

В следующих разделах описываются различные свойства, которые можно использовать для управления созданным образом контейнера.

ContainerBaseImage

Свойство базового образа контейнера управляет изображением, используемым в качестве основы для образа. По умолчанию следующие значения выводятся на основе свойств проекта:

• Если проект является автономным, в качестве базового образа используется образ mcr.microsoft.com/dotnet/runtime-deps.
• Если проект является проектом ASP.NET Core, в качестве базового образа используется образ mcr.microsoft.com/dotnet/aspnet.
• В противном случае в качестве базового образа используется образ mcr.microsoft.com/dotnet/runtime.

Тег изображения определяется числовым компонентом выбранного TargetFramework. Например, проект, предназначенный для net6.0, приводит к 6.0 тегу выводимого базового образа, а проект net7.0-linux использует тег 7.0 и т. д.

Если вы задаете здесь значение, необходимо задать полное имя изображения, которое будет использоваться в качестве основы, включая любой тег, который вы предпочитаете:

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

С помощью пакета SDK для .NET версии 8.0.200 ContainerBaseImage улучшается для оптимизации размера и безопасности:

• Нацелив linux-musl-x64 или идентификаторы среды выполнения linux-musl-arm64, автоматически выбирает варианты образа alpine, чтобы обеспечить выполнение проекта:
  • Если проект использует PublishAot=true, nightly/runtime-depsjammy-chiseled-aot вариант базового образа для оптимального размера и безопасности.
  • Если проект использует InvariantGlobalization=false, -extra варианты используются для обеспечения локализации.

Дополнительные сведения о размерах и характеристиках изображений см. в отчете о размере образа контейнера .NET 8.0.

ContainerFamily

Начиная с .NET 8, вы можете использовать свойство ContainerFamily MSBuild для выбора другого семейства образов контейнеров, предоставляемых Корпорацией Майкрософт, в качестве базового образа для вашего приложения. При установке это значение добавляется к концу выбранного тега TFM, изменяя предоставленный тег. Например, чтобы использовать варианты Alpine Linux базовых образов .NET, можно задать для ContainerFamily значение alpine:

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

Предыдущая конфигурация проекта приводит к окончательному тегу 8.0-alpine для приложения .NET 8.NET.

Это поле является бесплатным и часто можно использовать для выбора различных дистрибутивов операционной системы, конфигураций пакетов по умолчанию или любых других изменений базового образа. Это поле игнорируется при установке ContainerBaseImage. Дополнительные сведения см. в образах контейнеров .NET.

ContainerRuntimeIdentifier(s)

Свойство ContainerRuntimeIdentifier указывает ОС и архитектуру контейнера, если ContainerBaseImage поддерживает несколько платформ. Например, образ mcr.microsoft.com/dotnet/runtime поддерживает linux-x64, linux-arm, linux-arm64и win10-x64. По умолчанию это значение имеет значение RuntimeIdentifier, используемое при публикации контейнера. Как правило, не нужно явно задавать это свойство; Вместо этого используйте параметр -r с командой dotnet publish. Если выбранное изображение не поддерживает указанный RuntimeIdentifier, ошибка указывает поддерживаемые идентификаторы.

Вы всегда можете задать для свойства ContainerBaseImage полное имя изображения, включая тег, чтобы избежать необходимости использовать это свойство вообще.

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

Чтобы указать несколько идентификаторов среды выполнения контейнера для образов с несколькими архитектурами, используйте разделенный точкой с запятой набор идентификаторов среды выполнения в свойстве ContainerRuntimeIdentifiers, аналогичный настройке нескольких TargetFrameworks:

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

Дополнительные сведения об идентификаторах среды выполнения, поддерживаемых .NET, см. в каталоге RID.

ContainerRegistry

Свойство реестра контейнеров управляет целевым реестром, куда будет отправлен только что созданный образ. По умолчанию она отправляется в локальную управляемую программу Docker, но можно также указать удаленный реестр. При использовании удаленного реестра, требующего проверки подлинности, вы проходите проверку подлинности с помощью известных механизмов docker login. Дополнительные сведения см. в разделе аутентификации в реестрах контейнеров дополнительные сведения. Для конкретного примера использования этого свойства рассмотрим следующий пример XML:

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

Это средство поддерживает публикацию в любом реестре, поддерживающем API HTTP-API Docker версии 2. Это включает следующие реестры явным образом (и, скорее всего, гораздо более неявно):

• реестра контейнеров Azure
• Реестра контейнеров Amazon Elastic
• реестра артефактов Google
• Docker Hub
• пакеты GitHub
• реестр контейнеров, размещенный в GitLab,
• Quay.io

Заметки о работе с этими реестрами см. в заметках, относящихся к реестру,.

ContainerRepository

Репозиторий контейнеров — это имя самого образа, например dotnet/runtime или my-app. По умолчанию используется AssemblyName проекта.

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

Имена изображений состоят из одного или нескольких сегментов с разделителями косой черты, каждый из которых может содержать только буквенно-цифровые символы нижнего регистра, точки, символы подчеркивания и дефисы, и должен начинаться с буквы или числа. Любые другие символы приводят к возникновению ошибки.

ContainerImageTag(s)

Свойство тега образа контейнера управляет тегами, созданными для образа. Чтобы указать один тег, используйте ContainerImageTag и для нескольких тегов ContainerImageTags.

Важный

При использовании ContainerImageTagsвы в конечном итоге будете использовать несколько изображений, по одному для уникального тега.

Теги часто используются для ссылки на разные версии приложения, но они также могут ссылаться на разные дистрибутивы операционной системы или даже разные конфигурации.

Начиная с .NET 8, если тег не указан по умолчанию, latest.

Чтобы переопределить значение по умолчанию, укажите одно из следующих значений:

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

Чтобы указать несколько тегов, используйте набор тегов с запятой в свойстве ContainerImageTags, аналогичный настройке нескольких TargetFrameworks:

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

Теги могут содержать только до 127 буквенно-цифровых символов, периодов, подчеркивания и дефисов. Они должны начинаться с буквенно-цифрового символа или подчеркивания. Любая другая форма приводит к возникновению ошибки.

Заметка

При использовании ContainerImageTags или любого свойства MSBuild, необходимого для настройки ; разделенных значений. Если вы вызываете dotnet publish из командной строки (как и в большинстве сред CI/CD), необходимо понять ограничения неспособности среды диамбигуировать разделители и кавычки, поэтому требуется надлежащее экранирование. Это отличается от PowerShell и Bash. Рассмотрим следующие команды dotnet publish в соответствующих средах:

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

В PowerShell необходимо экранировать как ;, так и " символы.

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

В Bash необходимо экранировать только " символ.

Это приводит к созданию двух образов: my-app:1.2.3-alpha2 и my-app:latest.

Кончик

Если у вас возникли проблемы со свойством ContainerImageTags, рассмотрите возможность определения области переменной среды ContainerImageTags.

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

ContainerLabel

Метка контейнера добавляет метку метаданных в контейнер. Метки часто используются для хранения метаданных версии и разработки для использования средствами проверки безопасности и другими средствами инфраструктуры. Можно указать любое количество меток контейнера.

Узел ContainerLabel имеет два атрибута:

• Include: ключ метки.
• Value: значение метки (это может быть пустым).

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

Список меток, созданных по умолчанию, см. в разделе метки контейнеров по умолчанию.

Настройка выполнения контейнера

Для управления выполнением контейнера можно использовать следующие свойства MSBuild.

ContainerWorkingDirectory

Узел рабочего каталога контейнера управляет рабочим каталогом контейнера, каталогом, который выполняется в ней, если не выполняется другая команда.

По умолчанию значение каталога /app используется в качестве рабочего каталога.

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

ContainerPort

Порт контейнера добавляет порты протокола управления передачей (TCP) или протокола пользовательской диаграммы данных (UDP) в список известных портов для контейнера. Это позволяет средам выполнения контейнеров, таким как Docker, автоматически сопоставлять эти порты с хост-компьютером. Это часто используется в качестве документации для контейнера, но также можно использовать для включения автоматического сопоставления портов.

Узел ContainerPort имеет два атрибута:

• Include: номер порта для предоставления.
• Type: по умолчанию tcpдопустимые значения — tcp или udp.

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

Начиная с .NET 8, ContainerPort выводится, если они не предоставляются явным образом на основе нескольких известных переменных среды ASP.NET:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

Если эти переменные среды присутствуют, их значения анализируются и преобразуются в сопоставления tcp-портов. Эти переменные среды считываются из базового образа, при наличии или из переменных среды, определенных в проекте, с помощью ContainerEnvironmentVariable элементов. Дополнительные сведения см. в разделе ContainerEnvironmentVariable.

ContainerEnvironmentVariable

Узел переменной среды контейнера позволяет добавлять переменные среды в контейнер. Переменные среды доступны приложению, работающему в контейнере немедленно, и часто используются для изменения поведения во время выполнения запущенного приложения.

Узел ContainerEnvironmentVariable имеет два атрибута:

• Include: имя переменной среды.
• Value: значение переменной среды.

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

Дополнительные сведения см. впеременных среды .NET .

Заметка

В настоящее время невозможно задать переменные среды из .NET CLI при публикации образа контейнера. Дополнительные сведения см. в разделе GitHub: сборки контейнеров пакета SDK для .NET.

Настройка команд контейнера

По умолчанию средства контейнера запускают приложение с помощью созданного двоичного файла AppHost для приложения (если приложение использует AppHost), или команду dotnet плюс библиотеку DLL приложения.

Однако вы можете управлять выполнением приложения с помощью некоторых сочетаний ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgsи ContainerAppCommandInstruction.

Эти разные точки конфигурации существуют, так как разные базовые образы используют различные сочетания ENTRYPOINT контейнера и COMMAND свойств, и вы хотите иметь возможность поддерживать все из них. Значения по умолчанию должны использоваться для большинства приложений, но если вы хотите настроить поведение запуска приложения, необходимо:

• Определите двоичный файл для запуска и задайте его как ContainerAppCommand
• Определите, какие аргументы необходимы для запуска приложения и задайте их как ContainerAppCommandArgs
• Определите, какие аргументы (если таковые есть) необязательные и могут быть переопределены пользователем и задать их как ContainerDefaultArgs
• Задайте для ContainerAppCommandInstruction значение DefaultArgs

Дополнительные сведения см. в следующих элементах конфигурации.

ContainerAppCommand

Элемент конфигурации команды приложения — это логическая точка входа приложения. Для большинства приложений это приложение AppHost, созданный исполняемый двоичный файл для вашего приложения. Если приложение не создает AppHost, эта команда обычно dotnet <your project dll>. Эти значения применяются после любого ENTRYPOINT в базовом контейнере или непосредственно, если ENTRYPOINT не определен.

Конфигурация ContainerAppCommand имеет одно свойство Include, представляющее команду, параметр или аргумент для использования в команде точки входа:

<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

Этот элемент конфигурации команды приложения args представляет все логически необходимые аргументы для приложения, которые должны применяться к ContainerAppCommand. По умолчанию для приложения не создается ни один из них. При наличии к контейнеру применяются args при выполнении.

Конфигурация ContainerAppCommandArgs имеет одно свойство Include, представляющее параметр или аргумент, применяемый к команде 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>

ContainerDefaultArgs

Этот элемент конфигурации args по умолчанию представляет любые переопределяемые пользователем аргументы для приложения. Это хороший способ предоставить значения по умолчанию, которые может потребоваться запустить приложение таким образом, чтобы упростить запуск, но по-прежнему легко настроить.

Конфигурация ContainerDefaultArgs имеет одно свойство Include, представляющее параметр или аргумент, применяемый к команде 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>

ContainerAppCommandInstruction

Конфигурация инструкций команды приложения помогает управлять способом ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgsи ContainerDefaultArgs объединяются для формирования окончательной команды, выполняемой в контейнере. Это зависит от того, присутствует ли ENTRYPOINT на базовом изображении. Это свойство принимает одно из трех значений: "DefaultArgs", "Entrypoint"или "None".

• Entrypoint:
  • В этом режиме точка входа определяется ContainerAppCommand, ContainerAppCommandArgsи ContainerDefaultArgs.
• None:
  • В этом режиме точка входа определяется ContainerEntrypoint, ContainerEntrypointArgsи ContainerDefaultArgs.
• DefaultArgs:
  • Это самый сложный режим, если ни один из элементов ContainerEntrypoint[Args] отсутствует, ContainerAppCommand[Args] и ContainerDefaultArgs используются для создания точки входа и команды. Точка входа базового образа для базовых образов с жесткой кодировкой для dotnet или /usr/bin/dotnet пропускается таким образом, чтобы вы имели полный контроль.
  • Если присутствуют оба ContainerEntrypoint и ContainerAppCommand, ContainerEntrypoint становится точкой входа, а ContainerAppCommand становится командой.

Заметка

Элементы конфигурации ContainerEntrypoint и ContainerEntrypointArgs устарели по сравнению с .NET 8.

Важный

Это для расширенных приложений, большинство пользователей не должны настраивать свою точку входа на эту степень. Дополнительные сведения и возможность предоставления вариантов использования для ваших сценариев см. в статье GitHub: контейнер пакета SDK для .NET создает обсуждения.

ContainerUser

Свойство конфигурации пользователя управляет пользователем по умолчанию, в котором выполняется контейнер. Это часто используется для запуска контейнера в качестве пользователя, не являющегося корневым, что рекомендуется для обеспечения безопасности. Существует несколько ограничений для этой конфигурации, которые следует учитывать:

• Он может принимать различные формы: имя пользователя, идентификаторы пользователей Linux, имя группы, идентификатор группы Linux, username:groupnameи другие варианты идентификаторов.
• На изображении нет проверки наличия указанного пользователя или группы.
• Изменение пользователя может изменить поведение приложения, особенно в отношении таких действий, как файловая система разрешения.

Значение по умолчанию этого поля зависит от проекта TFM и целевой операционной системы:

• Если вы используете .NET 8 или более поздней версии и используете образы среды выполнения Майкрософт, выполните следующие действия.
  • в Linux используется app без корневого пользователя (хотя он ссылается на его идентификатор пользователя)
  • В Windows используется ContainerUser без корневого пользователя
• В противном случае не используется ContainerUser по умолчанию

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

Кончик

Переменная среды APP_UID используется для задания сведений о пользователе в контейнере. Это значение может поступать из переменных среды, определенных в базовом образе (например, образы Microsoft .NET), или вы можете настроить его самостоятельно с помощью синтаксиса ContainerEnvironmentVariable.

Чтобы настроить приложение для запуска от имени корневого пользователя, задайте для свойства ContainerUser значение root. В файле проекта добавьте следующее:

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

Кроме того, можно задать это значение при вызове dotnet publish из командной строки:

dotnet publish -p ContainerUser=root

Метки контейнеров по умолчанию

Метки часто используются для предоставления согласованных метаданных на образах контейнеров. Этот пакет предоставляет некоторые метки по умолчанию для повышения удобства обслуживания созданных образов.

• org.opencontainers.image.created задан формат ISO 8601 текущего значения DateTime.UtcNow.

Дополнительные сведения см. в статье Реализация обычных меток на основе существующихинфраструктуры меток.

См. также

• Контейнеризация приложения .NET с помощью dotnet publish
• образы контейнеров .NET