Aracılığıyla paylaş

RID'ye özgü, kendine yeten ve AOT .NET araçları oluşturma

Bu makale şunlar için geçerlidir: ✔️ .NET SDK 10 ve üzeri sürümler

Yerel, hızlı ve kırpılmış uygulamaları dağıtabilmeniz için belirli platformlar ve mimariler için .NET araçlarını paketleyin. Bu özellik, MCP sunucuları veya platforma özgü diğer yardımcı programlar gibi komut satırı araçları için iyileştirilmiş uygulamaları dağıtmayı kolaylaştırır.

Genel Bakış

.NET SDK 10'dan başlayarak, belirli işletim sistemi ortamlarını (Çalışma Zamanı Tanımlayıcıları (RID) ile temsil edilen) hedefleyen .NET araçları oluşturabilirsiniz. Bu araçlar şunlar olabilir:

  • RID'ye özgü: Belirli işletim sistemleri ve mimariler için derlenmiştir.
  • Bağımsız: .NET çalışma zamanını dahil edin ve ayrı bir .NET yüklemesi gerektirmez.
  • Yerel AOT: Daha hızlı başlangıç ve daha küçük bellek ayak izi için Önceden Derleme özelliğini kullanın.

Kullanıcılar aracı yüklerken bir fark fark etmez. .NET CLI, platformları için en iyi paketi otomatik olarak seçer ve yükler.

RID'ye özgü paketlemeyi kabul etme

RID'ye özgü bir araç oluşturmak için projenizi aşağıdaki MSBuild özelliklerinden biriyle yapılandırın:

RuntimeIdentifiers özelliği

Aracının desteklediği platformları belirtmek için kullanın RuntimeIdentifiers :

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

ToolPackageRuntimeIdentifiers özelliği

Alternatif seçenek olarak, araçlar için özel RID yapılandırması için ToolPackageRuntimeIdentifiers kullanın.

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

RID değerlerinin noktalı virgülle ayrılmış listesini kullanın. Çalışma Zamanı Tanımlayıcılarının listesi için bkz. RID kataloğu.

Çerçeveye bağımlı bir sürüm sağlama

RID'ye özgü araç paketlemeyi kabul ettiğinizde, .NET SDK'sı belirtilen her RID için bağımsız paketler oluşturur. Ancak, .NET çalışma zamanının yüklü olduğu herhangi bir platformda çalışan varsayılan çerçeveye bağımlı paketlemeyi kaybedersiniz.

RID'ye özgü paketlerin yanı sıra çerçeveye bağımlı bir sürüm sağlamak için listenize any ekleyinToolPackageRuntimeIdentifiers:

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

Bu yapılandırma beş paket oluşturur:

  • Kullanılabilir tüm alt paketleri listeleyen bir üst düzey işaretçi paketi.
  • Kendi kendine kapsanan ve kırpılan ÜÇ RID'ye özgü paket (win-x64, osx-arm64, linux-x64).
  • Çerçeveye bağımlı olan ve .NET çalışma zamanının yüklenmesini gerektiren bir RID-agnostic paketi (any).

Kullanıcılar aracınızı yüklediğinde:

  • win-x64, osx-arm64veya linux-x64 sistemlerinde, bağımsız, kırpılmış paketler indirilir ve yürütülür.
  • Diğer tüm işletim sistemlerinde veya mimarilerde çerçeveye bağımlı any paket kullanılır.

Bu yaklaşım, ortak platformlar için iyileştirilmiş, bağımsız ikili dosyalar sağlarken, çerçeveye bağımlı geri dönüş aracılığıyla daha az yaygın platformlarla uyumluluğu korur.

Ne zaman RuntimeIdentifiers yerine ToolPackageRuntimeIdentifiers kullanılır?

Hem RuntimeIdentifiers hem de ToolPackageRuntimeIdentifiers aracınızı RID'ye özgü paketleme için kullanılır, ancak bunlar biraz farklı amaçlara sahiptir.

Şu durumlarda kullanın RuntimeIdentifiers :

  • Projenin genel olarak RID'ye özgü uygulamalar derlemesini ve yayımlamasını istiyorsunuz (yalnızca bir araç olarak değil).
  • Öncelikle CoreCLR'yi (AOT olmayan) hedefliyor veya tek dotnet pack bir kullanıcının birden çok RID'ye özgü paket ürettiği standart SDK davranışını istiyorsunuz.
  • RID'lerin bir alt kümesi için PublishAot şartlandırabilirsiniz, ancak yine de RuntimeIdentifiers içindeki her RID için CoreCLR tabanlı bir paket istiyorsunuz.

Şu durumlarda kullanın ToolPackageRuntimeIdentifiers :

  • Projenin diğer dağıtım senaryoları için derleme şeklini değiştirmeden yalnızca araç paketlemesi için RID'ye özgü davranış tanımlamak istiyorsunuz.
  • Yerel AOT kullanıyorsunuz ve el ile RID başına dotnet pack -r <RID> AOT ikili dosyaları oluşturmayı planlıyorsunuz.
  • Bazı RID'lerin Yerel AOT aldığı ve bazılarının taşınabilir CoreCLR uygulamasına geri döndüğü karma bir model istiyorsunuz.

Notes:

  • Üst düzey işaretçi paketi, kullanılabilir RID'ye özgü paketleri belirtir. ToolPackageRuntimeIdentifiers'i belirlerseniz, araç RID'lerini belirler; aksi takdirde RuntimeIdentifiers kullanılır.
  • ToolPackageRuntimeIdentifiers, RuntimeIdentifiers içindeki RID'lerin tamamına eşit veya bir alt kümesi olmalıdır.
  • olduğunda PublishAot=true, RID'ye özgü paketler yalnızca belirli bir RID için paketlediğinizde oluşturulur (örneğin, dotnet pack -r linux-x64).
  • Yerel AOT derlemeleri (PublishAot=true), yalnızca derleme işletim sistemi ve hedef işletim sistemi eşleştiğinde desteklenir.

Aracınızı paketleme

Paketleme işlemi, AOT derlemesi kullanıp kullanmadığınıza bağlı olarak farklılık gösterir. Projeden bir NuGet paketi veya .nupkg dosyası oluşturmak için dotnet pack komutunu çalıştırın.

RID'ye özgü ve bağımsız araçlar

Bir kez çalıştırın dotnet pack :

dotnet pack

Bu komut birden çok NuGet paketi oluşturur:

  • Her RID için bir paket: <packageName>.<RID>.<packageVersion>.nupkg
    • Örnek: mytool.win-x64.1.0.0.nupkg
    • Örnek: mytool.linux-x64.1.0.0.nupkg
    • Örnek: mytool.osx-arm64.1.0.0.nupkg
  • Bağımsız yapıda pointer paketi: <packageName>.<packageVersion>.nupkg
    • Örnek: mytool.1.0.0.nupkg

AOT araçları

AOT derlemesi ()<PublishAot>true</PublishAot> olan araçlar için her platform için ayrı ayrı paketlemeniz gerekir.

Yerel AOT için platform gereksinimleri

Yerel AOT derlemesi, hedef RID'nin işletim sistemiyle eşleşmesi için SDK RID'nin işletim sistemi (OS) bölümünü gerektirir. SDK farklı mimariler için (örneğin, x64 ile ARM64) çapraz derleme yapabilir ancak farklı işletim sistemleri arasında (örneğin, Windows'tan Linux'a) derleme yapamaz.

Bu, Yerel AOT paketleri oluşturmak için çeşitli seçenekleriniz olduğu anlamına gelir:

  • Yalnızca geliştirme makineniz için derleme: Yerel AOT'yi yalnızca geliştirmekte olduğunuz işletim sistemi için destekleyin.
  • Linux derlemeleri için kapsayıcıları kullanma: macOS veya Windows kullanıyorsanız, Linux için çapraz derleme yapmak için kapsayıcıları kullanın. Örneğin mcr.microsoft.com/dotnet/sdk:10.0-noble-aot kapsayıcı görüntülerini kullanın.
  • Derlemenizi makineler arasında bir araya getir: Farklı işletim sistemleri üzerinde derleme yapmak için GitHub Actions veya Azure DevOps Pipelines gibi CI/CD sistemlerini kullanın.

Rid'e özgü tüm paketleri aynı makinede veya aynı anda oluşturmanız gerekmez. En üst düzey paketi yayımlamadan önce bunları derlemeniz ve yayımlamanız yeterlidir.

Yerel AOT araçlarını paketleme

Üst düzey paketi bir kez (herhangi bir platformda) paketle:

dotnet pack

Her bir platformdaki belirli RID için paketleme, örneğin:

dotnet pack -r linux-x64

RID'ye özgü her paket komutunu, işletim sisteminin hedef RID'nin işletim sistemiyle eşleştiği bir platformda çalıştırmanız gerekir. Yerel AOT derlemesinin önkoşulları hakkında daha fazla bilgi için bkz. Yerel AOT dağıtımı.

PublishAot'yi true olarak ayarladığınızda, paketleme davranışı değişir.

  • dotnet pack üst düzey işaretçi paketini (paket türüDotnetTool) üretir.
  • RID'e özgü AOT paketleri, yalnızca -r <RID> gibi belirli bir RID'i açıkça geçtiğinizde, örneğin dotnet pack -r linux-x64 veya dotnet pack -r osx-arm64, oluşturulur.

Hibrit AOT + CoreCLR paketleme düzeni (örnek)

Bazı araçlar her iki dünyanın da en iyisini ister:

  • Yerel AOT, araca bağlı olarak yüksek öncelikli platformların bir alt kümesi için.
  • Yerel AOT derlemeleri tarafından hedeflenmemiş platformlarda çalışan taşınabilir bir CoreCLR geri dönüşü .

Bu "karma" modeli aşağıdaki desenle elde edebilirsiniz:

  1. Aracı Yerel AOT ve araca özgü RID'ler için yapılandırın.

    Proje dosyanızda kullanın ToolPackageRuntimeIdentifiers ve etkinleştirin PublishAot.

    Örneğin:

    <ToolPackageRuntimeIdentifiers>osx-arm64;linux-arm64;linux-x64;any</ToolPackageRuntimeIdentifiers>
<PublishAot>true</PublishAot>

  2. İşaretçi paketini oluşturun.

    RID'ye özgü paketleri işaret eden üst düzey paketi oluşturmak için bir kez (herhangi bir platformda) çalıştırın dotnet pack :

    dotnet pack

  3. Seçili RID'ler için Yerel AOT paketleri oluşturun.

    Yerel AOT derlemesi, hedef platformda inşa edilmesini gerektirir. dotnet pack -r <RID> kullanarak AOT özellikli her RID paketini uyumlu platformda oluşturun.

Örneğin:

dotnet pack -r linux-x64

  1. CoreCLR geri dönüş paketi oluşturun.

    Evrensel bir yedek çözüm sağlamak için RID'yi any AOT kullanmadan paketle:

    dotnet pack -r any -p:PublishAot=false

    Bu, ayrılmış AOT derlemesi olmayan platformlarda çalışabilen taşınabilir bir CoreCLR paketi (örneğin, yourtool.any.<version>.nupkg) üretir.

Uyarı

Linux kapsayıcılarını destekleyen herhangi bir konaktan Linux Doğal AOT araçlarını derleyip paketlemek için .NET SDK 10.0-noble-aot kapsayıcı görüntülerini de kullanabilirsiniz. Örneğin:

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

Geliştirme makineniz Linux'u yerel olarak çalışmadığı durumlarda bu kullanışlıdır.

Bu karma kurulumda:

  • İşaretçi paketi (yourtool.<version>.nupkg) her ikisine de başvurur:
    • RID'e özgü Yerel AOT paketleri (örneğin, yourtool.osx-arm64, yourtool.linux-x64).
    • Yedek olarak any CoreCLR paketi.
  • .NET CLI, kullanıcı dotnet tool install veya dnx çalıştırdığında, kullanıcının platformu için en uygun paketi otomatik olarak seçer.

Örnek: dotnet10-hybrid-tool

Bu dotnet10-hybrid-tool depo, osx-arm64, linux-arm64, ve linux-x64 için Yerel AOT paketlerinin yanı sıra, RID any için (özellikle Windows'ta AOT derlemesi mevcut olmadığında kullanılan) bir CoreCLR yedek paketi ile bu karma paketleme desenini göstermektedir.

Aracı kendiniz yükleyebilir ve deneyebilirsiniz:

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

Araç çalışma zamanı çerçevesi açıklamasını, çalışma zamanı tanımlayıcısını (RID) ve derleme modunu (Yerel AOT veya CoreCLR) bildirir.

Yerel AOT içeren bir platformda örnek çıktı:

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

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

CoreCLR yedekleme işlevini kullanan bir platformda örnek bir çıktı:

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

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

Bu, RID'ye özgü, AOT ile derlenmiş araçlar ve CoreCLR geri dönüş davranışıyla deneme yapmak için kullanışlı bir yoldur.

Aracınızı yayımlama

RID'ye özgü araç paketleri yayımlandığında .NET CLI, eşleşen RID'ye özgü paketleri seçmek için üst düzey paketin sürüm numarasını kullanır. Bu, şu anlama gelir:

  • RID'ye özgü tüm paketlerin en üst düzey paketle tam olarak aynı sürüme sahip olması gerekir.
  • Üst düzey paket kullanılabilir duruma gelmeden önce tüm paketlerin akışınızda yayımlanması gerekir.

Sorunsuz bir yayımlama işlemi sağlamak için:

  1. Önce RID'ye özgü tüm paketleri yayımlayın:

    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

  2. En üst düzey paketi en son yayımlayın:

    dotnet nuget push yourtool.1.0.0.nupkg

En son üst düzey paketi yayımlamak, kullanıcılar aracınızı yüklediğinde başvuruda bulunulan TÜM RID'ye özgü paketlerin kullanılabilir olmasını sağlar. Kullanıcı tüm RID paketleri yayımlanmadan önce aracınızı yüklerse yükleme başarısız olur.

Araçları yükleme ve çalıştırma

Bir aracın RID'ye özgü paketleme kullanıp kullanmadığı, kullanıcılar için saydam olan bir uygulama ayrıntısıdır. Araç geliştiricisinin RID'ye özgü paketlemeyi kabul edip etmediğine bakılmaksızın araçları aynı şekilde yükler ve çalıştırırsınız.

Bir aracı genel olarak yüklemek için:

dotnet tool install -g mytool

Yüklendikten sonra doğrudan çağırabilirsiniz:

mytool

Node.js ekosistemindekine benzer dnx şekilde davranan yardımcıyı da kullanabilirsiniznpx: Henüz mevcut değilse bir aracı tek bir hareketle indirir ve başlatır:

dnx mytool

Bir araç RID'ye özgü paketleme kullandığında.NET CLI, platformunuz için doğru paketi otomatik olarak seçer. BIR RID belirtmeniz gerekmez; CLI bunu sisteminizden çıkarsar ve uygun RID'ye özgü paketi indirir.

Ayrıca bakınız

  • Last updated on