Rychlý start: Vytvoření a publikování balíčku pomocí sady Visual Studio (.NET Framework, Windows)

Pomocí sady Microsoft Visual Studio můžete vytvořit balíček NuGet z knihovny tříd rozhraní .NET Framework a pak ho publikovat do nuget.org pomocí nástroje Rozhraní příkazového řádku NuGet.

Rychlý start je určený jenom pro uživatele Windows. Pokud používáte Visual Studio pro Mac, přečtěte si místo toho nástroje rozhraní příkazového řádku dotnet.

Požadavky

• Nainstalujte visual Studio 2022 pro Windows s libovolným . Úloha související s net

  Edici 2022 Community si můžete nainstalovat zdarma z visualstudio.microsoft.com nebo použít edici Professional nebo Enterprise.

  Visual Studio 2017 a vyšší automaticky zahrnuje funkce NuGet při instalaci úlohy .NET.

• 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

Chcete-li vytvořit projekt knihovny tříd, postupujte takto:

1. V sadě Visual Studio vyberte Soubor>nový>projekt.

2. V okně Vytvořit nový projekt vyberte v rozevíracích seznamech C#, Windows a Library .

3. Ve výsledném seznamu šablon projektů vyberte Knihovnu tříd (.NET Framework) a pak vyberte Další.

4. V okně Konfigurovat nový projekt zadejte Název projektu AppLoggera pak vyberte Vytvořit.

5. 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).

6. (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 tento ukázkový 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);
           }
       }
   }
   

   V rámci skutečného balíčku NuGet byste pravděpodobně implementovali mnoho užitečných funkcí, se kterými můžou ostatní vytvářet aplikace. Můžete také nastavit cílové architektury. Příklady najdete v tématu UPW a Xamarin.

Konfigurace vlastností projektu pro balíček

Balíček NuGet obsahuje manifest ( .nuspec soubor), který obsahuje relevantní metadata, jako je identifikátor balíčku, číslo verze, popis a další. Některá z těchto metadat lze přímo nakreslit z vlastností projektu, což se v projektu i manifestu nemusí samostatně aktualizovat. Následující kroky popisují, jak nastavit příslušné vlastnosti:

1. Vyberte Vlastnosti projektu > a pak vyberte kartu Aplikace.

2. Jako název sestavení zadejte jedinečný identifikátor balíčku. Pokud se pokusíte publikovat balíček s názvem, který už existuje, zobrazí se chyba.

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

3. Vyberte Informace o sestavení, ve kterém se zobrazí dialogové okno, ve kterém můžete zadat další vlastnosti, které se do manifestu přenesou (viz Náhradní tokeny). Nejčastěji používaná pole jsou Název, Popis, Společnost, Autorská práva a Verze sestavení. Vzhledem k tomu, že se tyto vlastnosti zobrazí s balíčkem na hostiteli, jako je nuget.org po publikování, ujistěte se, že jsou plně popisné.

   

4. (Volitelné) Pokud chcete zobrazit a upravit vlastnosti přímo, otevřete v projektu soubor Vlastnosti/AssemblyInfo.cs výběrem možnosti Projekt>upravit soubor projektu.

5. Po nastavení těchto vlastností nastavte konfiguraci aktivního řešení v nástroji Build>Configuration Manager tak, aby se projekt uvolnil a znovu sestavil, aby se vygenerovala aktualizovaná knihovna DLL.

Vygenerování počátečního manifestu

Po nastavení vlastností projektu a vytvoření knihovny DLL teď můžete vygenerovat počáteční soubor .nuspec z projektu. Tento krok obsahuje relevantní náhradní tokeny pro kreslení informací ze souboru projektu.

Spuštěním nuget spec pouze jednou vygenerujte počáteční manifest. Pokud balíček aktualizujete, změňte hodnoty v projektu nebo upravte manifest přímo:

1. 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, kde AppLogger.csproj se soubor nachází.

2. Spusťte následující příkaz: nuget spec AppLogger.csproj.

   NuGet vytvoří manifest, který odpovídá názvu projektu, v tomto případě AppLogger.nuspec. Zahrnuje také náhradní tokeny v manifestu.

3. Otevřete AppLogger.nuspec v textovém editoru a prozkoumejte jeho obsah, který bude podobný následujícímu kódu:

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>Your username</authors>
       <owners>Your username</owners>
       <license type="expression">MIT</license>
       <!-- <icon>icon.png</icon> -->
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2022</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Úprava manifestu

1. Před pokračováním upravte následující vlastnosti. Jinak pokud se pokusíte vytvořit balíček NuGet s výchozími hodnotami v .nuspec souboru, dojde k chybě. Informace o těchto vlastnostech naleznete v tématu Volitelné prvky metadat:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • značky

2. 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á.

3. V tuto chvíli můžete do manifestu přidat i další prvky, jak je popsáno v odkazu na soubor .nuspec.

4. Než budete pokračovat, uložte soubor.

Spuštění příkazu pack

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

2. Spusťte následující příkaz: nuget pack.

   NuGet vygeneruje soubor .nupkg ve formě identifier.version.nupkg v aktuální složce.

Publikování balíčku

Po vytvoření souboru .nupkg ho publikujte do nuget.org pomocí rozhraní příkazového řádku NuGet s klíčem rozhraní API získaným z nuget.org. Pro nuget.org musíte použít nuget.exe verzi 4.1.0 nebo vyšší.

Pokud chcete balíček otestovat a ověřit před publikováním veřejné galerie, můžete ho nahrát do testovacího prostředí, jako je int.nugettest.org místo nuget.org. Mějte na paměti, že balíčky nahrané do int.nugettest.org se nemusí zachovat.

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

1. Pokud ho ještě nemáte, přihlaste se ke svému nuget.org účtu nebo si ho vytvořte.

2. Vyberte své uživatelské jméno v pravém horním rohu a pak vyberte Klíče rozhraní API.

3. Vyberte Vytvořit a zadejte název klíče.

4. V části Vybrat obory vyberte Nasdílení změn.

5. V části Vybrat vzor globu>balíčků zadejte *.

6. Vyberte Vytvořit.

7. 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í rozhraní příkazového řádku NuGet

Použití rozhraní příkazového řádku NuGet (nuget.exe) je alternativou k použití rozhraní příkazového řádku .NET:

1. Otevřete příkazový řádek a přejděte do složky obsahující soubor .nupkg .

2. Spusťte následující příkaz: Nahraďte <název souboru> balíčku názvem vašeho balíčku a nahraďte <hodnotu> klíče rozhraní API klíčem rozhraní API. Název souboru balíčku je zřetězení ID balíčku a čísla verze s příponou .nupkg . Například AppLogger.1.0.0.nupkg:

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   Výsledek procesu publikování se zobrazí takto:

   Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
       PUT https://www.nuget.org/api/v2/package/
       Created https://www.nuget.org/api/v2/package/ 6829ms
   Your package was pushed.
   

Další informace najdete v nuget push.

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

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

   

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

Další kroky

Blahopřejeme k vytvoření balíčku NuGet pomocí sady Visual Studio .NET Framework. V dalším článku se dozvíte, jak vytvořit balíček NuGet pomocí rozhraní příkazového řádku NuGet.

Vytvoření balíčku pomocí rozhraní příkazového řádku NuGet

Další možnosti, které NuGet nabízí, najdete v následujících článcích:

• Publikování balíčku
• Vytvoření předběžné verze balíčku
• Podpora více cílových architektur
• Správa verzí balíčků
• Vytvoření lokalizovaného balíčku