Vytvoření balíčku NuGet pomocí rozhraní příkazového řádku dotnet

  • Článek

Balíčky NuGet obsahují kód, který můžou vývojáři ve svých projektech opakovaně používat. Bez ohledu na to, co váš kód dělá nebo obsahuje, použijete k vytvoření balíčku NuGet nástroj příkazového řádku nebo nuget.exedotnet.exe.

Tento článek popisuje, jak vytvořit balíček pomocí rozhraní příkazového řádku dotnet. Počínaje sadou Visual Studio 2017 je rozhraní příkazového řádku dotnet součástí všech úloh .NET a .NET Core. Pokud potřebujete nainstalovat rozhraní příkazového řádku dotnet nebo jiné klientské nástroje NuGet, přečtěte si téma Instalace klientských nástrojů NuGet.

Toto téma platí jenom pro .NET a další projekty, které používají formát ve stylu sady SDK. V těchto projektech nuGet k vytvoření balíčku používá informace ze souboru projektu. Kurzy pro rychlý start najdete v tématu Vytváření balíčků pomocí rozhraní příkazového řádku dotnet nebo vytváření balíčků pomocí sady Visual Studio.

Příkaz MSBuild msbuild -t:pack je funkčně ekvivalentní sadě dotnet pack. Další informace o vytvoření balíčku pomocí nástroje MSBuild naleznete v tématu Vytvoření balíčku NuGet pomocí nástroje MSBuild.

Poznámka:

Nastavení vlastností

Pomocí příkazu můžete vytvořit ukázkový projekt dotnet new classlib knihovny tříd a zabalit projekt pomocí dotnet pack. Příkaz dotnet pack používá následující vlastnosti. Pokud v souboru projektu nezadáte hodnoty, použije příkaz výchozí hodnoty.

  • PackageId, identifikátor balíčku musí být jedinečný napříč nuget.org a všemi dalšími cíli, které hostují balíček. Pokud nezadáte hodnotu, použije příkaz AssemblyName.
  • Version je konkrétní číslo verze ve formuláři Major.Minor.Patch[-Suffix], kde -Suffix identifikuje předběžné verze. Pokud není zadána, je výchozí hodnota 1.0.0.
  • Authors jsou autoři balíčku. Pokud není zadána, výchozí hodnota je AssemblyName.
  • Company jsou informace o společnosti. Pokud není zadána, výchozí hodnota je Authors hodnota.
  • Product jsou informace o produktu. Pokud není zadána, výchozí hodnota je AssemblyName.

V sadě Visual Studio můžete tyto hodnoty nastavit ve vlastnostech projektu. Klikněte pravým tlačítkem myši na projekt v Průzkumník řešení, vyberte Vlastnosti a pak vyberte oddíl Balíček. Vlastnosti můžete přidat také přímo do souboru .csproj nebo jiného projektu.

Následující příklad ukazuje soubor projektu s přidanými vlastnostmi balíčku.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

Můžete přidat další volitelné vlastnosti, například Title, PackageDescriptiona PackageTags.

Poznámka:

U balíčků, které vytváříte pro veřejnou spotřebu, věnujte zvláštní pozornost vlastnosti PackageTags . Značky pomáhají ostatním najít váš balíček a pochopit, co to dělá.

Příkaz dotnet pack automaticky převede PackageReferencesoubory projektu na závislosti v vytvořeném balíčku. Můžete řídit, které prostředky mají být zahrnuty prostřednictvím IncludeAssetsExcludeAssets a PrivateAssets značek. Další informace naleznete v tématu Řízení prostředků závislostí.

Další informace o závislostech, volitelných vlastnostech a správě verzí najdete tady:

Zvolte jedinečný identifikátor balíčku a nastavte číslo verze.

Identifikátor balíčku a číslo verze jednoznačně identifikují přesný kód obsažený v balíčku.

Pokud chcete vytvořit identifikátor balíčku, postupujte podle těchto osvědčených postupů:

  • Identifikátor musí být jedinečný napříč nuget.org a všemi ostatními umístěními, která hostují balíček. Aby nedocházelo ke konfliktům, dobrým vzorem je použít název vaší společnosti jako první část identifikátoru.

  • Postupujte podle konvence vytváření názvů podobných oboru názvů .NET pomocí zápisu tečky. Použijte například Contoso.Utility.UsefulStuff místo Contoso-Utility-UsefulStuff nebo Contoso_Utility_UsefulStuff. Je také užitečné pro uživatele, pokud odpovídá identifikátoru balíčku s oborem názvů, který kód používá.

  • Pokud vytvoříte balíček vzorového kódu , který ukazuje, jak použít jiný balíček, připojte .Sample k identifikátoru, jako v Contoso.Utility.UsefulStuff.Sample.

    Ukázkový balíček má závislost na původním balíčku. Při vytváření ukázkového balíčku přidejte <IncludeAssets> hodnotu contentFiles . Ve složce obsahu uspořádejte vzorový kód do složky s názvem \Samples\<identifier>, například \Samples\Contoso.Utility.UsefulStuff.Sample.

Pokud chcete nastavit verzi balíčku, postupujte podle těchto osvědčených postupů:

  • Obecně platí, že verze balíčku odpovídá verzi projektu nebo sestavení, i když to není nezbytně nutné. Porovnávání verze je jednoduché, když omezíte balíček na jedno sestavení. NuGet se zabývá verzemi balíčků při překladu závislostí, nikoli verzí sestavení.

  • Pokud používáte nestandardní schéma verzí, nezapomeňte zvážit pravidla správy verzí NuGet, jak je vysvětleno ve správě verzí balíčků. NuGet je většinou sémantická správa verzí kompatibilní s 2.0.0.

Poznámka:

Další informace o řešení závislostí najdete v tématu Řešení závislostí pomocí PackageReference. Informace, které vám můžou pomoct pochopit správu verzí, najdete v této sérii blogových příspěvků:

Přidání volitelného pole popisu

Volitelný popis balíčku se zobrazí na kartě README na stránce nuget.org balíčku. Popis se stáhne ze <Description> souboru projektu nebo $description ze souboru .nuspec.

Následující příklad ukazuje Description v souboru .csproj pro balíček .NET:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Spuštění příkazu pack

Chcete-li sestavit balíček NuGet nebo soubor .nupkg , spusťte příkaz dotnet pack ze složky projektu, která také automaticky sestaví projekt.

dotnet pack

Výstup ukazuje cestu k souboru .nupkg :

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Automatické generování balíčku při sestavení

Pokud chcete automaticky spustit dotnet pack při každém spuštění dotnet build, přidejte do souboru projektu do značky <PropertyGroup> následující řádek:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Poznámka:

Při automatickém vygenerování balíčku se doba sestavení projektu zvýší.

Spuštění dotnet pack v balíčku řešení všechny projekty v řešení, které jsou sbalitelné, to znamená, mají vlastnost nastavena IsPackable na true.

Instalace testovacího balíčku

Před publikováním balíčku byste měli otestovat instalaci balíčku do projektu. Testování zajišťuje, aby potřebné soubory skončily na jejich správných místech v projektu.

Otestujte instalaci ručně v sadě Visual Studio nebo na příkazovém řádku pomocí normálního procesu instalace balíčku.

Důležité

  • Balíčky nelze po vytvoření změnit. Pokud problém opravíte, změňte obsah balíčku a znovu ho zabalte.

  • Po opětovném vytvoření balíčku bude opětovné otestování stále používat starou verzi balíčku, dokud nesmazáte složku globálních balíčků. Vymazání složky je zvlášť důležité pro balíčky, které v každém sestavení nepoužívají jedinečný popisek předběžné verze.

Další kroky

Jakmile balíček vytvoříte, můžete soubor .nupkg publikovat na hostitele podle svého výběru.

Publikování balíčku

V následujících článcích najdete způsoby, jak rozšířit možnosti balíčku nebo podporovat jiné scénáře: