Membuat alat .NET khusus RID, mandiri, dan AOT

Artikel ini berlaku untuk: ✔️ .NET SDK 10 dan versi yang lebih baru

Kemasi alat .NET untuk platform dan arsitektur tertentu sehingga Anda dapat mendistribusikan aplikasi asli, cepat, dan yang telah dioptimalkan. Kemampuan ini memudahkan untuk mendistribusikan aplikasi yang dioptimalkan untuk alat baris perintah seperti server MCP atau utilitas khusus platform lainnya.

Gambaran Umum

Dimulai dengan .NET SDK 10, Anda dapat membuat alat .NET yang menargetkan lingkungan sistem operasi tertentu (diwakili oleh Pengidentifikasi Runtime (RID)). Alat-alat ini dapat berupa:

Khusus RID: Dikompilasi untuk sistem operasi dan arsitektur tertentu.
Mandiri: Sertakan runtime .NET dan tidak memerlukan penginstalan .NET terpisah.
AOT Asli: Gunakan kompilasi Ahead-of-Time untuk startup yang lebih cepat dan jejak memori yang lebih kecil.

Pengguna tidak melihat perbedaan saat menginstal alat. .NET CLI secara otomatis memilih dan menginstal paket terbaik untuk platform mereka.

Memilih untuk berpartisipasi dalam kemasan khusus RID

Untuk membuat alat khusus RID, konfigurasikan proyek Anda dengan salah satu properti MSBuild berikut:

Properti RuntimeIdentifiers

Gunakan RuntimeIdentifiers untuk menentukan platform yang didukung alat Anda:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>mytool</ToolCommandName>
    <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>
  </PropertyGroup>
</Project>

Properti ToolPackageRuntimeIdentifiers

Atau, gunakan ToolPackageRuntimeIdentifiers untuk konfigurasi RID khusus alat:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <PublishAot>true</PublishAot>
    <ToolCommandName>mytool</ToolCommandName>
    <ToolPackageRuntimeIdentifiers>win-x64;linux-x64;osx-arm64</ToolPackageRuntimeIdentifiers>
  </PropertyGroup>
</Project>

Gunakan daftar nilai RID yang dibatasi titik koma. Untuk daftar Pengidentifikasi Runtime, lihat katalog RID.

Menyediakan versi yang bergantung pada kerangka kerja

Saat Anda memilih untuk menggunakan pengemasan alat khusus RID, .NET SDK membuat paket mandiri untuk setiap RID yang ditentukan. Namun, Anda kehilangan kemasan yang bergantung pada kerangka kerja default yang berfungsi pada platform apa pun dengan runtime .NET terpasang.

Untuk menyediakan versi yang bergantung pada kerangka kerja bersama paket khusus RID, tambahkan any ke daftar Anda ToolPackageRuntimeIdentifiers :

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <ToolPackageRuntimeIdentifiers>win-x64;osx-arm64;linux-x64;any</ToolPackageRuntimeIdentifiers>
</PropertyGroup>

Konfigurasi ini membuat lima paket:

Satu paket pointer tingkat atas yang mencantumkan semua sub-paket yang tersedia.
Tiga paket khusus RID (win-x64, osx-arm64, linux-x64) yang terintegrasi dan dipadatkan.
Satu paket RID-agnostic (any) yang bergantung pada kerangka kerja dan mengharuskan runtime .NET diinstal.

Saat pengguna menginstal alat Anda:

Pada sistem win-x64, osx-arm64, atau linux-x64, paket yang mandiri dan telah dipangkas diunduh dan dijalankan.
Pada sistem operasi atau arsitektur lainnya, paket yang bergantung pada kerangka kerja any digunakan.

Pendekatan ini menyediakan biner mandiri yang dioptimalkan untuk platform umum sambil mempertahankan kompatibilitas dengan platform yang kurang umum melalui fallback yang bergantung pada kerangka kerja.

Kapan menggunakan `RuntimeIdentifiers` vs `ToolPackageRuntimeIdentifiers`

Kedua RuntimeIdentifiers dan ToolPackageRuntimeIdentifiers memasukkan alat Anda ke dalam kemasan khusus RID, tetapi memenuhi tujuan yang sedikit berbeda.

Gunakan RuntimeIdentifiers saat:

Anda ingin proyek membangun dan menerbitkan aplikasi khusus RID secara umum (bukan hanya sebagai alat).
Anda terutama menargetkan CoreCLR (non-AOT) atau Anda menginginkan perilaku SDK standar di mana satu dotnet pack menghasilkan beberapa paket khusus RID.
Anda dapat melakukan kondisionalisasi PublishAot untuk subset RID, tetapi Anda masih menginginkan paket berbasis CoreCLR untuk setiap RID di RuntimeIdentifiers.

Gunakan ToolPackageRuntimeIdentifiers saat:

Anda ingin menentukan perilaku khusus RID hanya untuk kemasan alat, tanpa mengubah bagaimana proyek dibangun untuk skenario penyebaran lainnya.
Anda menggunakan Native AOT dan berencana untuk membangun biner AOT secara manual untuk setiap RID dengan dotnet pack -r <RID>.
Anda menginginkan model hibrid di mana beberapa RID mendapatkan Native AOT dan yang lain kembali ke implementasi portabel CoreCLR.

Notes:

Paket pointer tingkat atas menentukan paket khusus RID yang tersedia. Jika Anda menentukan ToolPackageRuntimeIdentifiers, ini menetapkan RID untuk alat; jika tidak, RuntimeIdentifiers digunakan.
ToolPackageRuntimeIdentifiers harus sama dengan atau subset RID di RuntimeIdentifiers
Ketika PublishAot=true, paket khusus RID dihasilkan hanya ketika Anda mengemas untuk RID tertentu (misalnya, dotnet pack -r linux-x64).
Build AOT asli (PublishAot=true) hanya didukung saat OS build dan OS target cocok.

Mengemas alat Anda

Proses pengemasan berbeda tergantung pada apakah Anda menggunakan kompilasi AOT. Untuk membangun paket NuGet, atau file .nupkg dari proyek, jalankan perintah paket dotnet .

Alat khusus RID dan mandiri

Jalankan dotnet pack sekali:

dotnet pack

Perintah ini membuat beberapa paket NuGet:

Satu paket untuk setiap RID: <packageName>.<RID>.<packageVersion>.nupkg
- Contoh: mytool.win-x64.1.0.0.nupkg
- Contoh: mytool.linux-x64.1.0.0.nupkg
- Contoh: mytool.osx-arm64.1.0.0.nupkg
Paket pointer yang tidak bergantung pada RID: <packageName>.<packageVersion>.nupkg
- Contoh: mytool.1.0.0.nupkg

Alat AOT

Untuk alat dengan kompilasi AOT (<PublishAot>true</PublishAot>), Anda harus mengemas secara terpisah untuk setiap platform.

Persyaratan platform untuk AOT Natif

Kompilasi AOT asli memerlukan bagian sistem operasi (OS) dari SDK RID agar sesuai dengan OS RID target. SDK dapat melakukan kompilasi silang untuk arsitektur yang berbeda (misalnya, x64 ke ARM64) tetapi tidak dapat melakukan kompilasi silang di seluruh sistem operasi (misalnya, Windows ke Linux).

Ini berarti Anda memiliki beberapa opsi untuk membuat paket AOT Asli:

Bangun hanya untuk komputer pengembangan Anda: Dukung AOT Asli hanya untuk OS yang Sedang Anda kembangkan.
Gunakan kontainer untuk build Linux: Jika Anda menggunakan macOS atau Windows, gunakan kontainer untuk mengkompilasi silang untuk Linux. Misalnya, gunakan mcr.microsoft.com/dotnet/sdk:10.0-noble-aot gambar kontainer.
Federasikan build Anda lintas mesin: Gunakan sistem CI/CD seperti GitHub Actions atau Azure DevOps Pipelines untuk membangun pada sistem operasi yang berbeda.

Anda tidak perlu membuat semua paket khusus RID pada komputer yang sama atau pada saat yang sama. Anda hanya perlu membangun dan menerbitkannya sebelum menerbitkan paket tingkat atas.

Mengemas alat AOT Asli

Kemas paket tingkat atas sekali (pada platform apa pun):

dotnet pack

Kemas untuk setiap RID tertentu pada platform yang sesuai, misalnya:

dotnet pack -r linux-x64

Anda harus menjalankan setiap perintah paket khusus RID pada platform tempat OS cocok dengan OS RID target. Untuk informasi selengkapnya tentang prasyarat untuk kompilasi AOT Asli, lihat Penyebaran AOT Asli.

Saat Anda mengatur PublishAot ke true, perilaku pengemasan berubah:

dotnet pack menghasilkan paket pointer tingkat atas (jenis DotnetToolpaket ).
Paket AOT khusus RID hanya diproduksi ketika Anda secara eksplisit meneruskan -r <RID>, misalnya, dotnet pack -r linux-x64 atau dotnet pack -r osx-arm64.

Pola pengemasan AOT + CoreCLR Hibrida (contoh)

Beberapa alat menginginkan manfaat terbaik dari dua sisi.

Native AOT untuk subset platform berprioritas tinggi (tergantung pada alat).
Fallback CoreCLR portabel yang dapat digunakan pada platform yang tidak disertakan dalam perangkat AOT Asli.

Anda dapat mencapai model "hibrid" ini dengan pola berikut:

Konfigurasikan alat untuk Native AOT dan RID khusus alat.

Dalam file proyek Anda, gunakan ToolPackageRuntimeIdentifiers dan aktifkan PublishAot.

Contohnya:
```
<ToolPackageRuntimeIdentifiers>osx-arm64;linux-arm64;linux-x64;any</ToolPackageRuntimeIdentifiers>
<PublishAot>true</PublishAot>
```
Buat paket pointer.

Jalankan dotnet pack sekali (pada platform apa pun) untuk membangun paket tingkat atas yang menunjuk ke paket khusus RID:
```
dotnet pack
```
Buat paket AOT Asli untuk RID yang dipilih.

Kompilasi AOT asli memerlukan pembangunan pada platform target. Buat setiap paket RID yang didukung AOT pada platform yang cocok menggunakan dotnet pack -r <RID>.

Contohnya:

dotnet pack -r linux-x64

Membangun paket fallback CoreCLR.

Untuk memberikan fallback universal, kemas any RID tanpa AOT:
```
dotnet pack -r any -p:PublishAot=false
```
Ini menghasilkan paket CoreCLR portabel (misalnya, yourtool.any.<version>.nupkg) yang dapat berjalan pada platform yang tidak memiliki build AOT khusus.

Nota

Anda juga dapat menggunakan .NET SDK 10.0-noble-aot gambar kontainer untuk membangun dan mengemas alat Linux Native AOT dari host apa pun yang mendukung kontainer Linux. Contohnya:

mcr.microsoft.com/dotnet/sdk:10.0-noble-aot

Ini berguna ketika komputer pengembangan Anda tidak menjalankan Linux secara asli.

Dalam penyiapan hibrid ini:

Paket pointer (yourtool.<version>.nupkg) mereferensikan keduanya:
- Paket AOT Asli khusus RID (misalnya, yourtool.osx-arm64, yourtool.linux-x64).
- Paket any CoreCLR sebagai opsi cadangan.
.NET CLI secara otomatis memilih paket yang paling tepat untuk platform pengguna saat mereka menjalankan dotnet tool install atau dnx.

Contoh: `dotnet10-hybrid-tool`

dotnet10-hybrid-tool Repositori menunjukkan pola pengemasan hibrida ini dengan paket Native AOT untuk osx-arm64, linux-arm64, dan linux-x64, ditambah paket fallback CoreCLR untuk any RID (digunakan, misalnya, pada Windows ketika tidak ada build AOT yang tersedia).

Anda dapat menginstal dan mencoba alat ini sendiri:

dotnet tool install -g dotnet10-hybrid-tool
dotnet10-hybrid-tool

Alat ini melaporkan deskripsi kerangka kerja runtime, pengidentifikasi runtime (RID), dan mode kompilasi (Native AOT atau CoreCLR).

Contoh output pada platform dengan Native AOT:

Hi, I'm a 'DotNetCliTool v2' tool!
Yes, I'm quite fancy.

Version: .NET 10.0.2
RID: osx-arm64
Mode: Native AOT

Contoh output pada platform menggunakan fallback CoreCLR:

Hi, I'm a 'DotNetCliTool v2' tool!
Yes, I'm quite fancy.

Version: .NET 10.0.2
RID: win-x64
Mode: CoreCLR

Ini menjadikannya cara yang berguna untuk bereksperimen dengan alat khusus RID yang dikompilasi AOT dan perilaku fallback CoreCLR.

Menerbitkan alat Anda

Saat menerbitkan paket alat khusus RID, .NET CLI menggunakan nomor versi paket tingkat atas untuk memilih paket khusus RID yang cocok. Ini berarti:

Semua paket khusus RID harus memiliki versi yang sama persis dengan paket tingkat atas.
Semua paket harus diterbitkan ke umpan Anda sebelum paket tingkat atas tersedia.

Untuk memastikan proses penerbitan yang lancar:

Terbitkan semua paket khusus RID terlebih dahulu:

dotnet nuget push yourtool.win-x64.1.0.0.nupkg
dotnet nuget push yourtool.linux-x64.1.0.0.nupkg
dotnet nuget push yourtool.osx-arm64.1.0.0.nupkg
dotnet nuget push yourtool.any.1.0.0.nupkg

Terbitkan paket tingkat atas terakhir:
```
dotnet nuget push yourtool.1.0.0.nupkg
```

Menerbitkan paket tingkat atas terakhir memastikan bahwa semua paket khusus RID yang dirujuk tersedia saat pengguna menginstal alat Anda. Jika pengguna menginstal alat Anda sebelum semua paket RID diterbitkan, penginstalan akan gagal.

Menginstal dan menjalankan alat

Apakah alat menggunakan kemasan khusus RID adalah detail implementasi yang transparan bagi pengguna. Anda menginstal dan menjalankan alat dengan cara yang sama, terlepas dari apakah pengembang alat memilih untuk menggunakan pengemasan khusus RID.

Untuk menginstal alat secara global:

dotnet tool install -g mytool

Setelah diinstal, Anda dapat memanggilnya secara langsung:

mytool

Anda juga dapat menggunakan helper dnx, yang berperilaku mirip dengan npx dalam ekosistem Node.js: ia mengunduh dan meluncurkan tool dalam satu gerakan jika belum ada.

dnx mytool

Saat alat menggunakan kemasan khusus RID, .NET CLI secara otomatis memilih paket yang benar untuk platform Anda. Anda tidak perlu menentukan RID—CLI menyimpulkannya dari sistem Anda dan mengunduh paket khusus RID yang sesuai.

Lihat juga

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-01-27