Rychlý start: Vytvoření a publikování balíčku NuGet pomocí sady Visual Studio (jenom Windows)
Pomocí sady Microsoft Visual Studio můžete vytvořit balíček NuGet z knihovny tříd .NET a pak ho publikovat do nuget.org pomocí nástroje rozhraní příkazového řádku.
Rychlý start je určený jenom pro uživatele Windows. Pokud používáte Visual Studio pro Mac, přečtěte si téma Vytvoření balíčku NuGet z existujících projektů knihovny nebo použití rozhraní příkazového řádku .NET.
Požadavky
Nainstalujte Visual Studio 2022 pro Windows s úlohou související s .NET Core.
Edici 2022 Community si můžete nainstalovat zdarma z visualstudio.microsoft.com nebo použít edici Professional nebo Enterprise.
Visual Studio 2017 a novější automaticky obsahuje funkce NuGet při instalaci . Úloha související s net
Pokud rozhraní příkazového řádku .NET ještě není nainstalované, nainstalujte ho.
Pro Visual Studio 2017 a novější se rozhraní .NET CLI automaticky nainstaluje se všemi úlohami souvisejícími s .NET Core. V opačném případě nainstalujte sadu .NET Core SDK , abyste získali rozhraní příkazového řádku .NET. Rozhraní příkazového řádku .NET je vyžadováno pro projekty .NET, které používají formát stylu sady SDK (atribut SDK). Výchozí šablona knihovny tříd .NET v sadě Visual Studio 2017 a novější používá atribut SDK.
Důležité
Pokud pracujete s projektem bez sady SDK, postupujte podle pokynů v tématu Vytvoření a publikování balíčku .NET Framework (Visual Studio) a vytvořte a publikujte balíček. Pro účely tohoto článku se doporučuje rozhraní .NET CLI. I když můžete publikovat libovolný balíček NuGet pomocí rozhraní příkazového řádku NuGet, některé kroky v tomto článku jsou specifické pro projekty ve stylu sady SDK a rozhraní příkazového řádku .NET. Rozhraní příkazového řádku NuGet se používá pro projekty bez sady SDK (obvykle .NET Framework).
Pokud ho ještě nemáte, zaregistrujte si bezplatný účet na nuget.org . Před nahráním balíčku NuGet musíte účet zaregistrovat a potvrdit.
Nainstalujte rozhraní příkazového řádku NuGet tak, že ho stáhnete z nuget.org. Přidejte soubor nuget.exe do vhodné složky a přidejte ji do proměnné prostředí PATH.
Vytvoření projektu knihovny tříd
Pro kód, který chcete zabalit, můžete použít existující projekt knihovny tříd .NET, nebo můžete vytvořit následující projekt:
V sadě Visual Studio vyberte Soubor>nový>projekt.
V okně Vytvořit nový projekt vyberte v rozevíracích seznamech C#, Windows a Library .
Ve výsledném seznamu šablon projektů vyberte knihovnu tříd (s popisem, projekt pro vytvoření knihovny tříd, která cílí na .NET nebo .NET Standard) a pak vyberte Další.
V okně Konfigurovat nový projekt zadejte Název projektu AppLoggera pak vyberte Další.
V okně Další informace vyberte příslušnou architekturu a pak vyberte Vytvořit.
Pokud si nejste jistí, kterou architekturu vybrat, je nejnovější vhodnou volbou a můžete ji později snadno změnit. Informace o tom, kterou architekturu použít, naleznete v tématu Kdy cílit na .NET 5.0 nebo .NET 6.0 vs. .NET Standard.
Pokud chcete zajistit správné vytvoření projektu, vyberte Sestavit řešení sestavení>. Knihovna DLL se nachází ve složce Debug (nebo Release, pokud místo toho sestavíte tuto konfiguraci).
(Volitelné) Pro účely tohoto rychlého startu nemusíte psát žádný další kód balíčku NuGet, protože knihovna tříd šablony stačí k vytvoření balíčku. Pokud ale chcete pro balíček nějaký funkční kód, uveďte následující kód:
namespace AppLogger { public class Logger { public void Log(string text) { Console.WriteLine(text); } } }
Konfigurace vlastností balíčku
Po vytvoření projektu můžete vlastnosti balíčku NuGet nakonfigurovat pomocí následujícího postupu:
Vyberte projekt v Průzkumník řešení a pak vyberte>< Název> projektu Vlastnosti, kde <název> projektu je název projektu.
Rozbalte uzel Balíček a pak vyberte Obecné.
Uzel Balíček se zobrazí pouze pro projekty ve stylu sady SDK v sadě Visual Studio. Pokud cílíte na projekt, který není stylem sady SDK (obvykle .NET Framework), buď projekt migrujte, nebo si přečtěte téma Vytvoření a publikování balíčku .NET Framework pro podrobné pokyny.
U balíčků vytvořených pro veřejnou spotřebu věnujte zvláštní pozornost vlastnosti Značky , protože značky pomáhají ostatním najít váš balíček a pochopit, co dělá.
Dejte balíčku jedinečné ID balíčku a vyplňte všechny další požadované vlastnosti. Tabulka, která ukazuje, jak vlastnosti NÁSTROJE MSBuild (projekty ve stylu sady SDK) mapuje na vlastnosti souboru .nuspec , viz cíle balíčku. Popis vlastností souboru .nuspec naleznete v odkazu na soubor .nuspec. Všechny tyto vlastnosti přejdou do manifestu
.nuspec, který sada Visual Studio pro projekt vytvoří.Důležité
Balíček musíte poskytnout jedinečný identifikátor pro nuget.org nebo libovolného hostitele, kterého používáte. V opačném případě dojde k chybě. Pro účely tohoto rychlého startu doporučujeme zahrnout do názvu ukázku nebo test , protože krok publikování balíček veřejně zviditelní.
(Volitelné) Pokud chcete zobrazit vlastnosti přímo v souboru projektu AppLogger.csproj, vyberte >Projekt upravit soubor projektu.
Načte se karta AppLogger.csproj .
Tato možnost je dostupná od sady Visual Studio 2017 pro projekty, které používají atribut stylu sady SDK. V dřívějších verzích sady Visual Studio musíte vybrat projekt Unload Project>, abyste mohli soubor projektu upravit.
Spuštění příkazu pack
Chcete-li vytvořit balíček NuGet z projektu, postupujte takto:
Vyberte Build>Configuration Manager a pak nastavte konfiguraci aktivního řešení na Verzi.
V Průzkumník řešení vyberte projekt AppLogger a pak vyberte Balíček.
Visual Studio projekt sestaví a vytvoří soubor .nupkg .
V okně Výstup vyhledejte podrobnosti, která obsahuje cestu k souboru balíčku. V tomto příkladu je integrované sestavení ve formátu bin\Release\net6.0 jako cíl .NET 6.0:
1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------ 1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll 1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'. ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========Pokud příkaz Pack v nabídce nevidíte, váš projekt pravděpodobně není projekt ve stylu sady SDK a potřebujete použít rozhraní příkazového řádku NuGet. Buď migrujte projekt a použijte .NET CLI, nebo si přečtěte článek Vytvoření a publikování balíčku rozhraní .NET Framework s podrobnými pokyny.
(Volitelné) Generování balíčku při sestavení
Sadu Visual Studio můžete nakonfigurovat tak, aby při sestavování projektu automaticky vygenerovala balíček NuGet:
Vyberte projekt v Průzkumník řešení a pak vyberte>< Název> projektu Vlastnosti, kde <název> projektu je název projektu (v tomto případě AppLogger).
Rozbalte uzel Balíček, vyberte Obecné a pak vyberte Vygenerovat balíček NuGet při sestavení.
Poznámka:
Při automatickém vygenerování balíčku se tím zvýší celková doba sestavení pro váš projekt.
(Volitelné) Balení s nástrojem MSBuild
Jako alternativu k použití příkazu nabídky Pack podporuje pack NuGet 4.x+ a MSBuild 15.1+ cíl, pokud projekt obsahuje potřebná data balíčku:
Když máte projekt otevřený v Průzkumník řešení, otevřete příkazový řádek výběrem příkazového řádku Nástroje>příkazového řádku Developer Command>Prompt.
Příkazový řádek se otevře v adresáři projektu.
Spusťte následující příkaz:
msbuild -t:pack.
Další informace naleznete v tématu Vytvoření balíčku pomocí nástroje MSBuild.
Publikování balíčku
Po vytvoření souboru .nupkg ho publikujte do nuget.org pomocí rozhraní příkazového řádku .NET nebo rozhraní příkazového řádku NuGet společně s klíčem rozhraní API získaným z nuget.org.
Poznámka:
Nuget.org prohledá všechny nahrané balíčky viry a odmítne balíčky, pokud najde nějaké viry. Nuget.org také pravidelně prohledá všechny existující uvedené balíčky.
Balíčky, které publikujete do nuget.org, jsou veřejně viditelné ostatním vývojářům, pokud je nezadáte. Pokud chcete balíčky hostovat soukromě, přečtěte si téma Hostování vlastních informačních kanálů NuGet.
Získání klíče rozhraní API
Před publikováním balíčku NuGet vytvořte klíč rozhraní API:
Pokud ho ještě nemáte, přihlaste se ke svému nuget.org účtu nebo si ho vytvořte.
Vyberte své uživatelské jméno v pravém horním rohu a pak vyberte Klíče rozhraní API.
Vyberte Vytvořit a zadejte název klíče.
V části Vybrat obory vyberte Nasdílení změn.
V části Vybrat vzor globu>balíčků zadejte *.
Vyberte Vytvořit.
Vyberte Kopírovat a zkopírujte nový klíč.
Důležité
- Vždy udržujte klíč rozhraní API tajným kódem. Klíč rozhraní API je jako heslo, které umožňuje každému spravovat balíčky vaším jménem. Pokud se klíč rozhraní API omylem odhalí, odstraňte ho nebo vygenerujte znovu.
- Uložte klíč do zabezpečeného umístění, protože klíč později nemůžete zkopírovat. Pokud se vrátíte na stránku klíče rozhraní API, musíte klíč znovu vygenerovat a zkopírovat ho. Klíč rozhraní API můžete také odebrat, pokud už nechcete nasdílet balíčky.
Rozsah umožňuje vytvořit samostatné klíče rozhraní API pro různé účely. Každý klíč má časový rámec vypršení platnosti a klíč můžete nastavit na konkrétní balíčky nebo vzory globu. Každý klíč také definujete na konkrétní operace: Nasdílíte nové balíčky a verze balíčků, nasdílíte jenom nové verze balíčků nebo zrušíte seznam.
Prostřednictvím oboru můžete vytvořit klíče rozhraní API pro různé uživatele, kteří spravují balíčky pro vaši organizaci, aby měli jenom potřebná oprávnění.
Další informace najdete v tématu o klíčích rozhraní API s vymezeným oborem.
Publikování pomocí .NET CLI nebo Rozhraní příkazového řádku NuGet
Každý z následujících nástrojů rozhraní příkazového řádku umožňuje odeslat balíček na server a publikovat ho. Vyberte kartu nástroje rozhraní příkazového řádku, buď rozhraní příkazového řádku .NET, nebo Rozhraní příkazového řádku NuGet.
Použití rozhraní příkazového řádku .NET (dotnet.exe) je doporučenou alternativou k použití rozhraní příkazového řádku NuGet.
Ve složce, která obsahuje soubor .nupkg , spusťte následující příkaz. Zadejte název souboru .nupkg a nahraďte hodnotu klíče klíčem rozhraní API.
dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json
Výstup zobrazuje výsledky procesu publikování:
Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.
Další informace najdete v tématu dotnet nuget push.
Poznámka:
Pokud se chcete vyhnout živému testovacímu balíčku na nuget.org, můžete nasdílení změn do testovacího webu nuget.org na adrese https://int.nugettest.org. Mějte na paměti, že balíčky nahrané do int.nugettest.org nemusí být zachovány.
Chyby publikování
Chyby z push příkazu obvykle značí problém. Možná jste například zapomněli aktualizovat číslo verze v projektu, takže se pokoušíte publikovat balíček, který už existuje.
Zobrazí se také chyby, pokud je váš klíč rozhraní API neplatný nebo vypršela jeho platnost, nebo pokud se pokusíte publikovat balíček pomocí identifikátoru, který už na hostiteli existuje. Předpokládejme například, že identifikátor AppLogger-test již v nuget.org existuje. Pokud se pokusíte publikovat balíček s tímto identifikátorem, push příkaz zobrazí následující chybu:
Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).
Pokud se zobrazí tato chyba, zkontrolujte, že používáte platný klíč rozhraní API, jehož platnost nevypršela. Pokud ano, znamená to, že identifikátor balíčku již na hostiteli existuje. Pokud chcete chybu opravit, změňte identifikátor balíčku tak, aby byl jedinečný, znovu sestavte projekt, znovu vytvořte soubor .nupkg a zkuste push příkaz zopakovat.
Správa publikovaného balíčku
Po úspěšném publikování balíčku obdržíte potvrzovací e-mail. Pokud chcete zobrazit právě publikovaný balíček, vyberte v nuget.org svoje uživatelské jméno v pravém horním rohu a pak vyberte Spravovat balíčky.
Poznámka:
Může chvíli trvat, než se váš balíček indexuje a zobrazí se ve výsledcích hledání, kde ho můžou najít jiní uživatelé. Během této doby se balíček zobrazí v části Nezasílané balíčky a na stránce balíčku se zobrazí následující zpráva:
Teď jste publikovali balíček NuGet, který nuget.org, který můžou ostatní vývojáři používat ve svých projektech.
Pokud jste vytvořili balíček, který není užitečný (například tento ukázkový balíček vytvořený s prázdnou knihovnou tříd), nebo se rozhodnete, že nechcete, aby byl balíček viditelný, můžete zrušit zařazení balíčku a skrýt ho ve výsledcích hledání:
Jakmile se balíček zobrazí v části Publikované balíčky na stránce Spravovat balíčky, vyberte ikonu tužky vedle výpisu balíčku.
Na další stránce zaškrtněte políčko Výpis, zrušte výběr seznamu ve výsledcích hledání a pak vyberte Uložit.
Balíček se teď zobrazí v části Nezasílané balíčky ve správě balíčků a ve výsledcích hledání se už nezobrazuje.
Poznámka:
Abyste zabránili živému provozu testovacího balíčku na nuget.org, můžete odeslat do testovacího webu nuget.org na adrese https://int.nugettest.org. Mějte na paměti, že balíčky nahrané do int.nugettest.org nemusí být zachovány.
Přidání souboru readme nebo jiného souboru
Pokud chcete přímo zadat soubory, které se mají zahrnout do balíčku, upravte soubor projektu a přidejte content vlastnost:
<ItemGroup>
<Content Include="readme.txt">
<Pack>true</Pack>
<PackagePath>\</PackagePath>
</Content>
</ItemGroup>
V tomto příkladu vlastnost určuje soubor s názvem readme.txt v kořenovém adresáři projektu. Visual Studio zobrazí obsah tohoto souboru jako prostý text hned po instalaci balíčku. Soubory Readme se nezobrazují pro balíčky nainstalované jako závislosti. Tady je například soubor readme pro balíček HtmlAgilityPack:
1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced.
7 This is normally found at
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
9 or
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced.
14 This is normally found at
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client
16 or
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client
Poznámka:
Pokud do kořenového adresáře projektu přidáte pouze readme.txt bez zahrnutí do content vlastnosti souboru projektu, nebude součástí balíčku.
Související video
Další videa NuGet najdete na Webu Channel 9 a YouTube.
Blahopřejeme k vytvoření balíčku NuGet pomocí knihovny tříd sady Visual Studio .NET. V dalším článku se dozvíte, jak vytvořit balíček NuGet pomocí rozhraní Visual Studio .NET Framework.
Další možnosti, které NuGet nabízí, najdete v následujících článcích: