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 pomocą polecenia dotnet pack zwraca plik *.nupkg 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 pliku *.nuspec i narzędzia wiersza polecenia nuget.exe. 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 są 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 wersję pakietu NuGet .
Title	title	Przyjazny dla człowieka tytuł pakietu. Domyślnie jest 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, który ma być użyty jako ikona pakietu. Przeczytaj więcej o metadanych icon.
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ć PackageLicenseFile. Przeczytaj więcej o license metadanych.

Ważny

Projekt bez licencji domyślnie posiada wyłączne prawa autorskie, co uniemożliwia prawnie jego wykorzystanie przez inne osoby.

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

✔️ Używaj odnośnika HTTPS dla ikony pakietu.

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

✔️ Należy użyć obrazu ikony pakietu o rozmiarze 64x64 z przezroczystym tłem, aby uzyskać najlepsze wyniki wyświetlania.

✔️ ROZWAŻ skonfigurowanie Source Link w celu dodania metadanych kontroli wersji do zestawów programistycznych i pakietu NuGet.

Link źródłowy automatycznie dodaje metadane RepositoryUrl i RepositoryType do 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 wersję przedprodukcyjną. Domyślnie interfejs użytkownika Menedżera pakietów NuGet wyświetla stabilne wersje, chyba że użytkownik zdecyduje się na pakiety w wersji wstępnej, co czyni pakiety wersji wstępnej idealnym rozwiązaniem do ograniczonego testowania użytkowników.

<PackageVersion>1.0.1-beta1</PackageVersion>

Notatka

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

✔️ Opublikuj pakiet w wersji wstępnej podczas testowania, 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 modułami. Pliki symboli przyporządkowują punkty wykonywania do oryginalnego kodu źródłowego, aby można było śledzić kod źródłowy podczas jego działania za pomocą debugera. NuGet obsługuje generowanie oddzielnego pakietu symboli (*.snupkg), który zawiera pliki symboli obok głównego pakietu zawierającego zestawy .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 serwera symboli . Deweloperzy mogą używać symboli opublikowanych na serwerze symboli NuGet.org, dodając https://symbols.nuget.org/download/symbols do źródeł symboli w programie Visual Studio.

Ważny

Serwer symboli NuGet.org obsługuje tylko nowe pliki symboli przenośnych (*.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 właściwość AllowedOutputExtensionsInPackageBuildOutputFolder:

<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 .NET kompilowanych przy użyciu projektów w stylu SDK. Jeśli rozmiar pakietu jest problemem, zamiast tego należy opublikować symbole w pakiecie symboli.

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

Pakiety symboli (*.snupkg) zapewniają deweloperom dobre środowisko debugowania na żądanie bez zwiększania rozmiaru głównego pakietu i bez wpływu na wydajność przywracania dla tych, którzy nie planują debugować pakietów 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