Membuat kontainer aplikasi .NET dengan penerbitan dotnet

  • Artikel

Kontainer memiliki banyak fitur dan manfaat, seperti menjadi infrastruktur yang tidak dapat diubah, menyediakan arsitektur portabel, dan memungkinkan skalabilitas. Gambar dapat digunakan untuk membuat kontainer untuk lingkungan pengembangan lokal, cloud privat, atau cloud publik Anda. Dalam tutorial ini, Anda akan mempelajari cara membuat kontainer aplikasi .NET menggunakan perintah terbitkan dotnet.

Prasyarat

Instal prasyarat berikut:

Selain prasyarat ini, disarankan agar Anda terbiasa dengan Layanan Pekerja di .NET.

Membuat aplikasi .NET

Anda memerlukan aplikasi .NET untuk melakukan kontainerisasi, jadi mulailah dengan membuat aplikasi baru dari templat. Buka terminal Anda, buat folder kerja (direktori sampel) jika Anda belum melakukannya, dan ubah direktori sehingga Anda berada di dalamnya. Di folder kerja, jalankan perintah berikut untuk membuat proyek baru di subdirektori bernama Worker:

dotnet new worker -o Worker -n DotNet.ContainerImage

Pohon folder Anda terlihat seperti berikut ini:

📁 sample-directory
    └──📂 Worker
        ├──appsettings.Development.json
        ├──appsettings.json
        ├──DotNet.ContainerImage.csproj
        ├──Program.cs
        ├──Worker.cs
        └──📂 obj
            ├── DotNet.ContainerImage.csproj.nuget.dgspec.json
            ├── DotNet.ContainerImage.csproj.nuget.g.props
            ├── DotNet.ContainerImage.csproj.nuget.g.targets
            ├── project.assets.json
            └── project.nuget.cache

Perintah dotnet new membuat folder baru bernama Worker dan menghasilkan layanan pekerja yang, saat dijalankan, mencatat pesan setiap detik. Dari sesi terminal Anda, ubah direktori dan navigasikan ke folder Pekerja . dotnet run Gunakan perintah untuk memulai aplikasi.

dotnet run
Building...
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:00 -05:00
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: .\Worker
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:01 -05:00
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:02 -05:00
info: DotNet.ContainerImage.Worker[0]
      Worker running at: 10/18/2022 08:56:03 -05:00
info: Microsoft.Hosting.Lifetime[0]
      Application is shutting down...
Attempting to cancel the build...

Templat pekerja mengulang tanpa batas waktu. Gunakan perintah batalkan Ctrl+C untuk menghentikannya.

Tambahkan paket NuGet

Paket NuGet Microsoft.NET.Build.Containers saat ini diperlukan untuk menerbitkan proyek non-web sebagai kontainer. Untuk menambahkan Microsoft.NET.Build.Containers paket NuGet ke templat pekerja, jalankan perintah tambahkan paket dotnet berikut:

dotnet add package Microsoft.NET.Build.Containers

Tip

Jika Anda membangun aplikasi web dan menggunakan .NET SDK 7.0.300 atau yang lebih baru, maka paket tidak diperlukan—SDK berisi fungsionalitas yang sama di luar kotak.

Mengatur nama gambar kontainer

Ada berbagai opsi konfigurasi yang tersedia saat menerbitkan aplikasi sebagai kontainer.

Secara default, nama gambar kontainer adalah AssemblyName proyek. Jika nama tersebut tidak valid sebagai nama gambar kontainer, Anda dapat mengambil alihnya dengan menentukan seperti yang ContainerRepository ditunjukkan dalam file proyek berikut:

<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>

Untuk informasi selengkapnya, lihat ContainerRepository.

Secara default, nama gambar kontainer adalah AssemblyName proyek. Jika nama tersebut tidak valid sebagai nama gambar kontainer, Anda dapat mengambil alihnya dengan menentukan (ContainerImageName usang) atau yang disukai ContainerRepository seperti yang ditunjukkan dalam file proyek berikut:

<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>

Untuk informasi selengkapnya, lihat ContainerImageName.

Menerbitkan aplikasi .NET

