Rychlý Start: vytvoření a publikování balíčku NuGet pomocí sady Visual Studio (.NET Standard, pouze Windows)Quickstart: Create and publish a NuGet package using Visual Studio (.NET Standard, Windows only)

Je to jednoduchý proces vytvoření balíčku NuGet z knihovny tříd .NET Standard v aplikaci Visual Studio ve Windows a jeho následné publikování na nuget.org pomocí nástroje CLI.It's a simple process to create a NuGet package from a .NET Standard Class Library in Visual Studio on Windows, and then publish it to nuget.org using a CLI tool.

Poznámka

Pokud používáte Visual Studio pro Mac, přečtěte si tyto informace o vytvoření balíčku NuGet nebo použijte nástroje dotnet CLI.If you are using Visual Studio for Mac, refer to this information on creating a NuGet package, or use the dotnet CLI tools.

PožadavkyPrerequisites

  1. Nainstalujte jakoukoli edici sady Visual Studio 2019 z VisualStudio.com s využitím úlohy související s .NET Core.Install any edition of Visual Studio 2019 from visualstudio.com with a .NET Core related workload.

  2. Pokud ještě není nainstalovaná, nainstalujte dotnet CLI.If it's not already installed, install the dotnet CLI.

    Pro dotnet CLI počínaje sadou Visual Studio 2017 se dotnet CLI automaticky nainstaluje se všemi úlohami souvisejícími s .NET Core.For the dotnet CLI, starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads. V opačném případě nainstalujte .NET Core SDK pro získání dotnet CLI.Otherwise, install the .NET Core SDK to get the dotnet CLI. dotnet CLI je vyžadován pro .NET Standard projekty, které používají Formát sady SDK (atribut sady SDK).The dotnet CLI is required for .NET Standard projects that use the SDK-style format (SDK attribute). Výchozí .NET Standard šablona knihovny tříd v sadě Visual Studio 2017 a vyšší, která se používá v tomto článku, používá atribut SDK.The default .NET Standard class library template in Visual Studio 2017 and higher, which is used in this article, uses the SDK attribute.

    Důležité

    Pokud pracujete s projektem, který není typu SDK, postupujte podle pokynů v části Vytvoření a publikování .NET Frameworkho balíčku (Visual Studio) pro vytvoření a publikování balíčku.If you are working with a non-SDK-style project, follow the procedures in Create and publish a .NET Framework package (Visual Studio) to create and publish the package instead. V tomto článku se doporučuje dotnet CLI.For this article, the dotnet CLI is recommended. I když můžete publikovat libovolný balíček NuGet pomocí nuget.exe CLI, některé kroky v tomto článku jsou specifické pro projekty ve stylu sady SDK a rozhraní příkazového řádku dotnet.Although you can publish any NuGet package using the nuget.exe CLI, some of the steps in this article are specific to SDK-style projects and the dotnet CLI. Rozhraní příkazového řádku NuGet. exe se používá pro projekty, které nejsou ve stylu sady SDK (obvykle .NET Framework).The nuget.exe CLI is used for non-SDK-style projects (typically .NET Framework).

  3. Zaregistrujte si bezplatný účet na NuGet.org , pokud ho ještě nemáte.Register for a free account on nuget.org if you don't have one already. Když se vytvoří nový účet, pošle se potvrzovací e-mail.Creating a new account sends a confirmation email. Než budete moct nahrát balíček, musíte účet potvrdit.You must confirm the account before you can upload a package.

Vytvořit projekt knihovny třídCreate a class library project

Můžete použít existující .NET Standard projekt knihovny tříd pro kód, který chcete zabalit, nebo vytvořit jednoduchý, a to následujícím způsobem:You can use an existing .NET Standard Class Library project for the code you want to package, or create a simple one as follows:

  1. V aplikaci Visual Studio zvolte soubor > nový > projekt, rozbalte uzel Visual C# > .NET Standard , vyberte šablonu knihovny tříd (.NET Standard), pojmenujte projekt AppLogger a klikněte na tlačítko OK.In Visual Studio, choose File > New > Project, expand the Visual C# > .NET Standard node, select the "Class Library (.NET Standard)" template, name the project AppLogger, and click OK.

    Tip

    Pokud nemáte důvod vybrat jinak, .NET Standard je upřednostňovaným cílem pro balíčky NuGet, protože poskytuje kompatibilitu s nejširší škálou náročných projektů.Unless you have a reason to choose otherwise, .NET Standard is the preferred target for NuGet packages, as it provides compatibility with the widest range of consuming projects.

  2. Klikněte pravým tlačítkem na výsledný soubor projektu a vyberte sestavit , abyste se ujistili, že se projekt vytvořil správně.Right-click on the resulting project file and select Build to make sure the project was created properly. Knihovna DLL se nachází ve složce ladění (nebo v případě, že tuto konfiguraci sestavíte místo toho).The DLL is found within the Debug folder (or Release if you build that configuration instead).

V rámci skutečného balíčku NuGet samozřejmě implementujete spoustu užitečných funkcí, se kterými můžou sestavovat aplikace i ostatní.Within a real NuGet package, of course, you implement many useful features with which others can build applications. Pro tento návod však nebudete psát žádný další kód, protože knihovna tříd ze šablony je dostačující k vytvoření balíčku.For this walkthrough, however, you won't write any additional code because a class library from the template is sufficient to create a package. I když chcete pro balíček použít nějaký funkční kód, použijte následující:Still, if you'd like some functional code for the package, use the following:

namespace AppLogger
{
    public class Logger
    {
        public void Log(string text)
        {
            Console.WriteLine(text);
        }
    }
}

Konfigurovat vlastnosti balíčkuConfigure package properties

  1. Klikněte pravým tlačítkem na projekt v Průzkumník řešení a zvolte příkaz nabídky vlastnosti a pak vyberte kartu balíček .Right-click the project in Solution Explorer, and choose Properties menu command, then select the Package tab.

    Karta balíček se zobrazí pouze pro projekty ve stylu sady SDK v aplikaci Visual Studio, obvykle .NET Standard nebo .NET Core Class projektů; Pokud cílíte na jiný projekt než sadu SDK (obvykle .NET Framework), buď migrujte projekt , nebo si přečtěte téma vytvoření a publikování .NET Framework balíčku pro podrobné pokyny.The Package tab appears only for SDK-style projects in Visual Studio, typically .NET Standard or .NET Core class library projects; if you are targeting a non-SDK style project (typically .NET Framework), either migrate the project or see Create and publish a .NET Framework package instead for step-by-step instructions.

    Vlastnosti balíčku NuGet v projektu Visual studia

    Poznámka

    Pro balíčky sestavené pro veřejnou spotřebu věnujte zvláštní pozornost vlastnosti značek , protože značky můžou ostatním uživatelům najít váš balíček a pochopit, co to dělá.For packages built for public consumption, pay special attention to the Tags property, as tags help others find your package and understand what it does.

  2. Dejte balíčku jedinečný identifikátor a vyplňte všechny požadované vlastnosti.Give your package a unique identifier and fill out any other desired properties. Mapování vlastností MSBuild (projekt ve stylu sady SDK) na vlastnosti v . nuspecnaleznete v tématu cíle balíčku.For a mapping of MSBuild properties (SDK-style project) to properties in a .nuspec, see pack targets. Popisy vlastností naleznete v souboru. nuspec reference.For descriptions of properties, see the .nuspec file reference. Všechny vlastnosti zde přejdou do .nuspec manifestu, který Visual Studio vytvoří pro projekt.All of the properties here go into the .nuspec manifest that Visual Studio creates for the project.

    Důležité

    Balíčku musíte dát identifikátor, který je jedinečný v rámci nuget.org nebo libovolného hostitele, který používáte.You must give the package an identifier that's unique across nuget.org or whatever host you're using. Pro tento návod doporučujeme, abyste v názvu jako pozdější krok publikování použili "Sample" nebo "test", aby byl balíček veřejně viditelný (i když je to nepravděpodobné, že ho kdokoli bude používat).For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it).

    Pokud se pokusíte publikovat balíček s názvem, který již existuje, zobrazí se chyba.If you attempt to publish a package with a name that already exists, you see an error.

  3. Volitelné Chcete-li zobrazit vlastnosti přímo v souboru projektu, klikněte pravým tlačítkem myši na projekt v Průzkumník řešení a vyberte Upravit AppLogger. csproj.(Optional) To see the properties directly in the project file, right-click the project in Solution Explorer and select Edit AppLogger.csproj.

    Tato možnost je k dispozici pouze od začátku v sadě Visual Studio 2017 pro projekty, které používají atribut Style sady SDK.This option is only available starting in Visual Studio 2017 for projects that use the SDK-style attribute. V opačném případě klikněte pravým tlačítkem myši na projekt a vyberte Uvolnit projekt.Otherwise, right-click the project and choose Unload Project. Pak klikněte pravým tlačítkem na uvolněný projekt a zvolte Upravit AppLogger. csproj.Then right-click the unloaded project and choose Edit AppLogger.csproj.

Spuštění příkazu PackRun the pack command

  1. Nastavte konfiguraci na release.Set the configuration to Release.

  2. Klikněte pravým tlačítkem na projekt v Průzkumník řešení a vyberte příkaz Pack :Right click the project in Solution Explorer and select the Pack command:

    Příkaz NuGet Pack v místní nabídce projektu sady Visual Studio

    Pokud nevidíte příkaz Pack , projekt pravděpodobně není projekt ve stylu sady SDK a je nutné použít nuget.exe CLI.If you don't see the Pack command, your project is probably not an SDK-style project and you need to use the nuget.exe CLI. Buď migrujte projekt a použijte dotnet CLI, nebo si přečtěte článek vytvoření a publikování .NET Framework balíčku pro podrobné pokyny.Either migrate the project and use dotnet CLI, or see Create and publish a .NET Framework package instead for step-by-step instructions.

  3. Visual Studio vytvoří projekt a vytvoří soubor .nupkg.Visual Studio builds the project and creates the .nupkg file. Projděte si podrobnosti v okně výstup (podobně jako v následujícím příkladu), který obsahuje cestu k souboru balíčku.Examine the Output window for details (similar to the following), which contains the path to the package file. Všimněte si také, že sestavené sestavení je v bin\Release\netstandard2.0 jako befits na cíl .NET Standard 2,0.Note also that the built assembly is in bin\Release\netstandard2.0 as befits the .NET Standard 2.0 target.

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
    1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\netstandard2.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 ==========
    

Volitelné Generovat balíček při sestavení(Optional) Generate package on build

Sadu Visual Studio můžete nakonfigurovat tak, aby automaticky generovala balíček NuGet při sestavování projektu.You can configure Visual Studio to automatically generate the NuGet package when you build the project.

  1. V Průzkumník řešení klikněte pravým tlačítkem na projekt a vyberte vlastnosti.In Solution Explorer, right-click the project and choose Properties.

  2. Na kartě balíček vyberte při sestavování vytvořit balíček NuGet.In the Package tab, select Generate NuGet package on build.

    Automaticky generovat balíček při sestavení

Poznámka

Když balíček automaticky vygenerujete, čas k zabalení zvýší čas sestavení pro váš projekt.When you automatically generate the package, the time to pack increases the build time for your project.

(Nepovinný) Pack s nástrojem MSBuild(Optional) pack with MSBuild

Jako alternativu k použití příkazu nabídky Pack , NuGet 4. x + a MSBuild 15.1 + podporuje cíl pack, když projekt obsahuje potřebná data balíčku.As an alternate to using the Pack menu command, NuGet 4.x+ and MSBuild 15.1+ supports a pack target when the project contains the necessary package data. Otevřete příkazový řádek, přejděte do složky projektu a spusťte následující příkaz.Open a command prompt, navigate to your project folder and run the following command. (Obvykle chcete spustit "Developer Command Prompt pro Visual Studio" z nabídky Start, protože se nakonfiguruje se všemi nezbytnými cestami pro MSBuild.)(You typically want to start the "Developer Command Prompt for Visual Studio" from the Start menu, as it will be configured with all the necessary paths for MSBuild.)

Další informace najdete v tématu Vytvoření balíčku pomocí nástroje MSBuild.For more information, see Create a package using MSBuild.

Publikování balíčkuPublish the package

Jakmile budete mít soubor .nupkg, publikujete ho nuget.org pomocí nuget.exe CLI nebo rozhraní příkazového řádku dotnet.exe spolu s klíčem rozhraní API získaným z nuget.org.Once you have a .nupkg file, you publish it to nuget.org using either the nuget.exe CLI or the dotnet.exe CLI along with an API key acquired from nuget.org.

Poznámka

Vyhledávání virů: nahrání do nuget.org všechny balíčky jsou vyhledány viry a odmítnuta, pokud nejsou nalezeny žádné viry.Virus scanning: All packages uploaded to nuget.org are scanned for viruses and rejected if any viruses are found. Všechny balíčky uvedené na nuget.org také jsou pravidelně kontrolovány.All packages listed on nuget.org are also scanned periodically.

Pokud jste vyjmutí ze seznamu je jsou i veřejně viditelné pro ostatní vývojáři balíčky pro publikování na nuget.org.Packages published to nuget.org are also publicly visible to other developers unless you unlist them. Hostujte balíčky soukromě, najdete v článku hostování balíčků.To host packages privately, see Hosting packages.

Získání klíče rozhraní APIAcquire your API key

  1. Přihlaste se k účtu NuGet.org nebo vytvořte účet, pokud ho ještě nemáte.Sign into your nuget.org account or create an account if you don't have one already.

    Další informace o vytvoření účtu najdete v tématu jednotlivé účty.For more information on creating your account, see Individual accounts.

  2. Vyberte své uživatelské jméno (v pravém horním rohu) a pak vyberte klíče rozhraní API.Select your user name (on the upper right), then select API Keys.

  3. Vyberte vytvořit, zadejte název pro svůj klíč, vyberte vybrat obory > Push.Select Create, provide a name for your key, select Select Scopes > Push. Zadejte * pro vzor globa pak vyberte vytvořit.Enter * for Glob pattern, then select Create. (Další informace o oborech najdete níže.)(See below for more about scopes.)

  4. Po vytvoření klíče vyberte Kopírovat a v rozhraní PŘÍKAZového řádku načtěte přístupový klíč, který potřebujete:Once the key is created, select Copy to retrieve the access key you need in the CLI:

    Zkopírování klíče rozhraní API do schránky

  5. Důležitéinformace: Klíč uložte na bezpečném místě, protože ho později nemůžete zkopírovat.Important: Save your key in a secure location because you cannot copy the key again later on. Pokud se vrátíte na stránku klíče rozhraní API, budete muset klíč znovu vygenerovat, abyste ho mohli zkopírovat.If you return to the API key page, you need to regenerate the key to copy it. Klíč rozhraní API můžete odebrat i v případě, že už nechcete nabízet balíčky přes rozhraní příkazového řádku.You can also remove the API key if you no longer want to push packages via the CLI.

Rozsah umožňuje vytvořit samostatné klíče rozhraní API pro různé účely.Scoping allows you to create separate API keys for different purposes. Každý klíč má svůj časový rámec vypršení platnosti a může být vymezen na konkrétní balíčky (nebo vzory glob).Each key has its expiration timeframe and can be scoped to specific packages (or glob patterns). Každý klíč je také vymezen pro konkrétní operace: vložení nových balíčků a aktualizací, pouze nabízených aktualizací nebo oddálení v seznamu.Each key is also scoped to specific operations: push of new packages and updates, push of updates only, or delisting. Pomocí oboru můžete vytvořit klíče rozhraní API pro různé lidi, kteří spravují balíčky pro vaši organizaci tak, aby měli jenom potřebná oprávnění.Through scoping, you can create API keys for different people who manage packages for your organization such that they have only the permissions they need. Další informace najdete v tématu vymezené klíče rozhraní API.For more information, see scoped API keys.

Publikování pomocí rozhraní příkazového řádku dotnet nebo NuGet. exe CLIPublish with the dotnet CLI or nuget.exe CLI

Vyberte kartu pro nástroj CLI, buď .NET Core CLI (dotnet CLI), nebo NuGet (NuGet. exe CLI).Select the tab for your CLI tool, either .NET Core CLI (dotnet CLI) or NuGet (nuget.exe CLI).

Tento krok je doporučenou alternativou použití nuget.exe.This step is the recommended alternative to using nuget.exe.

Než budete moct balíček publikovat, musíte nejdřív otevřít příkazový řádek.Before you can publish the package, you must first open a command line.

  1. Přejděte do složky, která obsahuje soubor .nupkg.Change to the folder containing the .nupkg file.

  2. Spusťte následující příkaz, zadáním názvu balíčku (jedinečné ID balíčku) a nahrazením hodnoty klíče klíčem rozhraní API:Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:

    dotnet nuget push AppLogger.1.0.0.nupkg -k qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -s https://api.nuget.org/v3/index.json
    
  3. dotnet zobrazuje výsledky procesu publikování:dotnet displays the results of the publishing process:

    info : Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
    info :   PUT https://www.nuget.org/api/v2/package/
    info :   Created https://www.nuget.org/api/v2/package/ 12620ms
    info : Your package was pushed.
    

Podívejte se na téma dotnet NuGet push.See dotnet nuget push.

Chyby publikováníPublish errors

Chyby z push příkaz obvykle signalizují potíže.Errors from the push command typically indicate the problem. Například možná jste zapomněli aktualizovat číslo verze ve vašem projektu a pokoušíte se publikovat balíček, který již existuje.For example, you may have forgotten to update the version number in your project and are therefore trying to publish a package that already exists.

Také se zobrazí chyby při pokusu o publikování balíčku pomocí identifikátor, který již existuje v hostiteli.You also see errors when trying to publish a package using an identifier that already exists on the host. Název "AppLogger", například už.The name "AppLogger", for example, already exists. V takovém případě push příkaz dochází k následující chybě:In such a case, the push command gives the following error:

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 používáte platný klíč rozhraní API, kterou jste právě vytvořili, tato zpráva znamená konfliktu názvů, která není zcela zřejmé z část "oprávnění" chyby.If you're using a valid API key that you just created, then this message indicates a naming conflict, which isn't entirely clear from the "permission" part of the error. Změnit identifikátor balíčku, sestavte projekt znovu, znovu vytvořit .nupkg souboru a zkuste to znovu push příkazu.Change the package identifier, rebuild the project, recreate the .nupkg file, and retry the push command.

Správa publikovaného balíčkuManage the published package

Váš profil na nuget.org, vyberte spravovat balíčky zobrazíte tu jste právě publikovali.From your profile on nuget.org, select Manage Packages to see the one you just published. Také obdržíte e-mail s potvrzením.You also receive a confirmation email. Všimněte si, že může trvat nějakou dobu váš balíček se zobrazí ve výsledcích hledání tam, kde ostatní můžete najít a indexovat.Note that it might take a while for your package to be indexed and appear in search results where others can find it. Během této doby stránku vašeho balíčku zobrazí následující zpráva:During that time your package page shows the message below:

Tento balíček nebyl dosud indexovány.

A to je všechno!And that's it! Právě jste publikovali svůj první balíček NuGet na nuget.org, které ostatní vývojáři mohou použít ve své vlastní projekty.You've just published your first NuGet package to nuget.org that other developers can use in their own projects.

Pokud v tomto návodu vytvoříte balíček, který není ve skutečnosti užitečné (jako je balíček vytvořen s prázdnou třídu knihovna), měli byste vyjmutí ze seznamu balíček ke skrytí před výsledky hledání:If in this walkthrough you created a package that isn't actually useful (such as a package created with an empty class library), you should unlist the package to hide it from search results:

  1. Na nuget.org, vyberte své uživatelské jméno (pravém horním rohu stránky) a pak vyberte spravovat balíčky.On nuget.org, select your user name (upper right of the page), then select Manage Packages.

  2. Vyhledání balíčku, kterou chcete vyjmutí ze seznamu v části publikováno a vyberte ikonu koše vpravo:Locate the package you want to unlist under Published and select the trash can icon on the right:

    Pro balíčků na nuget.org ikonu koše

  3. Na další stránku, zrušte zaškrtnutí políčka popisek seznamu (název balíčku) ve výsledcích hledání a vyberte Uložit:On the subsequent page, clear the box labeled List (package-name) in search results and select Save:

    Zrušením zaškrtnutí políčka seznam balíčků na nuget.org

Přidání souboru Readme a dalších souborůAdding a readme and other files

Chcete-li přímo určit soubory, které mají být zahrnuty do balíčku, upravte soubor projektu a použijte vlastnost content:To directly specify files to include in the package, edit the project file and use the content property:

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

Tato akce zahrne do kořenového adresáře balíčku soubor s názvem readme.txt.This will include a file named readme.txt in the package root. Sada Visual Studio zobrazí obsah tohoto souboru jako prostý text ihned po instalaci balíčku přímo.Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Soubory Readme se nezobrazí pro balíčky nainstalované jako závislosti).(Readme files are not displayed for packages installed as dependencies). Tady je příklad, jak se zobrazí soubor Readme pro balíček HtmlAgilityPack:For example, here's how the readme for the HtmlAgilityPack package appears:

Zobrazení souboru Readme pro balíček NuGet při instalaci

Poznámka

Pouze přidání souboru Readme. txt v kořenu projektu nebude mít za následek zahrnutí do výsledného balíčku.Merely adding the readme.txt at the project root will not result in it being included in the resulting package.