NuGet

NuGet jest menedżerem pakietów dla ekosystemu platformy .NET i jest podstawowym sposobem odnajdywania i uzyskiwania bibliotek open source platformy .NET. NuGet.org, bezpłatna usługa oferowana przez firmę Microsoft do hostowania pakietów NuGet, jest hostem podstawowym publicznych pakietów NuGet, ale można publikować w niestandardowych usługach NuGet, takich jak MyGet i Azure Artifacts.

Tworzenie pakietu NuGet

Pakiet NuGet (*.nupkg) to plik zip zawierający zestawy .NET i skojarzone metadane.

Istnieją dwa główne sposoby tworzenia pakietu NuGet. Nowszym i zalecanym sposobem jest utworzenie pakietu na podstawie projektu w stylu zestawu SDK (pliku projektu, którego zawartość zaczyna się od <Project Sdk="Microsoft.NET.Sdk">). Zestawy i obiekty docelowe są automatycznie dodawane do pakietu, a pozostałe metadane są dodawane do pliku MSBuild, na przykład nazwa pakietu i numer wersji. Kompilowanie za dotnet pack pomocą polecenia generuje *.nupkg plik zamiast zestawów.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

Starszy sposób tworzenia pakietu NuGet dotyczy *.nuspec pliku i nuget.exe narzędzia wiersza polecenia. Plik nuspec zapewnia świetną kontrolę, ale należy dokładnie określić zestawy i obiekty docelowe, które mają zostać uwzględnione w ostatnim pakiecie NuGet. Łatwo jest popełnić błąd lub zapomnieć o aktualizacji nuspec podczas wprowadzania zmian. Zaletą narzędzia nuspec jest użycie go do tworzenia pakietów NuGet dla struktur, które nie obsługują jeszcze pliku projektu w stylu zestawu SDK.

✔️ ROZWAŻ użycie pliku projektu w stylu zestawu SDK w celu utworzenia pakietu NuGet.

Zależności pakietów

Zależności pakietów NuGet zostały szczegółowo omówione w artykule Zależności .

Ważne metadane pakietu NuGet

Pakiet NuGet obsługuje wiele właściwości metadanych. Poniższa tabela zawiera podstawowe metadane, które powinny zawierać każdy pakiet w NuGet.org:

Nazwa właściwości MSBuild	Nazwa narzędzia Nuspec	opis
PackageId	id	Identyfikator pakietu. Prefiks z identyfikatora może być zarezerwowany, jeśli spełnia kryteria.
PackageVersion	version	Wersja pakietu NuGet. Aby uzyskać więcej informacji, zobacz Wersja pakietu NuGet.
Title	title	Przyjazny dla człowieka tytuł pakietu. Wartość domyślna to PackageId.
Description	description	Długi opis pakietu wyświetlanego w interfejsie użytkownika.
Authors	authors	Rozdzielona przecinkami lista autorów pakietów zgodna z nazwami profilów w nuget.org.
PackageTags	tags	Spacja lub rozdzielana średnikami lista tagów i słów kluczowych opisujących pakiet. Tagi są używane podczas wyszukiwania pakietów.
PackageIcon	icon	Ścieżka do obrazu w pakiecie do użycia jako ikona pakietu. Przeczytaj więcej na temat icon metadanych.
PackageProjectUrl	projectUrl	Adres URL strony głównej projektu lub repozytorium źródłowego.
PackageLicenseExpression	license	Identyfikator SPDX licencji projektu. Tylko zatwierdzone licencje OSI i FSF mogą używać identyfikatora. Inne licencje powinny używać polecenia PackageLicenseFile. Przeczytaj więcej na temat license metadanych.

Ważne

Projekt bez licencji domyślnie do wyłącznego prawa autorskiego, co czyni go prawnie niemożliwe dla innych osób do wykorzystania.

✔️ ROZWAŻ wybranie nazwy pakietu NuGet z prefiksem spełniającym kryteria rezerwacji prefiksu NuGet.

✔️ Użyj skrótu HTTPS do ikony pakietu.

Witryny, takie jak NuGet.org uruchamiane z włączonym protokołem HTTPS, a wyświetlanie obrazu innego niż HTTPS spowoduje utworzenie ostrzeżenia o mieszanej zawartości.

✔️ Do użyj obrazu ikony pakietu, który jest 64x64 i ma przezroczyste tło, aby uzyskać najlepsze wyniki wyświetlania.

