Vytvoření balíčku NuGet pomocí nástroje MSBuild

  • Článek

Když z kódu vytvoříte balíček NuGet, zabalíte tuto funkci do komponenty, se kterou se dá sdílet a používat libovolný počet dalších vývojářů. Tento článek popisuje, jak vytvořit balíček pomocí nástroje MSBuild. Nástroj MSBuild je předinstalovaný se každou úlohou sady Visual Studio, která obsahuje NuGet. Kromě toho můžete msBuild použít také prostřednictvím rozhraní příkazového řádku dotnet s nástrojem dotnet msbuild.

Pro projekty .NET Core a .NET Standard, které používají formát sady SDK a všechny ostatní projekty ve stylu sady SDK, nuGet používá informace v souboru projektu přímo k vytvoření balíčku. Pro projekt, který nepoužívá sadu SDK, který používá <PackageReference>, NuGet také používá soubor projektu k vytvoření balíčku.

Projekty ve stylu sady SDK mají ve výchozím nastavení k dispozici funkce balíčku. Pro projekty PackageReference ve stylu sady SDK je potřeba do závislostí projektu přidat balíček NuGet.Build.Tasks.Pack. Podrobné informace ocílech

Příkaz, který vytvoří balíček , msbuild -t:packje funkčně ekvivalentní dotnet pack.

Důležité

Toto téma se týká projektů ve stylu sady SDK, obvykle projektů .NET Core a .NET Standard a projektů jiných než SDK, které používají PackageReference.

Nastavení vlastností

K vytvoření balíčku jsou vyžadovány následující vlastnosti.

  • PackageId, identifikátor balíčku, který musí být jedinečný v galerii, která je hostitelem balíčku. Pokud není zadána, je výchozí hodnota AssemblyName.
  • Version, konkrétní číslo verze ve formátu Major.Minor.Patch[-Suffix] kde -Suffix identifikuje předběžné verze. Pokud není zadána, výchozí hodnota je 1.0.0.
  • Název balíčku, který by se měl zobrazovat na hostiteli (například nuget.org)
  • Authors, informace o autorovi a vlastníkovi. Pokud není zadána, je výchozí hodnota AssemblyName.
  • Company, název vaší společnosti. Pokud není zadána, je výchozí hodnota AssemblyName.

Pokud navíc balíte projekty, které nepoužívají sadu SDK, které používají PackageReference, vyžaduje se toto:

  • PackageOutputPath, výstupní složka balíčku vygenerovaná při volání balíčku.

V sadě Visual Studio můžete tyto hodnoty nastavit ve vlastnostech projektu (klikněte pravým tlačítkem na projekt v Průzkumník řešení, zvolte Vlastnosti a vyberte kartu Balíček). Tyto vlastnosti můžete také nastavit přímo v souborech projektu (.csproj).

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Důležité

Dejte balíčku jedinečný identifikátor pro nuget.org nebo jakýkoli zdroj balíčku, který používáte.

Následující příklad ukazuje jednoduchý kompletní projektový soubor s těmito vlastnostmi.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

Můžete také nastavit volitelné vlastnosti, například Title, PackageDescriptiona PackageTags, jak je popsáno v cílech sady MSBuild, řízení prostředků závislostí a vlastnosti metadat NuGet.

Poznámka:

U balíčků vytvořených pro veřejnou spotřebu věnujte zvláštní pozornost vlastnosti PackageTags, protože značky pomáhají ostatním najít váš balíček a pochopit, co dělá.

Podrobnosti o deklarování závislostí a zadávání čísel verzí naleznete v tématu Odkazy na balíčky v souborech projektu a správa verzí balíčků. Prostředky je také možné zpřístupněte přímo v balíčku pomocí <IncludeAssets> atributů a <ExcludeAssets> atributů. Další informace naleznete v tématu Řízení prostředků závislostí.

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>

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í balíčku NuGet.Build.Tasks.Pack

Pokud používáte NÁSTROJ MSBuild s projektem bez sady SDK a PackageReference, přidejte do projektu balíček NuGet.Build.Tasks.Pack.

  1. Otevřete soubor projektu a za element přidejte následující <PropertyGroup> :

    <ItemGroup>
  <!-- ... -->
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.7.0" PrivateAssets="all" />
  <!-- ... -->
</ItemGroup>

    Poznámka:

    Zvažte použití nejnovější dostupné verze tohoto balíčku.

  2. Otevřete příkazový řádek Pro vývojáře (do vyhledávacího pole zadejte Příkazový řádek pro vývojáře).

    Obvykle chcete spustit příkazový řádek pro vývojáře pro Visual Studio z nabídky Start , protože bude nakonfigurován se všemi potřebnými cestami pro NÁSTROJ MSBuild.

  3. Přepněte do složky obsahující soubor projektu a zadáním následujícího příkazu nainstalujte balíček NuGet.Build.Tasks.Pack.

    # Uses the project file in the current folder by default
msbuild -t:restore

    Ujistěte se, že výstup NÁSTROJE MSBuild označuje, že sestavení bylo úspěšně dokončeno.

Spuštění příkazu msbuild -t:pack

Pokud chcete sestavit balíček NuGet ( .nupkg soubor) z projektu, spusťte msbuild -t:pack příkaz, který také automaticky sestaví projekt:

Do příkazového řádku Vývojář pro Visual Studio zadejte následující příkaz:

# Uses the project file in the current folder by default
msbuild -t:pack

Výstup ukazuje cestu k .nupkg souboru.

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

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

Pokud chcete automaticky spustit msbuild -t:pack při sestavování nebo obnovování projektu, přidejte do souboru projektu následující řádek:<PropertyGroup>

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Při spuštění msbuild -t:pack v řešení se tím zabalí všechny projekty v řešení, které jsou packable (<IsPackable> vlastnost je nastavena na true).

Poznámka:

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

Instalace testovacího balíčku

Před publikováním balíčku obvykle chcete otestovat proces instalace balíčku do projektu. Testy zajišťují, aby všechny soubory nutně skončily na jejich správných místech v projektu.

Instalace můžete testovat ručně v sadě Visual Studio nebo na příkazovém řádku pomocí běžných kroků instalace balíčku.

Důležité

Balíčky jsou neměnné. Pokud problém opravíte, znovu změňte obsah balíčku a balíčku, až budete znovu testovat, budete nadále používat starou verzi balíčku, dokud nesmazáte globální složku balíčků . To je zvlášť důležité při testování balíčků, které nepoužívají jedinečný popisek předběžné verze pro každé sestavení.

Další kroky

Jakmile vytvoříte balíček, což je .nupkg soubor, můžete ho publikovat do galerie podle svého výběru, jak je popsáno v tématu Publikování balíčku.

Můžete také chtít rozšířit možnosti balíčku nebo jinak podporovat další scénáře popsané v následujících tématech:

A konečně existují další typy balíčků, o které je potřeba vědět: