Udostępnij za pomocą

Tworzenie pakietu NuGet przy użyciu programu MSBuild

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ć MSBuild za pośrednictwem dotnet CLI z 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 typu nie-SDK, który używa <PackageReference>, NuGet także używa pliku projektu do utworzenia pakietu.

Projekty w stylu zestawu SDK mają domyślnie dostępną funkcję pakietu. W przypadku projektów w stylu innym niż SDK, PackageReference jest również domyślnie dostępne od Visual Studio 2026. We wcześniejszych wersjach programu Visual Studio należy dodać pakiet NuGet.Build.Tasks.Pack do zależności projektu i zalecamy usunięcie tego odwołania do pakietu podczas uaktualniania do programu Visual Studio 2026. Aby uzyskać szczegółowe informacje na temat obiektów docelowych pakietu MSBuild, zobacz Pakiet NuGet i przywracanie jako obiekty docelowe programu MSBuild.

W przypadku projektów w stylu zestawu SDK, msbuild -t:pack jest 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, jak powinien być przedstawiony 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 polecenia pack.

W programie Visual Studio można ustawić te wartości we właściwościach projektu (kliknij prawym przyciskiem myszy projekt w Eksploratorze 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 / Notatka

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ść wyświetlania zasobów z zależności bezpośrednio w pakiecie przy użyciu atrybutów <IncludeAssets> 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 na stronie nuget.org pakietu. Opis jest pobierany z <Description> pliku projektu lub $description w pliku .nuspec.

W poniższym przykładzie pokazano Description 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 Contoso.Utility.UsefulStuff zamiast 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, dodaj .Sample do identyfikatora, jak w Contoso.Utility.UsefulStuff.Sample.

    Przykładowy pakiet ma zależność od oryginalnego pakietu. Podczas tworzenia przykładowego pakietu dodaj <IncludeAssets> z wartością 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 / Notatka

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:

Konfigurowanie projektu dla pakietu

Projekty w stylu zestawu SDK nie wymagają żadnej dodatkowej konfiguracji.

Projekty, które nie są w stylu SDK, muszą mieć zainstalowany co najmniej jeden pakiet (poprzez PackageReference, a nie packages.config), albo projekt musi wyraźnie poinstruować NuGet, aby traktować projekt jako projekt PackageReference za pomocą właściwości RestoreProjectStyle.

Program Visual Studio 2022 i starsze wersje nie mają wbudowanego pakietu, dlatego należy również zainstalować pakiet NuGet.Build.Tasks.Pack. Podczas uaktualniania do programu Visual Studio 2026 lub nowszego zalecamy odinstalowanie pakietu, aby korzystać z nowych funkcji i poprawek błędów.

  1. Edytuj plik projektu.

    Jeśli chcesz jawnie poinstruować nuGet, aby traktować projekt jako PackageReference (projekt nie ma zainstalowanych pakietów), znajdź lub dodaj element <PropertyGroup> , który nie ma żadnej Condition instrukcji, i dodaj:

    <PropertyGroup>
  <!-- other properties -->
  <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
  <!-- more properties are allowed -->
</PropertyGroup>

    Jeśli używasz programu Visual Studio 2022 lub starszego, dodaj następujące polecenie po elemecie <PropertyGroup> :

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

    Uwaga / Notatka

    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 przywrócić 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ę do pliku .nupkg.

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>

Podczas uruchamiania msbuild -t:pack na rozwiązaniu, pakowane są wszystkie projekty w rozwiązaniu, które są pakowalne (<IsPackable> właściwość jest ustawiona na true).

Uwaga / Notatka

Po automatycznym wygenerowaniu pakietu czas potrzebny na spakowanie zwiększa czas kompilacji projektu.

Instalacja pakietu testowego

Przed opublikowaniem pakietu zazwyczaj chcesz przetestować proces instalowania pakietu w projekcie. Testy zapewniają, że wszystkie niezbędne pliki trafiają na właściwe miejsca 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ń zawartość pakietu i zapakuj ponownie, podczas ponownego testowania nadal będziesz używać starej wersji pakietu, dopóki nie wyczyścisz 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.

Dalsze 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ć:

  • Last updated on