✔️ ROZWAŻ skonfigurowanie linkuźródłowego w celu dodania metadanych kontroli źródła do zestawów i pakietu NuGet.

Link źródłowy automatycznie dodaje RepositoryUrl metadane do RepositoryType pakietu NuGet. Link źródłowy dodaje również informacje o dokładnym kodzie źródłowym, z którego utworzono pakiet. Na przykład pakiet utworzony na podstawie repozytorium Git będzie miał dodany skrót zatwierdzenia jako metadane.

Pakiety wersji wstępnej

Pakiety NuGet z sufiksem wersji są uznawane za wersje wstępne. Domyślnie interfejs użytkownika Menedżer pakietów NuGet wyświetla stabilne wersje, chyba że użytkownik zdecyduje się na pakiety wersji wstępnej, co czyni pakiety wersji wstępnej idealnym rozwiązaniem do ograniczonego testowania użytkowników.

<PackageVersion>1.0.1-beta1</PackageVersion>

Uwaga

Stabilny pakiet nie może zależeć od pakietu wersji wstępnej. Musisz utworzyć własny pakiet w wersji wstępnej lub zależeć od starszej stabilnej wersji.

✔️ Czy opublikować pakiet wstępny podczas testowania, wyświetlania podglądu lub eksperymentowania.

✔️ Publikuj stabilny pakiet, gdy jest gotowy, aby inne stabilne pakiety mogły się do niego odwoływać.

Pakiety symboli

Pliki symboli (*.pdb) są tworzone przez kompilator .NET wraz z zestawami. Pliki symboli mapować lokalizacje wykonywania do oryginalnego kodu źródłowego, aby można było przejść przez kod źródłowy, ponieważ jest uruchomiony przy użyciu debugera. Pakiet NuGet obsługuje generowanie oddzielnego pakietu symboli (*.snupkg) zawierającego pliki symboli wraz z głównym pakietem zawierającym zestawy platformy .NET. Chodzi o to, że pakiety symboli są hostowane na serwerze symboli i są pobierane tylko przez narzędzie, takie jak Program Visual Studio na żądanie.

NuGet.org hostuje własne repozytorium serwerów symboli. Deweloperzy mogą używać symboli opublikowanych na serwerze symboli NuGet.org przez dodanie https://symbols.nuget.org/download/symbols ich do źródeł symboli w programie Visual Studio.

Ważne

Serwer symboli NuGet.org obsługuje tylko nowe przenośne pliki symboli (*.pdb) utworzone przez projekty w stylu zestawu SDK.

Aby użyć serwera symboli NuGet.org podczas debugowania biblioteki .NET, deweloperzy muszą mieć program Visual Studio 2017 w wersji 15.9 lub nowszej.

Alternatywą do utworzenia pakietu symboli jest osadzanie plików symboli w głównym pakiecie NuGet. Główny pakiet NuGet będzie większy, ale osadzone pliki symboli oznaczają, że deweloperzy nie muszą konfigurować serwera symboli NuGet.org. Jeśli tworzysz pakiet NuGet przy użyciu projektu w stylu zestawu SDK, możesz osadzić pliki symboli, ustawiając AllowedOutputExtensionsInPackageBuildOutputFolder właściwość:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

Wadą osadzania plików symboli jest zwiększenie rozmiaru pakietu o około 30% dla bibliotek platformy .NET skompilowanych przy użyciu projektów w stylu zestawu SDK. Jeśli rozmiar pakietu jest problemem, zamiast tego należy opublikować symbole w pakiecie symboli.

✔️ ROZWAŻ publikowanie symboli jako pakietu symboli (*.snupkg) w celu NuGet.org

Pakiety symboli (*.snupkg) zapewniają deweloperom dobre środowisko debugowania na żądanie bez wzdęcia głównego rozmiaru pakietu i wpływające na wydajność przywracania dla tych, którzy nie zamierzają debugować pakietu NuGet.

Zastrzeżeniem jest to, że użytkownicy mogą potrzebować znaleźć i skonfigurować serwer symboli NuGet w swoim środowisku IDE (jako konfiguracja jednorazowa), aby uzyskać pliki symboli. Program Visual Studio 2019 w wersji 16.1 dodał serwer symboli nuGet.org do listy domyślnych serwerów symboli.

PoprzedniNastępny