dotnet publish を使用して .NET アプリをコンテナー化する

• .NET 8+ SDK
  .NET がインストールされている場合は、dotnet --info コマンドを使用して、使用している SDK を特定します。
• Docker Community Edition

• .NET 7+ SDK
  .NET がインストールされている場合は、dotnet --info コマンドを使用して、使用している SDK を特定します。
• Docker Community Edition

NuGet パッケージを追加する

現在、Web 以外のプロジェクトをコンテナーとして発行するには Microsoft.NET.Build.Containers NuGet パッケージが必要です。 Microsoft.NET.Build.Containers NuGet パッケージをワーカー テンプレートに追加するには、次の dotnet add package コマンドを実行します。

dotnet add package Microsoft.NET.Build.Containers

既定で、コンテナー イメージ名はプロジェクトの AssemblyName になります。 その名前がコンテナー イメージ名として無効な場合は、次のプロジェクト ファイルに示すように ContainerRepository を指定してオーバーライドできます。

<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UserSecretsId>dotnet-DotNet.ContainerImage-2e40c179-a00b-4cc9-9785-54266210b7eb</UserSecretsId>
    <ContainerRepository>dotnet-worker-image</ContainerRepository>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </ItemGroup>
</Project>

詳細については、「ContainerRepository」を参照してください。

既定で、コンテナー イメージ名はプロジェクトの AssemblyName になります。 その名前がコンテナー イメージ名として無効な場合は、次のプロジェクト ファイルに示すように、(ContainerImageName 古い) または優先する ContainerRepository を指定してオーバーライドできます。

<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UserSecretsId>dotnet-DotNet.ContainerImage-2e40c179-a00b-4cc9-9785-54266210b7eb</UserSecretsId>
    <ContainerImageName>dotnet-worker-image</ContainerImageName>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="7.0.1" />
    <PackageReference Include="Microsoft.NET.Build.Containers" Version="7.0.401" />
  </ItemGroup>
</Project>

詳細については、「ContainerImageName」を参照してください。

Determining projects to restore...
  All projects are up-to-date for restore.
  DotNet.ContainerImage -> .\Worker\bin\Release\net8.0\linux-x64\DotNet.ContainerImage.dll
  DotNet.ContainerImage -> .\Worker\bin\Release\net8.0\linux-x64\publish\
  Building image 'dotnet-worker-image' with tags latest on top of base image mcr.microsoft.com/dotnet/aspnet:8.0
  Pushed container 'dotnet-worker-image:latest' to Docker daemon

Determining projects to restore...
  All projects are up-to-date for restore.
  DotNet.ContainerImage -> .\Worker\bin\Release\net7.0\linux-x64\DotNet.ContainerImage.dll
  DotNet.ContainerImage -> .\Worker\bin\Release\net7.0\linux-x64\publish\
  Building image 'dotnet-worker-image' with tags 1.0.0 on top of base image mcr.microsoft.com/dotnet/aspnet:7.0
  Pushed container 'dotnet-worker-image:1.0.0' to Docker daemon

ContainerArchiveOutputPath

.NET 8 以降では、tar.gz アーカイブとしてコンテナーを直接作成できます。 この機能は、たとえば画像をプッシュする前にスキャン ツールを実行する必要がある場合などワークフローが複雑な場合に便利です。 アーカイブが作成されたら、アーカイブの移動、スキャン、またはローカル Docker ツールチェーンへの読み込みを行うことができます。

アーカイブに発行するには、次に例を示す ContainerArchiveOutputPath プロパティを dotnet publish コマンドに追加します。

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

フォルダー名または特定のファイル名を持つパスを指定できます。 フォルダー名を指定すると、イメージ アーカイブ ファイルに対して生成されるファイル名は $(ContainerRepository).tar.gz のようになります。 これらのアーカイブには、すべての ContainerImageTags に対して 1 つのファイルが作成される場合にのみ、それらの中に複数のタグを含めることができます。

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

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

ContainerFamily

.NET 8 以降では、ContainerFamily MSBuild プロパティを使用して、アプリの基本イメージとして、Microsoft が提供する別のコンテナー イメージ ファミリを選択できます。 この値を設定すると、選択した TFM 固有のタグの末尾にこの値が追加され、指定されたタグが変更されます。 たとえば、.NET 基本イメージの Alpine Linux バリアントを使用するには、ContainerFamily を alpine に設定できます:

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

上記のプロジェクト構成では、.NET 8 ターゲット アプリの 8.0-alpine の最終的なタグが生成されます。

このフィールドは自由形式であり、多くの場合、さまざまなオペレーティング システムのディストリビューション、既定のパッケージ構成、または基本イメージに対するその他の変更のフレーバーを選択するために使用できます。 このフィールドは、ContainerBaseImage が設定されている場合は無視されます。 詳しくは、「.NET コンテナー イメージ」を参照してください。

ContainerRepository

コンテナー リポジトリは、イメージ自体の名前です、(例: dotnet/runtime または my-app)。 既定で、プロジェクトの AssemblyName が使用されます。

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

ContainerImageName

コンテナー イメージ名は、イメージ自体の名前を制御します (例: dotnet/runtime または my-app)。 既定で、プロジェクトの AssemblyName が使用されます。

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

.NET 8 以降では、タグが指定されていない場合、既定値は latest です。

既定で、プロジェクトの Version がタグ値として使用されます。

.NET 8 以降では、いくつかの良く知られている ASP.NET 環境変数に基づいて明示的に指定されていない場合、ContainerPort が推論されます:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

これらの環境変数が存在する場合、それらの値は解析され、TCP ポート マッピングに変換されます。 これらの環境変数は、基本イメージ (存在する場合) から、または ContainerEnvironmentVariable 項目を介してプロジェクトで定義されている環境変数から読み取られます。 詳細については、「ContainerEnvironmentVariable」を参照してください。

ただし、ContainerAppCommand、ContainerAppCommandArgs、ContainerDefaultArgs、ContainerAppCommandInstructionの組み合わせを使用して、アプリの実行方法を制御できます。

これらの異なる構成ポイントは、異なる基本イメージがコンテナー ENTRYPOINT と COMMAND プロパティの異なる組み合わせを使用し、それらすべてをサポートできるようにするために存在します。 既定値はほとんどのアプリで使用できる必要がありますが、アプリの起動動作をカスタマイズする場合は、次の操作を行う必要があります:

• 実行するバイナリを識別し、ContainerAppCommand として設定する
• アプリケーションを実行するために必要な引数を特定し、ContainerAppCommandArgs として設定する
• 省略可能な引数 (存在する場合) を特定し、ユーザーによってオーバーライドし、ContainerDefaultArgs として設定できます
• ContainerAppCommandInstruction を DefaultArgsに設定する

詳細については、次の構成項目を参照してください。

ContainerAppCommand

アプリ コマンド構成項目は、アプリの論理エントリ ポイントです。 ほとんどのアプリでは、これはアプリ用に生成された実行可能バイナリである AppHost です。 アプリで AppHost が生成されない場合、このコマンドは通常は dotnet <your project dll> です。 これらの値は、基本コンテナー内の任意の ENTRYPOINT の後、または ENTRYPOINT が定義されていない場合は直接適用されます。

ContainerAppCommand 構成には、entrypoint コマンドで使用するコマンド、オプション、または引数を表す 1 つの 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

このアプリ コマンド引数構成項目は、ContainerAppCommand に適用する必要があるアプリの論理的に必要な員数を表します。 既定では、アプリには何も生成されません。 存在する場合、引数は実行時にコンテナーに適用されます。

ContainerAppCommandArgs 構成には、ContainerAppCommand コマンドに適用するオプションまたは引数を表す 1 つの Include プロパティがあります。

<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

この既定の引数構成項目は、アプリのユーザーがオーバーライドできる引数を表します。 アプリが簡単に開始でき、しかし簡単にカスタマイズできるようアプリを実行するための既定値を指定するための良い方法です。

ContainerDefaultArgs 構成には、ContainerAppCommand コマンドに適用するオプションまたは引数を表す 1 つの Include プロパティがあります。

<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 によって大きく異なります。 このプロパティは、次の 3 つの値のいずれかを受け取ります: "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 がコマンドになります。

ContainerUser

user configuration プロパティは、コンテナーが実行される既定のユーザーを制御します。 これは、セキュリティのベスト プラクティスである非ルート ユーザーとしてコンテナーを実行するためによく使用されます。 この構成には注意する必要がある制約がいくつかあります:

• ユーザー名、Linux ユーザー ID、グループ名、Linux グループ ID、username:groupname、その他の ID バリアントなど、さまざまな形式を取りえます。
• 指定されたユーザーまたはグループがイメージに存在するという検証はありません。
• ユーザーを変更すると、特にファイル システム のアクセス許可などに関して、アプリの動作を変更できます。

このフィールドの既定値は、プロジェクト TFM とターゲット オペレーティング システムによって異なります:

• .NET 8 以降を対象とし、Microsoft ランタイム イメージを使用している場合は、次のようにします:
  • Linux では、ルートレス ユーザー app が使用されます (ただし、そのユーザー ID によって参照されます)
  • Windows では、ルートレス ユーザー ContainerUser が使用されます
• それ以外の場合、既定値 ContainerUser は使用されません

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

ただし、ContainerEntrypoint と ContainerEntrypointArgs を使用して、アプリの実行方法を制御できます。

ContainerEntrypoint

コンテナー エントリ ポイントを使用して、コンテナーの ENTRYPOINT をカスタマイズできます。これは、コンテナーの起動時に呼び出される実行可能ファイルです。 既定では、アプリ ホストを作成するビルドの場合、それが ContainerEntrypoint として設定されます。 実行可能ファイルを作成しないビルドの場合、dotnet path/to/app.dll は ContainerEntrypoint として使用されます。

ContainerEntrypoint ノードには 1 つの属性があります。

• Include: ContainerEntrypoint コマンドで使用するコマンド、オプション、または引数。

たとえば、次のサンプル .NET プロジェクト項目グループを考えます。

<ItemGroup Label="Entrypoint Assignment">
  <!-- This is how you would start the dotnet ef tool in your container -->
  <ContainerEntrypoint Include="dotnet" />
  <ContainerEntrypoint Include="ef" />

  <!-- This shorthand syntax means the same thing.
       Note the semicolon separating the tokens. -->
  <ContainerEntrypoint Include="dotnet;ef" />
</ItemGroup>

ContainerEntrypointArgs

コンテナー エントリ ポイント args ノードは、ContainerEntrypoint に提供される既知の引数を制御します。 これは、ContainerEntrypoint がユーザーがそのままで使用したいと考える可能性があるプログラムである場合に使用する必要があります。 既定で、ContainerEntrypointArgs は自動的に作成されません。

ContainerEntrypointArg ノードには 1 つの属性があります。

• Include: ContainerEntrypoint コマンドに適用するオプションまたは引数。

次の .NET プロジェクト項目グループの例を考えます。

<ItemGroup>
  <!-- Assuming the ContainerEntrypoint defined above,
       this would be the way to update the database by
       default, but let the user run a different EF command. -->
  <ContainerEntrypointArgs Include="database" />
  <ContainerEntrypointArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerEntrypointArgs Include="database;update" />
</ItemGroup>