Udostępnij za pomocą

Tworzenie pakietu NuGet za pomocą interfejsu wiersza polecenia dotnet

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 nuget.exe lub dotnet.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.

Polecenie MSBuild msbuild -t:pack 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 / Notatka

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.
  • Version jest 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ślone, wartość domyślna to AssemblyName.
  • Company to informacje o firmie. Jeśli nie zostanie określona, wartość domyślna to wartość Authors.
  • Product to informacje o produkcie. Jeśli nie zostanie określony, wartością domyślną jest AssemblyName.

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, 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 / Notatka

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

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 ExcludeAssets . PrivateAssets 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 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:

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>

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 build, dodaj następujący wiersz do pliku projektu w tagu <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Uwaga / Notatka

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

Uruchomienie dotnet pack na rozwiązaniu spakuje wszystkie projekty w rozwiązaniu, które można spakować, czyli mają właściwość IsPackable ustawioną na true.

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.

Dalsze kroki

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

Opublikuj pakiet

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

  • Last updated on