Tworzenie pakietu NuGet przy użyciu programu MSBuild

  • Artykuł

Podczas tworzenia pakietu NuGet na podstawie kodu należy spakować te funkcje do składnika, który może być udostępniany i używany przez dowolną liczbę innych deweloperów. W tym artykule opisano sposób tworzenia pakietu przy użyciu programu MSBuild. Program MSBuild jest wstępnie zainstalowany z każdym obciążeniem programu Visual Studio zawierającym pakiet NuGet. Ponadto możesz również użyć programu MSBuild za pośrednictwem interfejsu wiersza polecenia dotnet z platformą dotnet msbuild.

W przypadku projektów .NET Core i .NET Standard korzystających z formatu zestawu SDK oraz innych projektów w stylu zestawu SDK program NuGet używa informacji w pliku projektu bezpośrednio do utworzenia pakietu. W przypadku projektu w stylu innego niż ZESTAW SDK, który używa <PackageReference>programu , nuGet używa również pliku projektu do utworzenia pakietu.

Projekty w stylu zestawu SDK mają domyślnie dostępną funkcję pakietu. W przypadku projektów PackageReference w stylu innych niż SDK należy dodać pakiet NuGet.Build.Tasks.Pack do zależności projektu. Aby uzyskać szczegółowe informacje na temat obiektów docelowych pakietu MSBuild, zobacz Pakiet NuGet i przywracanie jako obiekty docelowe programu MSBuild.

Polecenie, które tworzy pakiet , msbuild -t:packjest funkcjonalnie równoważne .dotnet pack

Ważne

Ten temat dotyczy projektów w stylu zestawu SDK, zazwyczaj projektów .NET Core i .NET Standard oraz projektów innych niż zestaw SDK korzystających z funkcji PackageReference.

Ustawianie właściwości

Do utworzenia pakietu wymagane są następujące właściwości.

  • PackageId, identyfikator pakietu, który musi być unikatowy w całej galerii, która hostuje pakiet. Jeśli nie zostanie określony, wartość domyślna to AssemblyName.
  • Version, określony numer wersji w postaci Major.Minor.Patch[-Sufiks], gdzie -Sufiks identyfikuje wersje wstępne. Jeśli nie zostanie określona, wartość domyślna to 1.0.0.
  • Tytuł pakietu powinien być wyświetlany na hoście (na przykład nuget.org)
  • Authors, autor i informacje o właścicielu. Jeśli nie zostanie określony, wartość domyślna to AssemblyName.
  • Company, nazwa firmy. Jeśli nie zostanie określony, wartość domyślna to AssemblyName.

Ponadto w przypadku pakowania projektów innych niż zestaw SDK korzystających z funkcji PackageReference wymagane są następujące elementy:

  • PackageOutputPath, folder wyjściowy pakietu wygenerowanego podczas wywoływania pakietu.

W programie Visual Studio można ustawić te wartości we właściwościach projektu (kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań, wybierz pozycję Właściwości i wybierz kartę Pakiet). Te właściwości można również ustawić bezpośrednio w plikach projektu (csproj).

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

Ważne

Nadaj pakietowi identyfikator unikatowy dla nuget.org lub dowolnego źródła pakietu, którego używasz.

W poniższym przykładzie przedstawiono prosty, kompletny plik projektu z dołączonymi tymi właściwościami.

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

Można również ustawić opcjonalne właściwości, takie jak Title, PackageDescriptioni PackageTags, zgodnie z opisem w temacie Cele pakietu MSBuild, Kontrolowanie zasobów zależności i właściwości metadanych NuGet.

Uwaga

W przypadku pakietów utworzonych do użytku publicznego należy zwrócić szczególną uwagę na właściwość PackageTags , ponieważ tagi pomagają innym osobom znaleźć pakiet i zrozumieć, co robi.

Aby uzyskać szczegółowe informacje na temat deklarowania zależności i określania numerów wersji, zobacz Odwołania do pakietów w plikach projektu i Przechowywanie wersji pakietu. Istnieje również możliwość uwidomieniania zasobów z zależności bezpośrednio w pakiecie przy użyciu <IncludeAssets> atrybutów i <ExcludeAssets> . Aby uzyskać więcej informacji, zobacz Kontrolowanie zasobów zależności.

Dodawanie opcjonalnego pola opisu

Opcjonalny opis pakietu jest wyświetlany na karcie README strony nuget.org pakietu. Opis pobiera się z <Description> pliku projektu lub $description pliku w pliku nuspec.

W poniższym przykładzie pokazano Description element w pliku csproj dla pakietu .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>

Wybierz unikatowy identyfikator pakietu i ustaw numer wersji

Identyfikator pakietu i numer wersji jednoznacznie identyfikują dokładny kod zawarty w pakiecie.

Postępuj zgodnie z poniższymi najlepszymi rozwiązaniami, aby utworzyć identyfikator pakietu:

  • Identyfikator musi być unikatowy w nuget.org i wszystkich innych lokalizacjach hostujących pakiet. Aby uniknąć konfliktów, dobrym wzorcem jest użycie nazwy firmy jako pierwszej części identyfikatora.

  • Postępuj zgodnie z konwencją nazewnictwa przypominającą przestrzeń nazw platformy .NET, używając notacji kropkowej. Na przykład użyj polecenia Contoso.Utility.UsefulStuff , a nie Contoso-Utility-UsefulStuff lub Contoso_Utility_UsefulStuff. Jest to również przydatne dla użytkowników, jeśli dopasujesz identyfikator pakietu do przestrzeni nazw używanej przez kod.

  • Jeśli utworzysz pakiet przykładowego kodu , który pokazuje, jak używać innego pakietu, dołącz .Sample go do identyfikatora, jak w pliku Contoso.Utility.UsefulStuff.Sample.

    Przykładowy pakiet ma zależność od oryginalnego pakietu. Podczas tworzenia przykładowego pakietu dodaj <IncludeAssets> wartość contentFiles . W folderze zawartości umieść przykładowy kod w folderze o nazwie \Samples\<identifier>, takim jak \Samples\Contoso.Utility.UsefulStuff.Sample.

Postępuj zgodnie z poniższymi najlepszymi rozwiązaniami, aby ustawić wersję pakietu:

  • Ogólnie rzecz biorąc, ustaw wersję pakietu tak, aby odpowiadała wersji projektu lub zestawu, chociaż nie jest to ściśle wymagane. Dopasowywanie wersji jest proste w przypadku ograniczenia pakietu do pojedynczego zestawu. Sam pakiet NuGet obsługuje wersje pakietów podczas rozpoznawania zależności, a nie wersji zestawów.

  • Jeśli używasz niestandardowego schematu wersji, pamiętaj, aby wziąć pod uwagę reguły przechowywania wersji NuGet, jak wyjaśniono w artykule Przechowywanie wersji pakietów. Pakiet NuGet jest głównie zgodny ze standardem Semantic Versioning 2.0.0.

Uwaga

Aby uzyskać więcej informacji na temat rozwiązywania zależności, zobacz Rozwiązywanie zależności za pomocą funkcji PackageReference. Aby uzyskać informacje pomocne w zrozumieniu wersji, zobacz tę serię wpisów w blogu:

Dodaj pakiet NuGet.Build.Tasks.Pack

Jeśli używasz programu MSBuild z projektem w stylu innych niż SDK i PackageReference, dodaj pakiet NuGet.Build.Tasks.Pack do projektu.

  1. Otwórz plik projektu i dodaj następujący kod po elemecie <PropertyGroup> :

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

    Uwaga

    Rozważ użycie najnowszej dostępnej wersji tego pakietu.

  2. Otwórz wiersz polecenia dewelopera (w polu Wyszukiwania wpisz Wiersz polecenia dla deweloperów).

    Zazwyczaj chcesz uruchomić wiersz polecenia dewelopera dla programu Visual Studio z menu Start , ponieważ zostanie on skonfigurowany ze wszystkimi niezbędnymi ścieżkami programu MSBuild.

  3. Przejdź do folderu zawierającego plik projektu i wpisz następujące polecenie, aby zainstalować pakiet NuGet.Build.Tasks.Pack.

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

    Upewnij się, że dane wyjściowe programu MSBuild wskazują, że kompilacja została ukończona pomyślnie.

Uruchom polecenie msbuild -t:pack

Aby skompilować pakiet NuGet ( .nupkg plik) z projektu, uruchom msbuild -t:pack polecenie , które również kompiluje projekt automatycznie:

W wierszu polecenia dewelopera dla programu Visual Studio wpisz następujące polecenie:

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

Dane wyjściowe zawierają ścieżkę .nupkg do pliku.

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

Automatyczne generowanie pakietu podczas kompilacji

Aby automatycznie uruchomić msbuild -t:pack podczas kompilowania lub przywracania projektu, dodaj następujący wiersz do pliku projektu w pliku <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Po uruchomieniu msbuild -t:pack rozwiązania program pakuje wszystkie projekty w rozwiązaniu, które można spakować (<IsPackable> właściwość jest ustawiona na truewartość ).

Uwaga

Po automatycznym wygenerowaniu pakietu czas do spakowania zwiększa czas kompilacji dla projektu.

Instalacja pakietu testowego

Przed opublikowaniem pakietu zazwyczaj chcesz przetestować proces instalowania pakietu w projekcie. Testy zapewniają, że wszystkie pliki muszą być przechowywane w odpowiednich miejscach w projekcie.

Instalacje można testować ręcznie w programie Visual Studio lub w wierszu polecenia przy użyciu zwykłych kroków instalacji pakietu.

Ważne

Pakiety są niezmienne. Jeśli usuniesz problem, zmień ponownie zawartość pakietu i pakietu, podczas ponownego testowania nadal będziesz używać starej wersji pakietu do momentu wyczyszczenia folderu pakietów globalnych. Jest to szczególnie istotne w przypadku testowania pakietów, które nie używają unikatowej etykiety wersji wstępnej w każdej kompilacji.

Następne kroki

Po utworzeniu pakietu, który jest plikiem .nupkg , możesz opublikować go w wybranej galerii zgodnie z opisem w temacie Publikowanie pakietu.

Możesz również rozszerzyć możliwości pakietu lub w inny sposób obsługiwać inne scenariusze, zgodnie z opisem w następujących tematach:

Na koniec istnieją dodatkowe typy pakietów, o których należy pamiętać: