Udostępnij za pośrednictwem

Tworzenie pakietu NuGet za pomocą interfejsu wiersza polecenia dotnet

  • Artykuł

Pakiety NuGet zawierają kod, którego deweloperzy mogą używać ponownie w swoich projektach. Niezależnie od tego, co robi lub zawiera kod, użyj narzędzia wiersza polecenia lub nuget.exedotnet.exe, aby utworzyć pakiet NuGet.

W tym artykule opisano sposób tworzenia pakietu przy użyciu interfejsu wiersza polecenia dotnet. Począwszy od programu Visual Studio 2017, interfejs wiersza polecenia dotnet jest dołączony do wszystkich obciążeń platformy .NET i platformy .NET Core. Jeśli musisz zainstalować interfejs wiersza polecenia dotnet lub inne narzędzia klienckie NuGet, zobacz Instalowanie narzędzi klienckich NuGet.

Ten temat dotyczy tylko platformy .NET i innych projektów korzystających z formatu w stylu zestawu SDK. W przypadku tych projektów nuGet używa informacji z pliku projektu do utworzenia pakietu. Aby zapoznać się z samouczkami szybkiego startu, zobacz Tworzenie pakietów przy użyciu interfejsu wiersza polecenia dotnet lub Tworzenie pakietów za pomocą programu Visual Studio.

MsBuild msbuild -t:pack polecenie jest funkcjonalnie równoważne dotnet pack. Aby uzyskać więcej informacji na temat tworzenia pakietu za pomocą programu MSBuild, zobacz Create a NuGet package using MSBuild (Tworzenie pakietu NuGet przy użyciu programu MSBuild).

Uwaga

Ustawianie właściwości

Przykładowy projekt biblioteki klas można utworzyć przy użyciu dotnet new classlib polecenia i spakować projekt przy użyciu polecenia dotnet pack. Polecenie dotnet pack używa następujących właściwości. Jeśli nie określisz wartości w pliku projektu, polecenie użyje wartości domyślnych.

  • PackageId, identyfikator pakietu musi być unikatowy w nuget.org i innych miejscach docelowych hostujących pakiet. Jeśli nie określisz wartości, polecenie użyje polecenia AssemblyName.
  • Versionjest określonym numerem wersji w formularzu Major.Minor.Patch[-Suffix], gdzie -Suffix identyfikuje wersje wstępne. Jeśli nie zostanie określony, wartość domyślna to 1.0.0.
  • Authors są autorami pakietu. Jeśli nie zostanie określony, wartość domyślna AssemblyNameto .
  • Company to informacje o firmie. Jeśli nie zostanie określony, wartość domyślna Authors to wartość .
  • Product to informacje o produkcie. Jeśli nie zostanie określony, wartość domyślna AssemblyNameto .

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, a następnie wybierz sekcję Pakiet. Właściwości można również dodać bezpośrednio do pliku csproj lub innego projektu.

Poniższy przykład przedstawia plik projektu z dodanymi właściwościami pakietu.

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

Możesz dodać inne opcjonalne właściwości, takie jak Title, PackageDescriptioni PackageTags.

Uwaga

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

Polecenie dotnet pack automatycznie konwertuje PackageReferencepliki projektu na zależności w utworzonym pakiecie. Możesz kontrolować, które zasoby mają być uwzględniane za pomocą tagów IncludeAssetsi PrivateAssets . ExcludeAssets Aby uzyskać więcej informacji, zobacz Kontrolowanie zasobów zależności.

Aby uzyskać więcej informacji na temat zależności, właściwości opcjonalnych i przechowywania wersji, zobacz:

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:

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>

Uruchamianie polecenia pakietu

Aby skompilować pakiet NuGet lub plik nupkg , uruchom polecenie dotnet pack z folderu projektu, który również kompiluje projekt automatycznie.

dotnet pack

Dane wyjściowe zawierają ścieżkę do pliku 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'.

Automatyczne generowanie pakietu podczas kompilacji

Aby automatycznie uruchomić dotnet pack przy każdym uruchomieniu dotnet buildpolecenia , dodaj następujący wiersz do pliku projektu w tagu <PropertyGroup> :

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Uwaga

Po automatycznym wygenerowaniu pakietu pakowanie zwiększa czas kompilacji projektu.

Uruchomione dotnet pack w pakiecie rozwiązania wszystkie projekty w rozwiązaniu, które można spakować, czyli mają właściwość ustawioną IsPackable na truewartość .

Instalacja pakietu testowego

Przed opublikowaniem pakietu należy przetestować zainstalowanie pakietu w projekcie. Testowanie gwarantuje, że niezbędne pliki trafią do odpowiednich miejsc w projekcie.

Przetestuj instalację ręcznie w programie Visual Studio lub w wierszu polecenia przy użyciu normalnego procesu instalacji pakietu.

Ważne

  • Nie można zmienić pakietów po utworzeniu. Jeśli rozwiązasz problem, zmień zawartość pakietu i ponownie pakuj.

  • Po ponownym utworzeniu pakietu ponowne testowanie nadal używa starej wersji pakietu do momentu wyczyszczenia folderu pakietów globalnych. Wyczyszczenie folderu jest szczególnie ważne w przypadku pakietów, które nie używają unikatowej etykiety wersji wstępnej w każdej kompilacji.

Następne kroki

Po utworzeniu pakietu możesz opublikować plik nupkg na wybranym hoście.

Publikowanie pakietu

Zapoznaj się z następującymi artykułami, aby dowiedzieć się, jak rozszerzyć możliwości pakietu lub obsługiwać inne scenariusze: