Share via

RID-specifieke, zelfstandige en AOT .NET-hulpprogramma's maken

Dit artikel is van toepassing op: ✔️ .NET SDK 10 en latere versies

Pakket .NET-hulpprogramma's voor specifieke platformen en architecturen, zodat u systeemeigen, snelle en bijgesneden toepassingen kunt distribueren. Deze mogelijkheid maakt het eenvoudiger om geoptimaliseerde toepassingen te distribueren voor opdrachtregelprogramma's zoals MCP-servers of andere platformspecifieke hulpprogramma's.

Overzicht

Vanaf .NET SDK 10 kunt u .NET-hulpprogramma's maken die zijn gericht op specifieke besturingssysteemomgevingen (vertegenwoordigd door runtime-id's (RID's)). Deze hulpprogramma's kunnen het volgende zijn:

  • RID-specifiek: gecompileerd voor bepaalde besturingssystemen en architecturen.
  • Zelfstandig: neem de .NET-runtime op en vereist geen afzonderlijke .NET-installatie.
  • Systeemeigen AOT: gebruik vooraf compilatie voor sneller opstarten en kleinere geheugenvoetafdruk.

Gebruikers merken geen verschil wanneer ze het hulpprogramma installeren. De .NET CLI selecteert en installeert automatisch het beste pakket voor hun platform.

Aanmelden voor RID-specifieke verpakking

Als u een RID-specifiek hulpprogramma wilt maken, configureert u uw project met een van de volgende MSBuild-eigenschappen:

Eigenschap RuntimeIdentifiers

Gebruik RuntimeIdentifiers dit om de platforms op te geven die door uw hulpprogramma worden ondersteund:

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

Eigenschap ToolPackageRuntimeIdentifiers

U kunt ook gebruiken ToolPackageRuntimeIdentifiers voor hulpprogrammaspecifieke RID-configuratie:

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

Gebruik een door puntkomma's gescheiden lijst met RID-waarden. Zie de RID-catalogus voor een lijst met runtime-id's.

Wanneer gebruikt u RuntimeIdentifiers versus ToolPackageRuntimeIdentifiers

Zowel RuntimeIdentifiers als ToolPackageRuntimeIdentifiers activeert de rid-specifieke verpakking van uw hulpprogramma, maar ze hebben enigszins verschillende doeleinden:

Gebruik RuntimeIdentifiers wanneer:

  • U wilt dat het project RID-specifieke apps in het algemeen bouwt en publiceert (niet alleen als een hulpprogramma).
  • U richt zich voornamelijk op CoreCLR (niet-AOT) of u wilt het standaard-SDK-gedrag waarbij één enkele dotnet pack RID-specifieke pakketten produceert.
  • U kunt voorwaardelijk maken PublishAot voor een subset van RID's, maar u wilt nog steeds een CoreCLR-pakket voor elke RID in RuntimeIdentifiers.

Gebruik ToolPackageRuntimeIdentifiers wanneer:

  • U wilt alleen RID-specifiek gedrag definiëren voor het verpakken van hulpprogramma's, zonder dat u hoeft te wijzigen hoe het project wordt gebouwd voor andere implementatiescenario's.
  • U gebruikt systeemeigen AOT en bent van plan om handmatig binaire AOT-bestanden per RID te bouwen met dotnet pack -r <RID>.
  • U wilt een hybride model waarbij sommige RID's systeemeigen AOT krijgen en anderen terugvallen op een draagbare CoreCLR-implementatie.

Notes:

  • Met het aanwijzerpakket op het hoogste niveau worden de beschikbare RID-specifieke pakketten opgegeven. Als u ToolPackageRuntimeIdentifiers opgeeft, bepaalt dat de tool-ID's; anders wordt RuntimeIdentifiers gebruikt.
  • ToolPackageRuntimeIdentifiers moet gelijk zijn aan of een subset van de RID's in RuntimeIdentifiers
  • Wanneer PublishAot=true, RID-specifieke pakketten worden alleen gegenereerd wanneer u inpakt voor een specifieke RID (bijvoorbeeld dotnet pack -r linux-x64).
  • Systeemeigen AOT-builds (PublishAot=true) worden alleen ondersteund wanneer het build-OS en het doel-OS overeenkomen.

Uw hulpprogramma verpakken

Het verpakkingsproces verschilt, afhankelijk van of u AOT-compilatie gebruikt. Als u een NuGet-pakket of .nupkg-bestand wilt maken vanuit het project, voert u de opdracht dotnet pack uit.

RID-specifieke en zelfstandige hulpprogramma's

Eenmaal uitvoeren dotnet pack :

dotnet pack

Met deze opdracht worden meerdere NuGet-pakketten gemaakt:

  • Eén pakket voor elke RID: <packageName>.<RID>.<packageVersion>.nupkg
    • Voorbeeld: mytool.win-x64.1.0.0.nupkg
    • Voorbeeld: mytool.linux-x64.1.0.0.nupkg
    • Voorbeeld: mytool.osx-arm64.1.0.0.nupkg
  • Eén RID-agnostisch aanwijzerpakket: <packageName>.<packageVersion>.nupkg
    • Voorbeeld: mytool.1.0.0.nupkg

AOT-hulpprogramma's

Voor hulpprogramma's met AOT-compilatie (<PublishAot>true</PublishAot>) moet u afzonderlijk inpakken voor elk platform.

Platformvereisten voor systeemeigen AOT

Systeemeigen AOT-compilatie vereist dat het besturingssysteem (OS) van de SDK RID overeenkomt met het besturingssysteem van de doel-RID. De SDK kan kruislings compileren voor verschillende architecturen (bijvoorbeeld x64 naar ARM64), maar niet tussen besturingssystemen (bijvoorbeeld Windows naar Linux).

Dit betekent dat u verschillende opties hebt voor het bouwen van systeemeigen AOT-pakketten:

  • Alleen bouwen voor uw ontwikkelcomputer: ondersteuning voor systeemeigen AOT alleen voor het besturingssysteem waarop u ontwikkelt.
  • Gebruik containers voor Linux-builds: als u macOS of Windows gebruikt, gebruikt u containers om kruislings te compileren voor Linux. Gebruik bijvoorbeeld mcr.microsoft.com/dotnet/sdk:10.0-noble-aot containerafbeeldingen.
  • Uw build federeren op verschillende computers: gebruik CI/CD-systemen zoals GitHub Actions of Azure DevOps Pipelines om te bouwen op verschillende besturingssystemen.

U hoeft niet alle RID-specifieke pakketten op dezelfde computer of tegelijkertijd te bouwen. U hoeft ze alleen te bouwen en te publiceren voordat u het pakket op het hoogste niveau publiceert.

Native AOT-tools verpakken

Pak het pakket op het hoogste niveau eenmaal in (op elk platform):

dotnet pack

Verpak voor elke specifieke RID op het bijbehorende platform, bijvoorbeeld:

dotnet pack -r linux-x64

U moet elke RID-specifieke packopdracht uitvoeren op een platform waarop het besturingssysteem overeenkomt met het besturingssysteem van de doel-RID. Zie Systeemeigen AOT-implementatie voor meer informatie over de vereisten voor systeemeigen AOT-compilatie.

Wanneer u PublishAot instelt op true, verandert het verpakkingsgedrag:

  • dotnet pack produceert het aanwijzerpakket op het hoogste niveau (pakkettype DotnetTool).
  • RID-specifieke AOT-pakketten worden alleen geproduceerd wanneer u expliciet doorgeeft -r <RID>, bijvoorbeeld dotnet pack -r linux-x64 of dotnet pack -r osx-arm64.

Patroon hybride AOT + CoreCLR-verpakkingspatroon (voorbeeld)

Sommige hulpprogramma's willen het beste van beide werelden:

  • Systeemeigen AOT voor een subset van platforms met hoge prioriteit (afhankelijk van het hulpprogramma).
  • Een draagbare CoreCLR-terugval die werkt op platforms waarop geen systeemeigen AOT-builds van toepassing zijn.

U kunt dit hybride model bereiken met het volgende patroon:

  1. Configureer het hulpprogramma voor systeemeigen AOT en hulpprogrammaspecifieke RID's.

    Gebruik ToolPackageRuntimeIdentifiers in uw projectbestand en schakel PublishAot in.

    Voorbeeld:

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

  2. Maak het aanwijzerpakket.

    Eenmaal dotnet pack uitvoeren (op elk platform) om het pakket op het hoogste niveau te bouwen dat verwijst naar de RID-specifieke pakketten:

    dotnet pack

  3. Bouw systeemeigen AOT-pakketten voor geselecteerde RID's.

    Voor native AOT-compilatie moet je bouwen op het doelplatform. Bouw elk RID-pakket met AOT-functionaliteit op het overeenkomende platform met behulp van dotnet pack -r <RID>.

Voorbeeld:

dotnet pack -r linux-x64

  1. Bouw een CoreCLR-terugvalpakket.

    Als u een universele terugval wilt bieden, kunt u de any RID zonder AOT inpakken:

    dotnet pack -r any -p:PublishAot=false

    Dit produceert een draagbaar CoreCLR-pakket (bijvoorbeeld yourtool.any.<version>.nupkg) dat kan worden uitgevoerd op platforms die geen toegewezen AOT-build hebben.

Opmerking

U kunt ook de .NET SDK 10.0-noble-aot containerinstallatiekopieën gebruiken om systeemeigen Linux-AOT-hulpprogramma's te bouwen en te verpakken vanaf elke host die Ondersteuning biedt voor Linux-containers. Voorbeeld:

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

Dit is handig wanneer op uw ontwikkelcomputer geen systeemeigen Linux wordt uitgevoerd.

In deze hybride installatie:

  • Het aanwijzerpakket (yourtool.<version>.nupkg) verwijst naar beide:
    • RID-specifieke systeemeigen AOT-pakketten (bijvoorbeeld yourtool.osx-arm64, yourtool.linux-x64).
    • Het any CoreCLR-pakket als een reserveoptie.
  • De .NET CLI kiest automatisch het meest geschikte pakket voor het platform van de gebruiker wanneer zij dotnet tool install of dnx uitvoeren.

Voorbeeld: dotnet10-hybrid-tool

De dotnet10-hybrid-tool repository demonstreert dit patroon voor hybride pakketten met systeemeigen AOT-pakketten voor osx-arm64, linux-arm64, en linux-x64, plus een CoreCLR-terugvalpakket voor de any RID (bijvoorbeeld op Windows wanneer er geen AOT-build beschikbaar is).

U kunt het hulpprogramma zelf installeren en uitproberen:

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

Het hulpprogramma rapporteert de beschrijving van het runtimeframework, de runtime-id (RID) en de compilatiemodus (Native AOT of CoreCLR).

Voorbeelduitvoer op een platform met 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

Voorbeelduitvoer op een platform met behulp van de CoreCLR-terugval:

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

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

Dit maakt het een handige manier om te experimenteren met RID-specifieke, AOT-gecompileerde hulpprogramma's en het coreCLR-terugvalgedrag.

Uw hulpprogramma publiceren

Bij het publiceren van RID-specifieke hulpprogrammapakketten gebruikt de .NET CLI het versienummer van het pakket op het hoogste niveau om de overeenkomende RID-specifieke pakketten te selecteren. Dit betekent:

  • Alle RID-specifieke pakketten moeten exact dezelfde versie hebben als het pakket op het hoogste niveau.
  • Alle pakketten moeten naar uw feed worden gepubliceerd voordat het pakket op het hoogste niveau beschikbaar wordt.

Een soepel publicatieproces garanderen:

  1. Publiceer eerst alle RID-specifieke pakketten:

    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. Publiceer het pakket op het hoogste niveau als laatste:

    dotnet nuget push yourtool.1.0.0.nupkg

Door het pakket op het hoogste niveau als laatste te publiceren, zorgt u ervoor dat alle RID-specifieke pakketten beschikbaar zijn wanneer gebruikers uw hulpprogramma installeren. Als een gebruiker uw hulpprogramma installeert voordat alle RID-pakketten worden gepubliceerd, mislukt de installatie.

Hulpprogramma's installeren en uitvoeren

Of een hulpprogramma gebruikmaakt van RID-specifieke pakketten is een implementatiedetails die transparant is voor gebruikers. U installeert en voert hulpprogramma's op dezelfde manier uit, ongeacht of de ontwikkelaar van het hulpprogramma heeft gekozen voor een RID-specifieke verpakking.

Een hulpprogramma globaal installeren:

dotnet tool install -g mytool

Zodra de app is geïnstalleerd, kunt u deze rechtstreeks aanroepen:

mytool

U kunt ook de dnx helper gebruiken, die zich op dezelfde manier npx gedraagt als in het Node.js ecosysteem: het downloadt en start een hulpprogramma in één gebaar als deze nog niet aanwezig is:

dnx mytool

Wanneer een hulpprogramma gebruikmaakt van RID-specifieke pakketten, selecteert de .NET CLI automatisch het juiste pakket voor uw platform. U hoeft geen RID op te geven. De CLI geeft deze af van uw systeem en downloadt het juiste RID-specifieke pakket.

Zie ook

  • Last updated on