Sdílet prostřednictvím

NuGet

  • Článek

NuGet je správce balíčků pro ekosystém .NET a je primárním způsobem, jak vývojáři hledají a získávají opensourcové knihovny .NET. NuGet.org je bezplatná služba poskytovaná Microsoftem pro hostování balíčků NuGet primárním hostitelem veřejných balíčků NuGet, ale můžete je publikovat do vlastních služeb NuGet, jako jsou MyGet a Azure Artifacts.

NuGet

Vytvoření balíčku NuGet

Balíček NuGet (*.nupkg) je soubor zip, který obsahuje sestavení .NET a přidružená metadata.

Balíček NuGet můžete vytvořit dvěma hlavními způsoby. Novějším a doporučeným způsobem je vytvořit balíček z projektu ve stylu sady SDK (soubor projektu, jehož obsah začíná <Project Sdk="Microsoft.NET.Sdk">). Sestavení a cíle se automaticky přidají do balíčku a zbývající metadata se přidají do souboru MSBuild, jako je název balíčku a číslo verze. Kompilace pomocí dotnet pack příkazu vypíše *.nupkg soubor místo sestavení.

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

Starší způsob vytvoření balíčku NuGet je soubor *.nuspec a nástroj příkazového nuget.exe řádku. Soubor nuspec poskytuje skvělou kontrolu, ale musíte pečlivě určit, jaká sestavení a cíle mají být zahrnuty do konečného balíčku NuGet. Je snadné udělat chybu nebo pro někoho, kdo zapomene aktualizovat nuspec při provádění změn. Nuspec má výhodu, že ho můžete použít k vytvoření balíčků NuGet pro architektury, které ještě nepodporují soubor projektu ve stylu sady SDK.

✔️ ZVAŽTE vytvoření balíčku NuGet pomocí souboru projektu ve stylu sady SDK.

Závislosti balíčků

Závislosti balíčků NuGet jsou podrobně popsány v článku Závislosti.

Důležitá metadata balíčku NuGet

Balíček NuGet podporuje mnoho vlastností metadat. Následující tabulka obsahuje základní metadata, která by měl poskytnout každý balíček na NuGet.org:

Název vlastnosti NÁSTROJE MSBuild Název Nuspec Popis
PackageId id Identifikátor balíčku. Předpona z identifikátoru může být vyhrazena , pokud splňuje kritéria.
PackageVersion version Verze balíčku NuGet Další informace najdete v tématu Verze balíčku NuGet.
Title title Název balíčku, který je pro člověka přátelský. Výchozí hodnota PackageIdje .
Description description Dlouhý popis balíčku zobrazeného v uživatelském rozhraní.
Authors authors Seznam autorů balíčků oddělený čárkami, který odpovídá názvům profilů v nuget.org.
PackageTags tags Seznam značek a klíčových slov oddělených středníkem, které popisují balíček. Značky se používají při hledání balíčků.
PackageIcon icon Cesta k obrázku v balíčku, která se má použít jako ikona balíčku. Přečtěte si další informace o icon metadatech.
PackageProjectUrl projectUrl Adresa URL domovské stránky projektu nebo zdrojového úložiště
PackageLicenseExpression license Identifikátor SPDX licence projektu. Identifikátor může používat jenom schválené licence OSI a FSF. Jiné licence by měly používat PackageLicenseFile. Přečtěte si další informace o license metadatech.

Důležité

Projekt bez licence se ve výchozím nastavení používá k výhradnímu autorským právům, což znemožňuje, aby ho mohli používat jiní uživatelé.

✔️ ZVAŽTE výběr názvu balíčku NuGet s předponou, která splňuje kritéria rezervace předpony NuGetu.

✔️ Do use an HTTPS href to your package icon.

Weby, jako je NuGet.org spuštěné s povoleným protokolem HTTPS, a zobrazením image bez HTTPS se vytvoří upozornění na smíšený obsah.

✔️ Použijte obrázek ikony balíčku, který je 64x64 a má průhledné pozadí pro nejlepší zobrazení výsledků.

✔️ ZVAŽTE nastavení odkazu na zdroj pro přidání metadat správy zdrojového kódu do sestavení a balíčku NuGet.

Zdrojový odkaz automaticky přidá RepositoryUrl a RepositoryType metadata do balíčku NuGet. Source Link také přidává informace o přesném zdrojovém kódu, ze které byl balíček sestaven. Například balíček vytvořený z úložiště Git bude obsahovat hodnotu hash potvrzení přidanou jako metadata.

Předběžné verze balíčků

Balíčky NuGet s příponou verze se považují za předběžné verze. Ve výchozím nastavení se v uživatelském rozhraní NuGet Správce balíčků zobrazují stabilní vydané verze, pokud se uživatel rozhodne pro předběžné verze balíčků, což je ideální pro omezené uživatelské testování.

<PackageVersion>1.0.1-beta1</PackageVersion>

Poznámka:

Stabilní balíček nemůže záviset na předběžném balíčku. Musíte buď vytvořit vlastní balíček před vydáním, nebo záviset na starší stabilní verzi.

NuGet pre-release package dependency

✔️ Publikujte předběžný balíček při testování, náhledu nebo experimentování.

✔️ Publikujte stabilní balíček, jakmile je připravený, aby na něj mohly odkazovat další stabilní balíčky.

Balíčky symbolů

Soubory symbolů (*.pdb) jsou vytvářeny kompilátorem .NET spolu se sestaveními. Soubory symbolů mapují umístění spuštění do původního zdrojového kódu, abyste mohli procházet zdrojový kód, když je spuštěný pomocí ladicího programu. NuGet podporuje generování samostatného balíčku symbolů (*.snupkg) obsahujícího soubory symbolů spolu s hlavním balíčkem obsahujícím sestavení .NET. Myšlenka balíčků symbolů je hostovaná na serveru symbolů a stáhnou se jenom nástrojem, jako je Visual Studio na vyžádání.

NuGet.org hostuje vlastní úložiště serverů symbolů. Vývojáři můžou pomocí symbolů publikovaných na serveru symbolů NuGet.org přidat https://symbols.nuget.org/download/symbols do svých zdrojů symbolů v sadě Visual Studio.

Důležité

Server symbolů NuGet.org podporuje pouze nové soubory přenosných symbolů (*.pdb) vytvořené projekty ve stylu sady SDK.

Aby vývojáři mohli při ladění knihovny .NET používat server symbolů NuGet.org, musí mít Visual Studio 2017 verze 15.9 nebo novější.

Alternativou k vytvoření balíčku symbolů je vložení souborů symbolů do hlavního balíčku NuGet. Hlavní balíček NuGet bude větší, ale vložené soubory symbolů znamenají, že vývojáři nemusí konfigurovat server symbolů NuGet.org. Pokud vytváříte balíček NuGet pomocí projektu ve stylu sady SDK, můžete vložit soubory symbolů nastavením AllowedOutputExtensionsInPackageBuildOutputFolder vlastnosti:

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

Nevýhodou vkládání souborů symbolů je, že zvětšují velikost balíčku o přibližně 30 % pro knihovny .NET kompilované pomocí projektů ve stylu sady SDK. Pokud jde o velikost balíčku, měli byste místo toho publikovat symboly v balíčku symbolů.

✔️ ZVAŽTE publikování symbolů jako balíčku symbolů (*.snupkg) pro NuGet.org

Balíčky symbolů (*.snupkg) poskytují vývojářům dobré prostředí pro ladění na vyžádání, aniž by se zvětšoval hlavní velikost balíčku a ovlivnil výkon obnovení pro ty, kteří nemají v úmyslu ladit balíček NuGet.

Upozornění spočívá v tom, že uživatelé možná budou muset najít a nakonfigurovat server symbolů NuGet ve svém integrovaném vývojovém prostředí (jako jednorázové nastavení), aby získali soubory symbolů. Visual Studio 2019 verze 16.1 přidalo server symbolů NuGet.org do seznamu výchozích serverů symbolů.

PředchozíDalší