Untuk menerbitkan aplikasi .NET sebagai kontainer, gunakan perintah terbitkan dotnet berikut:

dotnet publish --os linux --arch x64 /t:PublishContainer -c Release

Perintah .NET CLI sebelumnya menerbitkan aplikasi sebagai kontainer:

  • Menargetkan Linux sebagai OS (--os linux).
  • Menentukan arsitektur x64 (--arch x64).
  • Menggunakan konfigurasi rilis (-c Release).

Penting

Untuk membangun kontainer secara lokal, Anda harus menjalankan daemon Docker. Jika tidak berjalan saat Anda mencoba menerbitkan aplikasi sebagai kontainer, Anda akan mengalami kesalahan yang mirip dengan yang berikut ini:

..\build\Microsoft.NET.Build.Containers.targets(66,9): error MSB4018:
   The "CreateNewImage" task failed unexpectedly. [..\Worker\DotNet.ContainerImage.csproj]

Tip

Bergantung pada jenis aplikasi yang Anda kontainerisasi, sakelar baris perintah (opsi) mungkin bervariasi. Misalnya, /t:PublishContainer argumen hanya diperlukan untuk aplikasi .NET non-web, seperti console dan worker templat. Untuk templat web, ganti /t:PublishContainer argumen dengan -p:PublishProfile=DefaultContainer. Untuk informasi selengkapnya, lihat Build kontainer .NET SDK, masalah #141.

Perintah menghasilkan output yang mirip dengan contoh output:

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

Perintah ini mengkompilasi aplikasi pekerja Anda ke folder terbitkan dan mendorong kontainer ke registri docker lokal Anda.

Mengonfigurasi gambar kontainer

Anda dapat mengontrol banyak aspek kontainer yang dihasilkan melalui properti MSBuild. Secara umum, jika Anda dapat menggunakan perintah di Dockerfile untuk mengatur beberapa konfigurasi, Anda dapat melakukan hal yang sama melalui MSBuild.

Catatan

Satu-satunya pengecualian untuk ini adalah RUN perintah. Karena cara kontainer dibangun, kontainer tidak dapat ditimulasi. Jika Anda memerlukan fungsionalitas ini, Anda harus menggunakan Dockerfile untuk membangun gambar kontainer Anda.

ContainerArchiveOutputPath

Mulai dari .NET 8, Anda dapat membuat kontainer secara langsung sebagai arsip tar.gz . Fitur ini berguna jika alur kerja Anda tidak mudah dan mengharuskan Anda, misalnya, menjalankan alat pemindaian di atas gambar Anda sebelum mendorongnya. Setelah arsip dibuat, Anda dapat memindahkannya, memindainya, atau memuatnya ke toolchain Docker lokal.

Untuk menerbitkan ke arsip, tambahkan properti ke ContainerArchiveOutputPath perintah Anda dotnet publish , misalnya:

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

Anda dapat menentukan nama folder atau jalur dengan nama file tertentu. Jika Anda menentukan nama folder, nama file yang dihasilkan untuk file arsip gambar akan menjadi $(ContainerRepository).tar.gz. Arsip ini dapat berisi beberapa tag di dalamnya, hanya karena satu file dibuat untuk semua ContainerImageTags.

Konfigurasi penamaan gambar kontainer

Gambar kontainer mengikuti konvensi penamaan tertentu. Nama gambar terdiri dari beberapa bagian, registri, port opsional, repositori, dan tag dan keluarga opsional.

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

Misalnya, pertimbangkan nama gambar yang mcr.microsoft.com/dotnet/runtime:8.0-alpine sepenuhnya memenuhi syarat:

  • mcr.microsoft.com adalah registri (dan dalam hal ini mewakili registri kontainer Microsoft).
  • dotnet/runtime adalah repositori (tetapi beberapa mempertimbangkan ini user/repository).
  • 8.0-alpine adalah tag dan keluarga (keluarga adalah penentu opsional yang membantu memisahkan kemasan OS).

Beberapa properti yang dijelaskan di bagian berikut sesuai dengan mengelola bagian dari nama gambar yang dihasilkan. Pertimbangkan tabel berikut yang memetakan hubungan antara nama gambar dan properti build:

Bagian nama gambar Properti MSBuild Contoh nilai
REGISTRY[:PORT] ContainerRegistry mcr.microsoft.com:443
PORT ContainerPort :443
REPOSITORY ContainerRepository dotnet/runtime
TAG ContainerImageTag 8.0
FAMILY ContainerFamily -alpine
Bagian nama gambar Properti MSBuild Contoh nilai
REGISTRY[:PORT] ContainerRegistry mcr.microsoft.com:443
PORT ContainerPort :443
REPOSITORY ContainerImageName dotnet/runtime
TAG ContainerImageTag 8.0

Bagian berikut menjelaskan berbagai properti yang dapat digunakan untuk mengontrol gambar kontainer yang dihasilkan.

ContainerBaseImage

Properti gambar dasar kontainer mengontrol gambar yang digunakan sebagai dasar untuk gambar Anda. Secara default, nilai berikut disimpulkan berdasarkan properti proyek Anda:

  • Jika proyek Anda mandiri, mcr.microsoft.com/dotnet/runtime-deps gambar digunakan sebagai gambar dasar.
  • Jika proyek Anda adalah proyek ASP.NET Core, mcr.microsoft.com/dotnet/aspnet gambar digunakan sebagai gambar dasar.
  • mcr.microsoft.com/dotnet/runtime Jika tidak, gambar digunakan sebagai gambar dasar.

Tag gambar disimpulkan sebagai komponen numerik dari pilihan Anda TargetFramework. Misalnya, penargetan net6.0 proyek menghasilkan 6.0 tag gambar dasar yang net7.0-linux disimpulkan, dan proyek menggunakan 7.0 tag , dan sebagainya.

Jika Anda menetapkan nilai di sini, Anda harus mengatur nama gambar yang sepenuhnya memenuhi syarat untuk digunakan sebagai dasar, termasuk tag apa pun yang Anda sukai:

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

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

ContainerFamily

Dimulai dengan .NET 8, Anda dapat menggunakan ContainerFamily properti MSBuild untuk memilih keluarga gambar kontainer yang disediakan Microsoft yang berbeda sebagai gambar dasar untuk aplikasi Anda. Saat diatur, nilai ini ditambahkan ke akhir tag khusus TFM yang dipilih, mengubah tag yang disediakan. Misalnya, untuk menggunakan varian Alpine Linux dari gambar dasar .NET, Anda dapat mengatur ContainerFamily ke alpine:

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

Konfigurasi proyek sebelumnya menghasilkan tag 8.0-alpine akhir untuk aplikasi penargetan .NET 8.

Bidang ini berbentuk bebas, dan sering kali dapat digunakan untuk memilih distribusi sistem operasi yang berbeda, konfigurasi paket default, atau rasa perubahan lainnya pada gambar dasar. Bidang ini diabaikan ketika ContainerBaseImage diatur. Untuk informasi selengkapnya, lihat Gambar kontainer .NET.

ContainerRuntimeIdentifier

Properti pengidentifikasi runtime kontainer mengontrol sistem operasi dan arsitektur yang digunakan oleh kontainer Anda jika ContainerBaseImage Anda mendukung lebih dari satu platform. Misalnya, mcr.microsoft.com/dotnet/runtime gambar saat ini mendukung linux-x64, , linux-armlinux-arm64 dan win10-x64 gambar semua di belakang tag yang sama, sehingga alat membutuhkan cara untuk diberi tahu versi mana yang ingin Anda gunakan. Secara default, ini diatur ke nilai RuntimeIdentifier yang Anda pilih saat menerbitkan kontainer. Properti ini jarang perlu diatur secara eksplisit - sebagai gantinya -r gunakan opsi ke dotnet publish perintah . Jika gambar yang Anda pilih tidak mendukung RuntimeIdentifier yang Anda pilih, menghasilkan kesalahan yang menjelaskan RuntimeIdentifiers yang didukung gambar.

Anda selalu dapat mengatur ContainerBaseImage properti ke nama gambar yang sepenuhnya memenuhi syarat, termasuk tag, untuk menghindari perlunya menggunakan properti ini sama sekali.

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

Untuk informasi selengkapnya mengenai pengidentifikasi runtime yang didukung oleh .NET, lihat katalog RID.

