Teilen über

Erstellen von RID-spezifischen, eigenständigen und AOT .NET-Tools

Dieser Artikel bezieht sich auf: ✔️ .NET SDK 10 und höhere Versionen

Packen Sie .NET-Tools für bestimmte Plattformen und Architekturen, damit Sie systemeigene, schnelle und gekürzte Anwendungen verteilen können. Diese Funktion erleichtert die Verteilung optimierter Anwendungen für Befehlszeilentools wie MCP-Server oder andere plattformspezifische Dienstprogramme.

Überblick

Ab .NET SDK 10 können Sie .NET-Tools erstellen, die auf bestimmte Betriebssystemumgebungen abzielen (dargestellt durch Runtime Identifiers (RIDs)). Diese Tools können folgendes sein:

  • RID-spezifisch: Kompiliert für bestimmte Betriebssysteme und Architekturen.
  • Eigenständig: Schließen Sie die .NET-Laufzeit ein, und benötigen Sie keine separate .NET-Installation.
  • Native AOT: Verwenden Sie die Ahead-of-Time-Kompilierung für einen schnelleren Start und einen geringeren Speicherbedarf.

Benutzer bemerken keinen Unterschied, wenn sie das Tool installieren. Die .NET CLI wählt automatisch das beste Paket für ihre Plattform aus und installiert es.

Melden Sie sich für RID-spezifische Verpackungen an.

Um ein RID-spezifisches Tool zu erstellen, konfigurieren Sie Ihr Projekt mit einer der folgenden MSBuild-Eigenschaften:

RuntimeIdentifiers-Eigenschaft

Wird RuntimeIdentifiers verwendet, um die Plattformen anzugeben, die Ihr Tool unterstützt:

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

Alternativ können Sie die werkzeugspezifische RID-Konfiguration verwenden: ToolPackageRuntimeIdentifiers

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

Verwenden Sie eine durch Semikolons getrennte Liste von RID-Werten. Eine Liste der Runtime-IDs finden Sie im RID-Katalog.

Bereitstellen einer framework-abhängigen Version

Wenn Sie sich für die RID-spezifische Toolverpackung entscheiden, erstellt das .NET SDK eigenständige Pakete für jedes angegebene RID. Allerdings verlieren Sie die standardmäßige frameworkabhängige Verpackung, die auf jeder Plattform funktioniert, auf der .NET-Runtime installiert ist.

Um eine frameworkabhängige Version zusammen mit RID-spezifischen Paketen bereitzustellen, fügen Sie any Ihrer ToolPackageRuntimeIdentifiers Liste Folgendes hinzu:

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

Diese Konfiguration erstellt fünf Pakete:

  • Ein Zeigerpaket auf oberster Ebene, das alle verfügbaren Unterpakete auflistet.
  • Drei RID-spezifische Pakete (win-x64, osx-arm64, linux-x64), die eigenständig und getrimmt sind.
  • Ein RID-agnostisches Paket (any), das vom Framework abhängig ist und erfordert, dass die .NET-Laufzeitumgebung installiert ist.

Wenn Benutzer Ihr Tool installieren:

  • Auf win-x64, osx-arm64oder linux-x64 Systemen werden die eigenständigen, gekürzten Pakete heruntergeladen und ausgeführt.
  • Auf allen anderen Betriebssystemen oder Architekturen wird das frameworkabhängige any Paket verwendet.

Dieser Ansatz bietet optimierte, eigenständige Binärdateien für allgemeine Plattformen, während die Kompatibilität mit weniger gängigen Plattformen über den frameworkabhängigen Fallback beibehalten wird.

Wann verwendet werden soll RuntimeIdentifiers im Vergleich ToolPackageRuntimeIdentifiers

Sowohl RuntimeIdentifiers als auch ToolPackageRuntimeIdentifiers wählen Ihr Tool für RID-spezifische Verpackungen, aber sie dienen leicht unterschiedlichen Zwecken:

Verwenden Sie RuntimeIdentifiers in folgenden Fällen:

  • Sie möchten, dass das Projekt RID-spezifische Apps im Allgemeinen erstellen und veröffentlichen soll (nicht nur als Tool).
  • Sie sind in erster Linie auf CoreCLR (non-AOT) ausgerichtet, oder Sie möchten das Standard-SDK-Verhalten, bei dem ein einzelner dotnet pack mehrere RID-spezifische Pakete erzeugt.
  • Sie können PublishAot für eine Teilmenge der RIDs bedingt anwenden, aber Sie möchten dennoch ein CoreCLR-basiertes Paket für jedes RID in RuntimeIdentifiers erhalten.

Verwenden Sie ToolPackageRuntimeIdentifiers in folgenden Fällen:

  • Sie möchten RID-spezifisches Verhalten nur für die Toolverpackung definieren, ohne zu ändern, wie das Projekt für andere Bereitstellungsszenarien erstellt wird.
  • Sie verwenden Native AOT und planen, AOT-Binärdateien manuell für jede RID mit zu kompilieren.
  • Sie möchten ein Hybridmodell , bei dem einige RIDs native AOT erhalten und andere auf eine portable CoreCLR-Implementierung zurückgreifen.

Notes:

  • Das Zeigerpaket der obersten Ebene gibt die verfügbaren RID-spezifischen Pakete an. Wenn Sie angeben ToolPackageRuntimeIdentifiers, bestimmt es die Tool-RIDs; andernfalls RuntimeIdentifiers wird verwendet.
  • ToolPackageRuntimeIdentifiers sollte gleich sein oder eine Teilmenge der RIDs in RuntimeIdentifiers darstellen.
  • Wenn PublishAot=true RID-spezifische Pakete nur dann generiert werden, wenn Sie für ein bestimmtes RID packen (z. B. dotnet pack -r linux-x64).
  • Native AOT-Builds (PublishAot=true) werden nur unterstützt, wenn das Buildbetriebssystem und das Zielbetriebssystem identisch sind.

Ihr Tool verpacken

Der Verpackungsprozess unterscheidet sich je nachdem, ob Sie die AOT-Kompilierung verwenden. Um ein NuGet-Paket oder eine nupkg-Datei aus dem Projekt zu erstellen, führen Sie den Dotnet Pack-Befehl aus.

RID-spezifische und in sich geschlossene Tools

dotnet pack einmal ausführen

dotnet pack

Mit diesem Befehl werden mehrere NuGet-Pakete erstellt:

  • Ein Paket für jedes RID: <packageName>.<RID>.<packageVersion>.nupkg
    • Beispiel: mytool.win-x64.1.0.0.nupkg
    • Beispiel: mytool.linux-x64.1.0.0.nupkg
    • Beispiel: mytool.osx-arm64.1.0.0.nupkg
  • Ein RID-agnostisches Zeigerpaket: <packageName>.<packageVersion>.nupkg
    • Beispiel: mytool.1.0.0.nupkg

AOT-Tools

Für Tools mit AOT-Kompilierung (<PublishAot>true</PublishAot>) müssen Sie für jede Plattform separat packen.

Plattformanforderungen für native AOT

Für die native AOT-Kompilierung muss der Betriebssystemteil des SDK-RID mit dem Betriebssystem des Ziel-RID übereinstimmen. Das SDK kann für verschiedene Architekturen (z. B. von x64 zu ARM64) cross-kompiliert werden, jedoch nicht über verschiedene Betriebssysteme hinweg (z. B. von Windows zu Linux).

Dies bedeutet, dass Sie mehrere Optionen zum Erstellen nativer AOT-Pakete haben:

  • Erstellen Sie nur für Ihren Entwicklungscomputer: Unterstützen Sie native AOT nur für das Betriebssystem, auf dem Sie entwickeln.
  • Verwenden Sie Container für Linux-Builds: Wenn Sie unter macOS oder Windows arbeiten, verwenden Sie Container zum kompilieren für Linux. Verwenden Sie beispielsweise mcr.microsoft.com/dotnet/sdk:10.0-noble-aot Container-Images.
  • Verbinden Sie Ihren Build auf verschiedenen Computern: Verwenden Sie CI/CD-Systeme wie GitHub-Aktionen oder Azure DevOps-Pipelines, um auf verschiedenen Betriebssystemen aufzubauen.

Sie müssen nicht alle RID-spezifischen Pakete auf demselben Computer oder gleichzeitig erstellen. Sie müssen sie nur erstellen und veröffentlichen, bevor Sie das Paket auf oberster Ebene veröffentlichen.

Verpacken von nativen AOT-Tools

Packen Sie das Top-Level-Paket einmal (auf einer beliebigen Plattform):

dotnet pack

Erstellen Sie für jede spezifische RID ein Paket auf der entsprechenden Plattform, z. B.:

dotnet pack -r linux-x64

Sie müssen jeden RID-spezifischen Packbefehl auf einer Plattform ausführen, auf der das Betriebssystem dem Ziel-RID entspricht. Weitere Informationen zu den Voraussetzungen für die native AOT-Kompilierung finden Sie in der nativen AOT-Bereitstellung.

Wenn Sie PublishAot auf true einstellen, ändert sich das Packverhalten:

  • dotnet pack erzeugt das Zeigerpaket der obersten Ebene (Pakettyp DotnetTool).
  • RID-spezifische AOT-Pakete werden nur erstellt, wenn Sie explizit -r <RID> übergeben, z. B. dotnet pack -r linux-x64 oder dotnet pack -r osx-arm64.

Hybrid-AOT + CoreCLR-Verpackungsmuster (Beispiel)

Einige Tools wollen das Beste aus beiden Welten:

  • Native AOT für eine Teilmenge von Plattformen mit hoher Priorität (abhängig vom Tool).
  • Ein portabler CoreCLR-Fallback , der auf Plattformen funktioniert, die nicht auf native AOT-Builds ausgerichtet sind.

Sie können dieses "Hybrid"-Modell mit dem folgenden Muster erreichen:

  1. Konfigurieren Sie das Tool für systemeigene AOT und toolspezifische RIDs.

    Verwenden Sie ToolPackageRuntimeIdentifiers und aktivieren Sie PublishAot in Ihrer Projektdatei.

    Beispiel:

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

  2. Erstellen Sie das Zeigerpaket.

    Führen Sie dotnet pack einmal (auf einer beliebigen Plattform) aus, um das Paket der obersten Ebene zu erstellen, das auf die RID-spezifischen Pakete verweist:

    dotnet pack

  3. Erstellen Sie native AOT-Pakete für ausgewählte RIDs.

    Für die native AOT-Kompilierung ist die Erstellung auf der Zielplattform erforderlich. Erstellen Sie jedes AOT-fähige RID-Paket auf der entsprechenden Plattform mithilfe von dotnet pack -r <RID>.

Beispiel:

dotnet pack -r linux-x64

  1. Erstellen Sie ein CoreCLR-Fallbackpaket.

    Um einen universellen Fallback bereitzustellen, packen Sie das any RID ohne AOT:

    dotnet pack -r any -p:PublishAot=false

    Dies erzeugt ein tragbares CoreCLR-Paket (z. B yourtool.any.<version>.nupkg. ), das auf Plattformen ausgeführt werden kann, die keinen dedizierten AOT-Build besitzen.

Hinweis

Sie können auch die .NET SDK 10.0-noble-aot Containerimages verwenden, um Linux Native AOT-Tools von jedem Host zu erstellen und zu verpacken, der Linux-Container unterstützt. Beispiel:

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

Dies ist nützlich, wenn Ihr Entwicklungscomputer Linux nicht nativ ausführt.

In diesem hybriden Setup:

  • Das Zeigerpaket (yourtool.<version>.nupkg) verweist auf beide:
    • RID-spezifische native AOT-Pakete (z. B. yourtool.osx-arm64, yourtool.linux-x64).
    • Das any CoreCLR-Paket als Fallback.
  • Die .NET CLI wählt automatisch das am besten geeignete Paket für die Plattform des Benutzers aus, wenn dotnet tool install oder dnx ausgeführt werden.

Beispiel: dotnet10-hybrid-tool

Das dotnet10-hybrid-tool-Repository veranschaulicht dieses Hybridpaketmuster mit nativen AOT-Paketen für osx-arm64, linux-arm64 und linux-x64 sowie ein CoreCLR-Fallbackpaket für das any-RID (zum Beispiel auf Windows, wenn kein AOT-Build verfügbar ist).

Sie können das Tool selbst installieren und ausprobieren:

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

Das Tool meldet seine Laufzeitframeworkbeschreibung, Laufzeit-ID (RID) und kompilierungsmodus (Native AOT oder CoreCLR).

Beispielausgabe auf einer Plattform mit nativem AOT:

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

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

Beispielausgabe auf einer Plattform unter Verwendung des CoreCLR-Fallbacks:

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

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

Auf diese Weise können Sie mit RID-spezifischen, AOT-kompilierten Tools und dem CoreCLR-Fallbackverhalten experimentieren.

Veröffentlichen Ihres Tools

Beim Veröffentlichen von RID-spezifischen Toolpaketen verwendet die .NET CLI die Versionsnummer des Pakets der obersten Ebene, um die übereinstimmenden RID-spezifischen Pakete auszuwählen. Dies bedeutet:

  • Alle RID-spezifischen Pakete müssen die gleiche Version wie das Paket auf oberster Ebene aufweisen.
  • Alle Pakete müssen in Ihrem Feed veröffentlicht werden, bevor das Paket der obersten Ebene verfügbar wird.

So stellen Sie einen reibungslosen Veröffentlichungsprozess sicher:

  1. Veröffentlichen Sie zuerst alle RID-spezifischen Pakete:

    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. Veröffentlichen Sie das Paket auf oberster Ebene zuletzt:

    dotnet nuget push yourtool.1.0.0.nupkg

Durch das Veröffentlichen des Pakets auf oberster Ebene wird sichergestellt, dass alle referenzierten RID-spezifischen Pakete verfügbar sind, wenn Benutzer Ihr Tool installieren. Wenn ein Benutzer Ihr Tool installiert, bevor alle RID-Pakete veröffentlicht werden, schlägt die Installation fehl.

Installieren und Ausführen von Tools

Ob ein Tool RID-spezifische Verpackungen verwendet, ist ein Implementierungsdetail, das für Benutzer transparent ist. Sie installieren und führen Tools auf die gleiche Weise aus, unabhängig davon, ob sich der Toolentwickler für RID-spezifische Verpackungen entschieden hat.

So installieren Sie ein Tool global:

dotnet tool install -g mytool

Nach der Installation können Sie sie direkt aufrufen:

mytool

Sie können auch das dnx Hilfsprogramm verwenden, das sich im Node.js Ökosystem ähnlich npx verhält: Es lädt ein Tool in einer einzigen Geste herunter und startet es, wenn es noch nicht vorhanden ist:

dnx mytool

Wenn ein Tool RID-spezifische Verpackungen verwendet, wählt die .NET CLI automatisch das richtige Paket für Ihre Plattform aus. Sie müssen kein RID angeben– die CLI leitet sie von Ihrem System ab und lädt das entsprechende RID-spezifische Paket herunter.

Siehe auch

  • Last updated on