RID-specifikus, önálló és AOT .NET-eszközök létrehozása

Ez a cikk a következő verziókra vonatkozik: ✔️ .NET SDK 10 és újabb verziók

Csomagolja a .NET-eszközöket adott platformokhoz és architektúrákhoz, hogy natív, gyors és levágott alkalmazásokat terjesszen. Ez a funkció megkönnyíti az optimalizált alkalmazások elosztását parancssori eszközökhöz, például MCP-kiszolgálókhoz vagy más platformspecifikus segédprogramokhoz.

Áttekintés

A .NET SDK 10-től kezdve létrehozhat olyan .NET-eszközöket, amelyek meghatározott operációsrendszer-környezeteket céloznak meg (amelyeket futtatókörnyezet-azonosítók (RID-k) képviselnek. Ezek az eszközök a következők lehetnek:

  • RID-specifikus: Adott operációs rendszerekhez és architektúrákhoz készült.
  • Önálló: Adja meg a .NET-futtatókörnyezetet, és ne igényeljen külön .NET-telepítést.
  • Natív AOT: Az idő előtti fordítás használata gyorsabb indításhoz és kisebb memóriaigényhez.

A felhasználók nem látnak különbséget az eszköz telepítésekor. A .NET CLI automatikusan kiválasztja és telepíti a platform számára legmegfelelőbb csomagot.

A RID-specifikus csomagolások alkalmazása

RID-specifikus eszköz létrehozásához konfigurálja a projektet az alábbi MSBuild tulajdonságok egyikével:

RuntimeIdentifiers tulajdonság

Az eszköz által támogatott platformok megadására használható 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 tulajdonság

Másik lehetőségként az eszközspecifikus RID-konfigurációt is használhatja 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>

Használjon pontosvesszővel tagolt, RID-értékeket tartalmazó listát. A futtatókörnyezet-azonosítók listáját a RID-katalógusban találja.

Keretrendszerfüggő verzió megadása

Amikor a RID-specifikus eszközcsomagolást választja, a .NET SDK önálló csomagokat hoz létre minden megadott RID-hez. Azonban elveszíti az alapértelmezett keretrendszerfüggő csomagolást, amely bármely platformon működik, és telepítve van a .NET-futtatókörnyezet.

Ha a RID-specifikus csomagok mellett egy keretrendszerfüggő verziót szeretne biztosítani, adja hozzá any a ToolPackageRuntimeIdentifiers listához:

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

Ez a konfiguráció öt csomagot hoz létre:

  • Egy legfelső szintű mutatócsomag, amely felsorolja az összes elérhető alcsomagot.
  • Három RID-specifikus csomag (win-x64, osx-arm64, linux-x64), amelyek önállóak és karcsúsítottak.
  • Egy rid-agnosztikus csomag (any), amely keretrendszerfüggő, és a .NET-futtatókörnyezet telepítését igényli.

Amikor a felhasználók telepítik az eszközt:

  • A win-x64, osx-arm64 vagy linux-x64 rendszereken az önálló, csökkentett csomagok letöltése és végrehajtása történik.
  • Bármely más operációs rendszeren vagy architektúrán a keretrendszertől függő any csomag lesz használatban.

Ez a megközelítés optimalizált, önálló bináris fájlokat biztosít a közös platformokhoz, miközben a keretrendszerfüggő tartalékon keresztül fenntartja a kevésbé gyakori platformokkal való kompatibilitást.

Mikor érdemes használni a RuntimeIdentifiers-t a ToolPackageRuntimeIdentifiers-vel szemben?

RuntimeIdentifiers és ToolPackageRuntimeIdentifiers az eszközt a RID-specifikus csomagolásra konfigurálják, de némileg eltérő célokat szolgálnak:

Használja a RuntimeIdentifiers-t, amikor:

  • Azt szeretné, hogy a projekt általában RID-specifikus alkalmazásokat hozzon létre és tegyen közzé (nem csak eszközként).
  • Ön elsősorban a CoreCLR-t (nem AOT) célozza, vagy azt a szokásos SDK-viselkedést szeretné használni, amelyben egyetlen csomag dotnet pack több RID-specifikus csomagot állít elő.
  • Lehetőség van feltételeket alkalmazni a RID-k egy részhalmazára, de továbbra is szeretne egy CoreCLR-alapú csomagot minden RID-hez.

Használja a ToolPackageRuntimeIdentifiers-t, amikor:

  • A RID-specifikus viselkedést csak az eszköz csomagolásához szeretné definiálni anélkül, hogy módosítaná a projekt más üzembe helyezési forgatókönyvekhez való buildelhetőségét.
  • Natív AOT-t használ, és tervezi, hogy RID-enként kézzel hozza létre az AOT bináris fájljaitdotnet pack -r <RID>.
  • Olyan hibrid modellt szeretne, amelyben egyes RID-k natív AOT-t kapnak, míg mások egy hordozható CoreCLR-implementációba kerülnek vissza.

Notes:

  • A felső szintű mutatócsomag az elérhető RID-specifikus csomagokat határozza meg. Ha megadja ToolPackageRuntimeIdentifiers, az határozza meg az eszköz RIDs; különben a RuntimeIdentifiers lesz használva.
  • ToolPackageRuntimeIdentifiers egyenlőnek kell lennie vagy részhalmazként kell szerepelnie a RuntimeIdentifiers belüli RID-ek között.
  • Amikor PublishAot=truea RID-specifikus csomagok csak akkor jönnek létre, ha egy adott RID-hez csomagol (például dotnet pack -r linux-x64).
  • A natív AOT-buildek (PublishAot=true) csak akkor támogatottak, ha a build operációs rendszere és a cél operációs rendszer egyezik.

Az eszköz csomagolása

A csomagolási folyamat attól függően változik, hogy AOT-fordítást használ-e. Ha NuGet-csomagot vagy .nupkg-fájlt szeretne létrehozni a projektből, futtassa a dotnet pack parancsot .

RID-specifikus és önálló eszközök

Futtasd dotnet pack egyszer:

dotnet pack

Ez a parancs több NuGet-csomagot hoz létre:

  • Egy csomag minden RID-hez: <packageName>.<RID>.<packageVersion>.nupkg
    • Példa: mytool.win-x64.1.0.0.nupkg
    • Példa: mytool.linux-x64.1.0.0.nupkg
    • Példa: mytool.osx-arm64.1.0.0.nupkg
  • Egy RID-agnosztikus mutatócsomag: <packageName>.<packageVersion>.nupkg
    • Példa: mytool.1.0.0.nupkg

AOT-eszközök

Az AOT-fordítással (<PublishAot>true</PublishAot>) rendelkező eszközöket minden platformhoz külön szükséges csomagolni.

A natív AOT platformkövetelményei

A natív AOT-fordításhoz az SDK RID operációs rendszer (OS) része szükséges, hogy megfeleljen a cél RID operációs rendszerének. Az SDK különböző architektúrákhoz képes keresztfordításra (például x64-ről ARM64-re), de nem más operációs rendszerek között (például Windowsról Linuxra).

Ez azt jelenti, hogy több lehetősége van natív AOT-csomagok létrehozására:

  • Csak a fejlesztői géphez való buildelés: A Natív AOT támogatása csak a fejleszteni kívánt operációs rendszerhez.
  • Konténerek használata Linux-buildekhez: Ha macOS vagy Windows rendszeren dolgozik, használjon konténereket a Linuxra való keresztfordításhoz. Használjon például mcr.microsoft.com/dotnet/sdk:10.0-noble-aot tárolórendszerképeket.
  • A buildek összevonása a gépek között: Ci/CD-rendszerek, például a GitHub Actions vagy az Azure DevOps Pipelines használata különböző operációs rendszerekre való buildeléshez.

Nem kell az összes RID-specifikus csomagot ugyanazon a gépen vagy egyszerre létrehoznia. A legfelső szintű csomag közzététele előtt csak létre kell hoznia és közzé kell tennie őket.

Natív AOT-eszközök csomagolása

Csomagolja be egyszer a legfelső szintű csomagot (bármely platformon):

dotnet pack

Csomagolja be az egyes RID-eket a megfelelő platformon, például:

dotnet pack -r linux-x64

Minden RID-specifikus csomagparancsot olyan platformon kell futtatnia, ahol az operációs rendszer megfelel a cél RID operációs rendszerének. Az előfeltételekről a Natív AOT-fordításhoz további információt a Natív AOT üzembe helyezés részben talál.

Amikor a PublishAottrue-ra van állítva, a csomagolási viselkedés megváltozik:

  • dotnet pack hozza létre a felső szintű mutatócsomagot (csomagtípus DotnetTool).
  • A RID-specifikus AOT-csomagok csak akkor jönnek létre, ha explicit módon megadja, például -r <RID>, dotnet pack -r linux-x64 vagy dotnet pack -r osx-arm64.

Hibrid AOT + CoreCLR csomagolási minta (példa)

Néhány eszköz mindkét világ legjobbját szeretné:

  • Natív AOT a magas prioritású platformok egy részhalmazához (az eszköztől függően).
  • Hordozható CoreCLR-tartalék, amely a natív AOT-buildek által nem célzott platformokon működik.

Ezt a "hibrid" modellt a következő mintával érheti el:

  1. Konfigurálja az eszközt natív AOT-hoz és eszközspecifikus RID-khez.

    A projektfájlban használja a ToolPackageRuntimeIdentifiers és engedélyezze PublishAot.

    Például:

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

  2. Hozza létre a mutatócsomagot.

    Futtassa dotnet pack egyszer (bármely platformon) a RID-specifikus csomagokra hivatkozó legfelső szintű csomagot:

    dotnet pack

  3. Natív AOT-csomagok létrehozása a kiválasztott RID-khez.

    A natív AOT-fordításhoz a fordítást a célplatformon kell elvégezni. Az egyes AOT-kompatibilis RID-csomagokat a megfelelő platformon hozhatja létre a következővel dotnet pack -r <RID>: .

Például:

dotnet pack -r linux-x64

  1. CoreCLR tartalék csomag létrehozása.

    Univerzális tartalék biztosításához csomagolja be a any RID-t AOT nélkül:

    dotnet pack -r any -p:PublishAot=false

    Ez létrehoz egy hordozható CoreCLR-csomagot (például yourtool.any.<version>.nupkg), amely dedikált AOT-buildel nem rendelkező platformokon futtatható.

Megjegyzés:

A tárolórendszerképek .NET SDK 10.0-noble-aot használatával linuxos natív AOT-eszközöket hozhat létre és csomagolhat be bármely gazdagépen, amely támogatja a Linux-tárolókat. Például:

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

Ez akkor hasznos, ha a fejlesztői gép natív módon nem fut Linuxon.

Ebben a hibrid beállításban:

  • A mutatócsomag (yourtool.<version>.nupkg) mindkettőre hivatkozik:
    • RID-specifikus natív AOT-csomagok (például yourtool.osx-arm64, yourtool.linux-x64).
    • A any CoreCLR-csomag tartalékként.
  • A .NET CLI automatikusan kiválasztja a felhasználó platformjának legmegfelelőbb csomagot, amikor a dotnet tool install vagy dnx parancsot futtatják.

Példa: dotnet10-hybrid-tool

Az dotnet10-hybrid-tool adattár ezt a hibrid csomagolási mintát mutatja be natív AOT-csomagokkal a RID-hezosx-arm64linux-arm64, linux-x64valamint anyegy CoreCLR tartalék csomaggal (például Windows rendszeren, ha nem érhető el AOT-build).

Az eszközt saját maga is telepítheti és kipróbálhatja:

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

Az eszköz a futtatókörnyezet keretrendszerének leírását, a futtatókörnyezet azonosítóját (RID) és a fordítási módot (natív AOT vagy CoreCLR) jelenti.

Példakimenet natív AOT-t tartalmazó platformon:

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

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

Példakimenet egy platformon a CoreCLR tartalék használatával:

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

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

Ez hasznos módszer a RID-specifikus, AOT-kompatibilis eszközökkel és a CoreCLR tartalék működésével való kísérletezéshez.

Az eszköz közzététele

A RID-specifikus eszközcsomagok közzétételekor a .NET CLI a legfelső szintű csomag verziószámával választja ki az egyező RID-specifikus csomagokat. Ez a következőt jelenti:

  • Minden RID-specifikus csomagnak pontosan ugyanazzal a verzióval kell rendelkeznie, mint a legfelső szintű csomagnak.
  • Az összes csomagot közzé kell tenni a hírcsatornában, mielőtt a legfelső szintű csomag elérhetővé válik.

Zökkenőmentes közzétételi folyamat biztosítása:

  1. Először tegye közzé az összes RID-specifikus csomagot:

    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. A legfelső szintű csomagot tegyük fel utoljára.

    dotnet nuget push yourtool.1.0.0.nupkg

A legfelső szintű csomag legutóbbi közzététele biztosítja, hogy az eszköz telepítésekor minden hivatkozott RID-specifikus csomag elérhető lesz. Ha egy felhasználó az összes RID-csomag közzététele előtt telepíti az eszközt, a telepítés sikertelen lesz.

Eszközök telepítése és futtatása

Az, hogy egy eszköz RID-specifikus csomagolást használ-e, az a felhasználók számára átlátható megvalósítási részlet. Ugyanúgy telepíthet és futtathat eszközöket, függetlenül attól, hogy az eszköz fejlesztője a RID-specifikus csomagolást választotta-e.

Eszköz globális telepítése:

dotnet tool install -g mytool

A telepítés után közvetlenül meghívhatja:

mytool

Használhatja a dnx segítőt is, amely a Node.js ökoszisztémájához npx hasonlóan viselkedik: letölti és elindít egy eszközt egyetlen kézmozdulatban, ha még nincs jelen:

dnx mytool

Ha egy eszköz RID-specifikus csomagolást használ, a .NET CLI automatikusan kiválasztja a platformhoz megfelelő csomagot. Nem kell megadnia egy RID-et – a parancssori felület a rendszerből következtet, és letölti a megfelelő RID-specifikus csomagot.

Lásd még

  • Last updated on