ContainerRegistry

Properti registri kontainer mengontrol registri tujuan, tempat gambar yang baru dibuat akan didorong. Secara default didorong ke daemon Docker lokal, tetapi Anda juga dapat menentukan registri jarak jauh. Saat menggunakan registri jarak jauh yang memerlukan autentikasi, Anda mengautentikasi menggunakan mekanisme terkenal docker login . Untuk informasi selengkapnya, Lihat mengautentikasi ke registri kontainer untuk detail selengkapnya. Untuk contoh konkret penggunaan properti ini, pertimbangkan contoh XML berikut:

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

Alat ini mendukung penerbitan ke registri apa pun yang mendukung API HTTP Docker Registry V2. Ini termasuk registri berikut secara eksplisit (dan kemungkinan banyak lebih implisit):

Untuk catatan tentang bekerja dengan registri ini, lihat catatan khusus registri.

ContainerRepository

Repositori kontainer adalah nama gambar itu sendiri, misalnya, dotnet/runtime atau my-app. Secara default, AssemblyName proyek digunakan.

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

ContainerImageName

Nama gambar kontainer mengontrol nama gambar itu sendiri, misalnya, dotnet/runtime atau my-app. Secara default, AssemblyName proyek digunakan.

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

Catatan

Dimulai dengan .NET 8, ContainerImageName tidak digunakan lagi demi ContainerRepository.

Nama gambar terdiri dari satu atau beberapa segmen yang dibatasi garis miring, yang masing-masing hanya dapat berisi karakter alfanumerik huruf kecil, titik, garis bawah, dan tanda hubung, dan harus dimulai dengan huruf atau angka. Karakter lain mengakibatkan kesalahan dilemparkan.

ContainerImageTag(s)

Properti tag gambar kontainer mengontrol tag yang dihasilkan untuk gambar. Untuk menentukan penggunaan ContainerImageTag tag tunggal dan untuk beberapa tag, gunakan ContainerImageTags.

Penting

Saat Anda menggunakan ContainerImageTags, Anda akan berakhir dengan beberapa gambar, satu per tag unik.

Tag sering digunakan untuk merujuk ke versi aplikasi yang berbeda, tetapi mereka juga dapat merujuk ke distribusi sistem operasi yang berbeda, atau bahkan konfigurasi yang berbeda.

Dimulai dengan .NET 8, ketika tag tidak disediakan, defaultnya adalah latest.

Secara default, Version proyek digunakan sebagai nilai tag.

Untuk mengambil alih default, tentukan salah satu hal berikut ini:

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

Untuk menentukan beberapa tag, gunakan kumpulan tag yang dibatasi titik koma di ContainerImageTags properti , mirip dengan pengaturan beberapa TargetFrameworks:

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

Tag hanya dapat berisi hingga 127 karakter alfanumerik, titik, garis bawah, dan tanda hubung. Mereka harus dimulai dengan karakter alfanumerik atau garis bawah. Formulir lain menghasilkan kesalahan yang dilemparkan.

Catatan

Saat menggunakan ContainerImageTags, tag dibatasi oleh ; karakter. Jika Anda memanggil dotnet publish dari baris perintah (seperti halnya dengan sebagian besar lingkungan CI/CD), Anda harus membungkus nilai dalam bungkus "tunggal ' dan dalam dengan tanda kutip ganda , misalnya (='"tag-1;tag-2"'). Pertimbangkan perintah berikut dotnet publish :

dotnet publish -p ContainerImageTags='"1.2.3-alpha2;latest"'

Ini menghasilkan dua gambar yang dihasilkan: my-app:1.2.3-alpha2 dan my-app:latest.

Tip

Jika Anda mengalami masalah dengan ContainerImageTags properti , pertimbangkan untuk mencakup variabel ContainerImageTags lingkungan sebagai gantinya:

ContainerImageTags='1.2.3;latest' dotnet publish

ContainerLabel

Label kontainer menambahkan label metadata ke kontainer. Label tidak berdampak pada kontainer pada waktu proses, tetapi sering digunakan untuk menyimpan metadata versi dan penulisan untuk digunakan oleh pemindai keamanan dan alat infrastruktur lainnya. Anda dapat menentukan sejumlah label kontainer.

Simpul ContainerLabel memiliki dua atribut:

  • Include: Kunci label.
  • Value: Nilai label (ini mungkin kosong).
<ItemGroup>
    <ContainerLabel Include="org.contoso.businessunit" Value="contoso-university" />
</ItemGroup>

Untuk daftar label yang dibuat secara default, lihat label kontainer default.

Mengonfigurasi eksekusi kontainer

Untuk mengontrol eksekusi kontainer, Anda dapat menggunakan properti MSBuild berikut.

ContainerWorkingDirectory

Simpul direktori kerja kontainer mengontrol direktori kerja kontainer, direktori yang perintah dijalankan jika tidak perintah lain dijalankan.

Secara default, /app nilai direktori digunakan sebagai direktori kerja.

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

ContainerPort

Port kontainer menambahkan port TCP atau UDP ke daftar port yang diketahui untuk kontainer. Ini memungkinkan runtime kontainer seperti Docker untuk memetakan port ini ke komputer host secara otomatis. Ini sering digunakan sebagai dokumentasi untuk kontainer, tetapi juga dapat digunakan untuk mengaktifkan pemetaan port otomatis.

Simpul ContainerPort memiliki dua atribut:

  • Include: Nomor port yang akan diekspos.
  • Type: Default ke tcp, nilai yang valid adalah tcp atau udp.
<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

Dimulai dengan .NET 8, ContainerPort disimpulkan ketika tidak secara eksplisit disediakan berdasarkan beberapa variabel lingkungan ASP.NET terkenal:

  • ASPNETCORE_URLS
  • ASPNETCORE_HTTP_PORTS
  • ASPNETCORE_HTTPS_PORTS

Jika variabel lingkungan ini ada, nilainya diurai dan dikonversi ke pemetaan port TCP. Variabel lingkungan ini dibaca dari gambar dasar Anda, jika ada, atau dari variabel lingkungan yang ditentukan dalam proyek Anda melalui ContainerEnvironmentVariable item. Untuk informasi selengkapnya, lihat ContainerEnvironmentVariable.

ContainerEnvironmentVariable

Simpul variabel lingkungan kontainer memungkinkan Anda menambahkan variabel lingkungan ke kontainer. Variabel lingkungan dapat diakses oleh aplikasi yang berjalan di kontainer segera, dan sering digunakan untuk mengubah perilaku run-time aplikasi yang sedang berjalan.

Simpul ContainerEnvironmentVariable memiliki dua atribut:

  • Include: Nama variabel lingkungan.
  • Value: Nilai variabel lingkungan.
<ItemGroup>
  <ContainerEnvironmentVariable Include="LOGGER_VERBOSITY" Value="Trace" />
</ItemGroup>

Untuk informasi selengkapnya, lihat variabel lingkungan .NET.

Mengonfigurasi perintah kontainer

Secara default, alat kontainer meluncurkan aplikasi Anda menggunakan biner AppHost yang dihasilkan untuk aplikasi Anda (jika aplikasi Anda menggunakan AppHost), atau dotnet perintah ditambah DLL aplikasi Anda.

Namun, Anda dapat mengontrol bagaimana aplikasi Anda dijalankan dengan menggunakan beberapa kombinasi ContainerAppCommand, , ContainerAppCommandArgsContainerDefaultArgs, dan ContainerAppCommandInstruction.

Titik konfigurasi yang berbeda ini ada karena gambar dasar yang berbeda menggunakan kombinasi kontainer ENTRYPOINT dan COMMAND properti yang berbeda, dan Anda ingin dapat mendukung semuanya. Default harus dapat digunakan untuk sebagian besar aplikasi, tetapi jika Anda ingin menyesuaikan perilaku peluncuran aplikasi, Anda harus:

  • Identifikasi biner untuk dijalankan dan atur sebagai ContainerAppCommand
  • Identifikasi argumen mana yang diperlukan agar aplikasi Anda berjalan dan atur sebagai ContainerAppCommandArgs
  • Mengidentifikasi argumen mana (jika ada) bersifat opsional dan dapat ditimpa oleh pengguna dan mengaturnya sebagai ContainerDefaultArgs
  • Atur ContainerAppCommandInstruction ke DefaultArgs

Untuk informasi selengkapnya, lihat item konfigurasi berikut.

ContainerAppCommand

Item konfigurasi perintah aplikasi adalah titik masuk logis aplikasi Anda. Untuk sebagian besar aplikasi, ini adalah AppHost, biner yang dapat dieksekusi yang dihasilkan untuk aplikasi Anda. Jika aplikasi Anda tidak menghasilkan AppHost, maka perintah ini biasanya akan menjadi dotnet <your project dll>. Nilai-nilai ini diterapkan setelah apa pun ENTRYPOINT di kontainer dasar Anda, atau secara langsung jika tidak ENTRYPOINT ditentukan.

Konfigurasi ContainerAppCommand memiliki satu Include properti, yang mewakili perintah, opsi, atau argumen untuk digunakan dalam perintah entrypoint:

<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

Item konfigurasi args perintah aplikasi ini mewakili argumen yang diperlukan secara logis untuk aplikasi Anda yang harus diterapkan ke ContainerAppCommand. Secara default, tidak ada yang dihasilkan untuk aplikasi. Saat ada, arg diterapkan ke kontainer Anda saat dijalankan.

Konfigurasi ContainerAppCommandArgs memiliki satu Include properti, yang mewakili opsi atau argumen untuk diterapkan ke ContainerAppCommand perintah .

<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

Item konfigurasi args default ini mewakili argumen yang dapat diganti pengguna untuk aplikasi Anda. Ini adalah cara yang baik untuk menyediakan default yang mungkin perlu dijalankan aplikasi Anda dengan cara yang memudahkan untuk memulai, namun masih mudah disesuaikan.

Konfigurasi ContainerDefaultArgs memiliki satu Include properti, yang mewakili opsi atau argumen untuk diterapkan ke ContainerAppCommand perintah .

<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

Konfigurasi instruksi perintah aplikasi membantu mengontrol cara ContainerEntrypoint, , ContainerEntrypointArgs, ContainerAppCommandContainerAppCommandArgs, dan ContainerDefaultArgs digabungkan untuk membentuk perintah akhir yang dijalankan dalam kontainer. Ini sangat tergantung pada apakah ada ENTRYPOINT dalam gambar dasar. Properti ini mengambil salah satu dari tiga nilai: "DefaultArgs", , "Entrypoint"atau "None".

  • Entrypoint:
    • Dalam mode ini, titik masuk didefinisikan oleh ContainerAppCommand, ContainerAppCommandArgs, dan ContainerDefaultArgs.
  • None:
    • Dalam mode ini, titik masuk didefinisikan oleh ContainerEntrypoint, ContainerEntrypointArgs, dan ContainerDefaultArgs.
  • DefaultArgs:
    • Ini adalah mode paling kompleks—jika tidak ada ContainerEntrypoint[Args] item yang ada, ContainerAppCommand[Args] dan ContainerDefaultArgs digunakan untuk membuat titik masuk dan perintah. Titik masuk gambar dasar untuk gambar dasar yang memilikinya dikodekan dotnet secara permanen atau /usr/bin/dotnet dilewati sehingga Anda memiliki kontrol penuh.
    • Jika keduanya ContainerEntrypoint dan ContainerAppCommand hadir, maka ContainerEntrypoint menjadi titik masuk, dan ContainerAppCommand menjadi perintah.

Catatan

Item ContainerEntrypoint konfigurasi dan ContainerEntrypointArgs tidak digunakan lagi pada .NET 8.

Penting

Ini untuk aplikasi pengguna tingkat lanjut-sebagian besar tidak perlu menyesuaikan titik masuk mereka ke derajat ini. Untuk informasi selengkapnya dan jika Anda ingin memberikan kasus penggunaan untuk skenario Anda, lihat Diskusi build kontainer GitHub: .NET SDK.

ContainerUser

Properti konfigurasi pengguna mengontrol pengguna default tempat kontainer berjalan. Ini sering digunakan untuk menjalankan kontainer sebagai pengguna nonroot, yang merupakan praktik terbaik untuk keamanan. Ada beberapa batasan untuk mengetahui konfigurasi ini:

  • Ini dapat mengambil berbagai bentuk—nama pengguna, id pengguna linux, nama grup, id grup linux, username:groupname, dan varian ID lainnya.
  • Tidak ada verifikasi bahwa pengguna atau grup yang ditentukan ada pada gambar.
  • Mengubah pengguna dapat mengubah perilaku aplikasi, terutama sehubungan dengan hal-hal seperti izin Sistem File.

Nilai default bidang ini bervariasi menurut TFM proyek dan sistem operasi target:

  • Jika Anda menargetkan .NET 8 atau yang lebih tinggi dan menggunakan gambar runtime Microsoft, maka:
    • di Linux, pengguna app tanpa akar digunakan (meskipun dirujuk oleh ID penggunanya)
    • pada Windows, pengguna ContainerUser tanpa akar digunakan
  • Jika tidak, tidak ada default ContainerUser yang digunakan
<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

Tip

Variabel APP_UID lingkungan digunakan untuk mengatur informasi pengguna dalam kontainer Anda. Nilai ini dapat berasal dari variabel lingkungan yang ditentukan dalam gambar dasar Anda (seperti yang dilakukan gambar Microsoft .NET), atau Anda dapat mengaturnya sendiri melalui ContainerEnvironmentVariable sintaks.

Namun, Anda dapat mengontrol bagaimana aplikasi Anda dijalankan dengan menggunakan ContainerEntrypoint dan ContainerEntrypointArgs.

ContainerEntrypoint

Titik entri kontainer dapat digunakan untuk menyesuaikan ENTRYPOINT kontainer, yang merupakan executable yang dipanggil saat kontainer dimulai. Secara default, untuk build yang membuat host aplikasi, build ditetapkan sebagai ContainerEntrypoint. Untuk build yang tidak membuat executable, dotnet path/to/app.dll digunakan sebagai ContainerEntrypoint.

Simpul ContainerEntrypoint memiliki atribut tunggal:

  • Include: Perintah, opsi, atau argumen untuk digunakan dalam ContainerEntrypoint perintah.

Misalnya, pertimbangkan contoh grup item proyek .NET berikut:

<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

Simpul args titik entri kontainer mengontrol argumen default yang disediakan untuk ContainerEntrypoint. Ini harus digunakan ketika ContainerEntrypoint adalah program yang mungkin ingin digunakan pengguna sendiri. Secara default, tidak ada ContainerEntrypointArgs yang dibuat atas nama Anda.

Simpul ContainerEntrypointArg memiliki atribut tunggal:

  • Include: Opsi atau argumen untuk diterapkan ke ContainerEntrypoint perintah .

Pertimbangkan contoh grup item proyek .NET berikut:

<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>

Label kontainer default

Label sering digunakan untuk menyediakan metadata yang konsisten pada gambar kontainer. Paket ini menyediakan beberapa label default untuk mendorong pemeliharaan gambar yang dihasilkan dengan lebih baik.

  • org.opencontainers.image.created diatur ke format ISO 8601 dari UTC DateTimesaat ini.

Untuk informasi selengkapnya, lihat Menerapkan label konvensional di atas infrastruktur label yang ada.

Membersihkan sumber daya

Dalam artikel ini, Anda menerbitkan pekerja .NET sebagai gambar kontainer. Jika mau, hapus sumber daya ini. docker images Gunakan perintah untuk melihat daftar gambar yang diinstal.

docker images

Pertimbangkan contoh output berikut:

REPOSITORY            TAG       IMAGE ID       CREATED          SIZE
dotnet-worker-image   1.0.0     25aeb97a2e21   12 seconds ago   191MB

Tip

File gambar bisa besar. Biasanya, Anda akan menghapus kontainer sementara yang Anda buat saat menguji dan mengembangkan aplikasi Anda. Anda biasanya menyimpan gambar dasar dengan runtime yang diinstal jika Anda berencana membangun gambar lain berdasarkan runtime tersebut.

Untuk menghapus gambar, salin ID gambar dan jalankan docker image rm perintah :

docker image rm 25aeb97a2e21

Langkah berikutnya