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, bezplatná služba poskytovaná Microsoftem pro hostování balíčků NuGet, je primárním hostitelem veřejných balíčků NuGet, ale můžete je publikovat do vlastních služeb NuGet, jako je MyGet a Azure Artifacts.

NuGet 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í příkazu dotnet pack místo sestavení vypíše soubor *.nupkg.

<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 se souborem *.nuspec a nástrojem příkazového řádku nuget.exe. 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 ně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 MSBuild Název Nuspec Popis
PackageId id Identifikátor balíčku. Předpona z identifikátoru může být vyhrazena, splňuje-li kritéria .
PackageVersion version Verze balíčku NuGet Další informace viz verze balíčku NuGet.
Title title Název balíčku, který je pro člověka přátelský. Výchozí hodnota je PackageId.
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 metadatech aicon.
PackageProjectUrl projectUrl Adresa URL domovské stránky projektu nebo zdrojového úložiště
PackageLicenseExpression license Identifikátor licence projektu SPDX . 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 metadatech license.

Důležitý

Projekt bez licence ve výchozím nastavení výhradních autorských práv, což znemožňuje použití jiným uživatelům.

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

✔️ Používejte odkaz HTTPS pro vaši ikonu balíčku.

Weby jako NuGet.org, které běží s povoleným HTTPS, a zobrazení obrázku bez tohoto protokolu způsobí 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í Source Link pro přidání metadat pro správu zdrojového kódu do vašich sestavení a balíčku NuGet.

Source Link automaticky přidává metadata RepositoryUrl a RepositoryType 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í uživatelské rozhraní Správce balíčků NuGet zobrazuje stabilní verze, pokud si uživatel záměrně nevybere předběžné balíčky, takže předběžné balíčky jsou 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é verzi balíčku. Musíte buď vytvořit vlastní předběžnou verzi balíčku, nebo záviset na starší stabilní verzi.

závislost předběžné verze balíčku NuGet

✔️ Publikujte předběžnou verzi balíčku 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 společně se sestaveními. Soubory symbolů mapují místa provedení na původní zdrojový kód, abyste mohli procházet zdrojový kód při jeho spuštění pomocí ladicího programu. NuGet podporuje vytváření samostatného balíčku symbolů (*.snupkg) obsahujícího soubory symbolů vedle hlavního balíčku s .NET sestaveními. Myšlenka balíčků symbolů spočívá v tom, že jsou hostovány na symbolovém serveru a stáhnou se pouze nástrojem, jako je Visual Studio, na vyžádání.

NuGet.org hostuje vlastní úložiště serverových symbolů . Vývojáři mohou používat symboly publikované na serveru symbolů NuGet.org přidáním https://symbols.nuget.org/download/symbols do zdrojů symbolů v sadě Visual Studio.

Důležitý

Server symbolů NuGet.org podporuje pouze nové soubory přenosných symbolů (*.pdb), které byly vytvořeny 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 vlastnosti AllowedOutputExtensionsInPackageBuildOutputFolder:

<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ší 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 zvětšovali velikost hlavního balíčku a ovlivnili výkon obnovení pro ty, kteří neplánují 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ší