Sdílet prostřednictvím

Vytvářejte samostatné nástroje .NET specifické pro RID a AOT

Tento článek se vztahuje na: ✔️ .NET SDK 10 a novější verze

Zabalte nástroje .NET pro konkrétní platformy a architektury, abyste mohli distribuovat nativní, rychlé a oříznuté aplikace. Tato funkce usnadňuje distribuci optimalizovaných aplikací pro nástroje příkazového řádku, jako jsou servery MCP nebo jiné nástroje specifické pro platformu.

Přehled

Počínaje sadou .NET SDK 10 můžete vytvořit nástroje .NET, které cílí na konkrétní prostředí operačního systému (reprezentované identifikátory RID)). Tyto nástroje můžou být:

  • Specifické pro identifikátor RID: Kompilováno pro konkrétní operační systémy a architektury.
  • Samostatné: Zahrňte modul runtime .NET a nevyžadují samostatnou instalaci .NET.
  • Nativní AOT: Pro rychlejší spouštění a menší nároky na paměť použijte předem připravenou kompilaci.

Uživatelé si při instalaci nástroje nevšimnou rozdílu. Rozhraní .NET CLI automaticky vybere a nainstaluje nejlepší balíček pro svou platformu.

Přihlaste se k balení specifickému pro RID

Pokud chcete vytvořit nástroj specifický pro identifikátor RID, nakonfigurujte projekt pomocí jedné z následujících vlastností nástroje MSBuild:

RuntimeIdentifiers – vlastnost

Slouží RuntimeIdentifiers k určení platforem, které nástroj podporuje:

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

vlastnost ToolPackageRuntimeIdentifiers

Alternativně můžete použít ToolPackageRuntimeIdentifiers pro konfiguraci identifikátorů RID pro konkrétní nástroje:

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

Použijte seznam hodnot IDENTIFIKÁTORŮ RID oddělený středníkem. Seznam identifikátorů modulu runtime najdete v katalogu IDENTIFIKÁTORŮ RID.

Poskytnutí verze závislé na rozhraní

Když zvolíte balení nástrojů specifických pro RID, .NET SDK vytvoří soběstačné balíčky pro každý zadaný RID. Ztratíte však výchozí balíček závislý na rozhraní, který funguje na libovolné platformě s nainstalovaným modulem runtime .NET.

Pokud chcete poskytnout verzi závislou na frameworku společně s balíčky specifickými pro prostředí RID, přidejte any do seznamu ToolPackageRuntimeIdentifiers:

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

Tato konfigurace vytvoří pět balíčků:

  • Jeden balíček ukazatele nejvyšší úrovně, který obsahuje seznam všech dostupných dílčích balíčků.
  • Tři balíčky specifické pro RID (win-x64, osx-arm64, linux-x64), které jsou samostatně obsažené a optimalizované.
  • Jeden balíček nezávislý na identifikátorech RID (any), který je závislý na rozhraní a vyžaduje instalaci modulu runtime .NET.

Když uživatelé nainstalují nástroj:

  • Na systémech win-x64, osx-arm64 nebo linux-x64 se stáhnou a spustí samostatné a oříznuté balíčky.
  • V jakémkoli jiném operačním systému nebo architektuře se použije balíček závislý na any architektuře.

Tento přístup poskytuje optimalizované samostatné binární soubory pro běžné platformy a současně zachovává kompatibilitu s méně běžnými platformami prostřednictvím záložního řešení závislého na rozhraní.

Kdy použít RuntimeIdentifiers vs. ToolPackageRuntimeIdentifiers

Oba RuntimeIdentifiers a ToolPackageRuntimeIdentifiers zařadí váš nástroj do balení podle RID, ale slouží mírně odlišným účelům:

Použít RuntimeIdentifiers když:

  • Chcete, aby projekt sestavil a publikoval aplikace obecně specifické pro identifikátory RID (nejen jako nástroj).
  • Primárně cílíte na CoreCLR (jiné než AOT) nebo chcete standardní chování sady SDK, kdy jeden dotnet pack vytváří více balíčků specifických pro identifikátory RID.
  • Můžete určit podmínky pro PublishAot u podmnožiny identifikátorů RID, ale přesto chcete balíček založený na CoreCLR pro každý identifikátor RID v rámci RuntimeIdentifiers.

Použít ToolPackageRuntimeIdentifiers když:

  • Chcete definovat chování specifické pro identifikátory RID pouze pro balení nástrojů, aniž byste změnili způsob sestavení projektu pro jiné scénáře nasazení.
  • Používáte nativní AOT a plánujete ručně sestavit binární soubory AOT pro každý RID pomocí dotnet pack -r <RID>.
  • Chcete hybridní model , kde některé identifikátory RID získávají nativní AOT a jiné se vrátí k přenosné implementaci CoreCLR.

Notes:

  • Balíček ukazatele nejvyšší úrovně určuje dostupné balíčky specifické pro identifikátory RID. Pokud zadáte ToolPackageRuntimeIdentifiers, určí to identifikátory RID nástroje; jinak se použije RuntimeIdentifiers.
  • ToolPackageRuntimeIdentifiers by měla být rovna nebo podmnožině identifikátorů RID v RuntimeIdentifiers
  • Pokud PublishAot=truese balíčky specifické pro identifikátory RID generují pouze v případě, dotnet pack -r linux-x64že zabalíte konkrétní identifikátor RID (například).
  • Nativní sestavení AOT (PublishAot=true) se podporují jenom v případech, kdy se operační systém sestavení a cílový operační systém shodují.

Zabalte svůj nástroj

Proces balení se liší v závislosti na tom, jestli používáte kompilaci AOT. Pokud chcete vytvořit balíček NuGet nebo soubor .nupkg z projektu, spusťte příkaz dotnet pack .

Nástroje určené specificky pro RID a nezávislé nástroje

Spusťte dotnet pack jednou:

dotnet pack

Tento příkaz vytvoří několik balíčků NuGet:

  • Jeden balíček pro každý identifikátor RID: <packageName>.<RID>.<packageVersion>.nupkg
    • Příklad: mytool.win-x64.1.0.0.nupkg
    • Příklad: mytool.linux-x64.1.0.0.nupkg
    • Příklad: mytool.osx-arm64.1.0.0.nupkg
  • Jeden balíček ukazatele nezávislý na identifikátoru RID: <packageName>.<packageVersion>.nupkg
    • Příklad: mytool.1.0.0.nupkg

Nástroje AOT

Pro nástroje s kompilací AOT (<PublishAot>true</PublishAot>) je nutné zabalit zvlášť pro každou platformu.

Požadavky na platformu pro nativní AOT

Nativní kompilace AOT vyžaduje, aby část operačního systému (OS) identifikátoru RID sady SDK odpovídala operačnímu systému cílového identifikátoru RID. Sada SDK může křížově kompilovat různé architektury (například x64 až ARM64), ale ne napříč operačními systémy (například Windows do Linuxu).

To znamená, že máte několik možností pro vytváření nativních balíčků AOT:

  • Sestavení pouze pro váš vývojový počítač: Podpora nativní AOT pouze pro operační systém, na kterém vyvíjíte.
  • Používejte kontejnery pro linuxové buildy: Pokud používáte macOS nebo Windows, použijte kontejnery k křížovému kompilaci pro Linux. Například použijte mcr.microsoft.com/dotnet/sdk:10.0-noble-aot kontejnerové image.
  • Federujte sestavení napříč počítači: K sestavování na různých operačních systémech používejte systémy CI/CD, jako jsou GitHub Actions nebo Azure DevOps Pipelines.

Nemusíte vytvářet všechny balíčky specifické pro identifikátory RID na stejném počítači nebo ve stejnou dobu. Před publikováním balíčku nejvyšší úrovně stačí je sestavit a publikovat.

Balení nativních nástrojů AOT

Balíček nejvyšší úrovně zabalte jednou (na libovolné platformě):

dotnet pack

Zabalte pro každé specifické RID na odpovídající platformě, například:

dotnet pack -r linux-x64

Každý příkaz balíčku specifického pro identifikátory RID musíte spustit na platformě, kde operační systém odpovídá operačnímu systému cílového identifikátoru RID. Další informace o požadavcích na nativní kompilaci AOT najdete v tématu Nativní nasazení AOT.

Když nastavíte PublishAot na true, chování při balení se změní:

  • dotnet pack produkuje balíček ukazatele nejvyšší úrovně (typ DotnetTool).
  • Balíčky AOT specifické pro identifikátory RID se vytváří pouze v případě, že explicitně předáte například -r <RID>, dotnet pack -r linux-x64 nebo dotnet pack -r osx-arm64.

Model balení Hybrid AOT + CoreCLR (příklad)

Některé nástroje chtějí nejlepší z obou světů:

  • Nativní AOT pro podmnožinu platforem s vysokou prioritou (v závislosti na nástroji)
  • Přenosná záložní sada CoreCLR, která funguje na platformách, které nejsou cílem nativních sestavení AOT.

Tento "hybridní" model můžete dosáhnout následujícím modelem:

  1. Nakonfigurujte nástroj pro nativní identifikátory AOT a identifikátory RID specifické pro konkrétní nástroje.

    V souboru projektu použijte ToolPackageRuntimeIdentifiers a povolte PublishAot.

    Například:

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

  2. Vytvořte balíček ukazatele.

    Spuštěním dotnet pack jednou (na libovolné platformě) sestavte balíček nejvyšší úrovně, který odkazuje na balíčky specifické pro identifikátory RID:

    dotnet pack

  3. Sestavte nativní AOT balíčky pro vybrané RIDs.

    Nativní kompilace AOT vyžaduje provádět sestavení na cílové platformě. Sestavte každý RID balíček s podporou AOT na odpovídající platformě pomocí dotnet pack -r <RID>.

Například:

dotnet pack -r linux-x64

  1. Sestavení záložního balíčku CoreCLR

    Pokud chcete poskytnout univerzální zálohu, zabalte any identifikátor RID bez AOT:

    dotnet pack -r any -p:PublishAot=false

    Tím se vytvoří přenosný balíček CoreCLR (například yourtool.any.<version>.nupkg), který se dá spustit na platformách, které nemají vyhrazený build AOT.

Poznámka:

Obrazy kontejnerů .NET SDK 10.0-noble-aot můžete také použít k sestavení a zabalení nativních nástrojů AOT pro Linux z libovolného hostitele, který podporuje kontejnery Linuxu. Například:

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

To je užitečné, když váš vývojový počítač nativně neběží s Linuxem.

V tomto hybridním nastavení:

  • Balíček ukazatele (yourtool.<version>.nupkg) odkazuje na oba:
    • Nativní AOT balíčky specifické pro platformy RID (například yourtool.osx-arm64, yourtool.linux-x64).
    • Balíček any CoreCLR jako záložní balíček.
  • .NET CLI automaticky vybere nejvhodnější balíček pro platformu uživatele při spuštění dotnet tool install nebo dnx.

Příklad: dotnet10-hybrid-tool

Úložiště dotnet10-hybrid-tool ukazuje tento hybridní vzor balení s nativními balíčky AOT pro osx-arm64, linux-arm64 a linux-x64, plus záložní balíček CoreCLR pro any RID (používá se například na Windows, pokud není k dispozici žádný build AOT).

Nástroj si můžete nainstalovat a vyzkoušet sami:

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

Nástroj hlásí popis rozhraní runtime, identifikátor modulu runtime (RID) a režim kompilace (nativní AOT nebo CoreCLR).

Příklad výstupu na platformě s nativní AOT:

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

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

Příklad výstupu na platformě s využitím náhradní verze CoreCLR:

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

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

Tím se stává užitečným způsobem pro experimentování s nástroji specifickými pro RID a zkompilovanými pomocí AOT a s chováním záložního mechanismu CoreCLR.

Publikování nástroje

Při publikování balíčků nástrojů specifických pro identifikátory RID používá rozhraní .NET CLI číslo verze balíčku nejvyšší úrovně k výběru odpovídajících balíčků specifických pro identifikátory RID. To znamená:

  • Všechny balíčky specifické pro identifikátory RID musí mít stejnou verzi jako balíček nejvyšší úrovně.
  • Všechny balíčky musí být publikovány ve vašem informačním kanálu, než se zpřístupní balíček nejvyšší úrovně.

Zajištění hladkého procesu publikování:

  1. Nejprve publikujte všechny RID-specifické balíčky:

    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. Publikujte balíček nejvyšší úrovně jako poslední:

    dotnet nuget push yourtool.1.0.0.nupkg

Publikování balíčku nejvyšší úrovně naposledy zajišťuje, že všechny odkazované balíčky specifické pro identifikátory RID budou k dispozici, když uživatelé nainstalují váš nástroj. Pokud uživatel nainstaluje nástroj před publikováním všech balíčků RID, instalace se nezdaří.

Instalace a spouštění nástrojů

Zda nástroj používá balíčkování specifické pro identifikátory RID, je implementační detail, který je pro uživatele transparentní. Nástroje nainstalujete a spustíte stejným způsobem bez ohledu na to, jestli vývojář nástroje zvolil balení specifické pro identifikátory RID.

Globální instalace nástroje:

dotnet tool install -g mytool

Po instalaci ji můžete vyvolat přímo:

mytool

Můžete také použít dnx pomocníka, který se chová podobně jako npx v ekosystému Node.js: stáhne a spustí nástroj jediným gestem, pokud ještě není k dispozici:

dnx mytool

Když nástroj používá balení specifické pro identifikátory RID, rozhraní příkazového řádku .NET automaticky vybere správný balíček pro vaši platformu. Nemusíte zadávat identifikátor RID – rozhraní příkazového řádku ho odvodí z vašeho systému a stáhne příslušný balíček specifický pro identifikátor RID.

Viz také

  • Last updated on