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

Vytvoření balíčku NuGet z knihovny tříd .NET Framework zahrnuje vytvoření knihovny DLL v aplikaci Visual Studio ve Windows a následné vytvoření a publikování balíčku pomocí nástroje příkazového řádku NuGet. exe.Creating a NuGet package from a .NET Framework Class Library involves creating the DLL in Visual Studio on Windows, then using the nuget.exe command line tool to create and publish the package.

Poznámka

Tento rychlý Start se týká jenom sady Visual Studio 2017 a vyšších verzí pro Windows.This Quickstart applies to Visual Studio 2017 and higher versions for Windows only. Visual Studio pro Mac nezahrnuje funkce popsané tady.Visual Studio for Mac does not include the capabilities described here. Místo toho použijte nástroje DOTNET CLI .Use the dotnet CLI tools instead.

PožadavkyPrerequisites

  1. Nainstalujte jakoukoli edici sady Visual Studio 2017 nebo novější z VisualStudio.com s libovolným. Zatížení související s NET.Install any edition of Visual Studio 2017 or higher from visualstudio.com with any .NET-related workload. Pokud je nainstalovaná úloha .NET, Visual Studio 2017 automaticky zahrnuje funkce NuGet.Visual Studio 2017 automatically includes NuGet capabilities when a .NET workload is installed.

  2. Nainstalujte rozhraní příkazového řádku nuget.exe stažením z NuGet.orga uložením tohoto souboru .exe do vhodné složky a přidáním této složky do proměnné prostředí PATH.Install the nuget.exe CLI by downloading it from nuget.org, saving that .exe file to a suitable folder, and adding that folder to your PATH environment variable.

  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 Framework 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 Framework 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, vyberte uzel vizuálů C# , vyberte šablonu knihovny tříd (.NET Framework), pojmenujte projekt AppLogger a klikněte na tlačítko OK.In Visual Studio, choose File > New > Project, select the Visual C# node, select the "Class Library (.NET Framework)" template, name the project AppLogger, and click OK.

  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. Můžete také nastavit cílové architektury, například.You can also set the target frameworks however you like. Podívejte se například na příručky pro UWP a Xamarin.For example, see the guides for UWP and Xamarin.

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:

using System;

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

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. Přečtěte si téma Vytvoření a publikování balíčku pomocí sady Visual Studio (.NET Standard).See Create and publish a package using Visual Studio (.NET Standard).

Konfigurovat vlastnosti projektu pro balíčekConfigure project properties for the package

Balíček NuGet obsahuje manifest (soubor .nuspec), který obsahuje relevantní metadata, jako je například identifikátor balíčku, číslo verze, popis a další.A NuGet package contains a manifest (a .nuspec file), that contains relevant metadata such as the package identifier, version number, description, and more. Některé z nich lze vykreslit přímo z vlastností projektu a zabránit tak jejich samostatné aktualizaci v projektu i v manifestu.Some of these can be drawn from the project properties directly, which avoids having to separately update them in both the project and the manifest. V této části se dozvíte, kde můžete nastavit příslušné vlastnosti.This section describes where to set the applicable properties.

  1. Vyberte příkaz nabídky Vlastnosti projektu > a pak vyberte kartu aplikace .Select the Project > Properties menu command, then select the Application tab.

  2. V poli název sestavení poskytněte balíčku jedinečný identifikátor.In the Assembly name field, give your package a unique identifier.

    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. Vyberte tlačítko informace o sestavení... , které zobrazí dialogové okno, ve kterém můžete zadat další vlastnosti, které se přenesou do manifestu (viz soubor. nuspec – náhradní tokeny reference).Select the Assembly Information... button, which brings up a dialog box in which you can enter other properties that carry into the manifest (see .nuspec file reference - replacement tokens). Nejčastěji používaná pole jsou název, Popis, Společnost, Copyrighta verze sestavení.The most commonly used fields are Title, Description, Company, Copyright, and Assembly version. Tyto vlastnosti se nakonec zobrazí s vaším balíčkem na hostiteli, jako je nuget.org, a ujistěte se, že jsou plně popisné.These properties ultimately appear with your package on a host like nuget.org, so make sure they're fully descriptive.

    Informace o sestavení v projektu .NET Framework v aplikaci Visual Studio

  4. Volitelné: Chcete-li zobrazit a upravit vlastnosti přímo, otevřete soubor Properties/AssemblyInfo.cs v projektu.Optional: to see and edit the properties directly, open the Properties/AssemblyInfo.cs file in the project.

  5. Po nastavení vlastností nastavte konfiguraci projektu na vydaná a znovu sestavte projekt, aby se vygenerovala Aktualizovaná knihovna DLL.When the properties are set, set the project configuration to Release and rebuild the project to generate the updated DLL.

Generování počátečního manifestuGenerate the initial manifest

Když je knihovna DLL v rukou a nastavené vlastnosti projektu, nyní použijete příkaz nuget spec pro vygenerování počátečního souboru .nuspec z projektu.With a DLL in hand and project properties set, you now use the nuget spec command to generate an initial .nuspec file from the project. Tento krok zahrnuje relevantní náhradní tokeny k vykreslování informací ze souboru projektu.This step includes the relevant replacement tokens to draw information from the project file.

Spustíte nuget spec pouze jednou pro vygenerování počátečního manifestu.You run nuget spec only once to generate the initial manifest. Při aktualizaci balíčku můžete buď změnit hodnoty v projektu, nebo přímo upravit manifest.When updating the package, you either change values in your project or edit the manifest directly.

  1. Otevřete příkazový řádek a přejděte do složky projektu obsahující AppLogger.csproj soubor.Open a command prompt and navigate to the project folder containing AppLogger.csproj file.

  2. Spusťte následující příkaz: nuget spec AppLogger.csproj.Run the following command: nuget spec AppLogger.csproj. Když zadáte projekt, NuGet vytvoří manifest, který se shoduje s názvem projektu, v tomto případě AppLogger.nuspec.By specifying a project, NuGet creates a manifest that matches the name of the project, in this case AppLogger.nuspec. Obsahuje také náhradní tokeny v manifestu.It also include replacement tokens in the manifest.

  3. V textovém editoru otevřete AppLogger.nuspec a prověřte jeho obsah, který by měl vypadat takto:Open AppLogger.nuspec in a text editor to examine its contents, which should appear as follows:

    <?xml version="1.0"?>
    <package >
      <metadata>
        <id>Package</id>
        <version>1.0.0</version>
        <authors>YourUsername</authors>
        <owners>YourUsername</owners>
        <license type="expression">MIT</license>
        <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
        <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Package description</description>
        <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
        <copyright>Copyright 2019</copyright>
        <tags>Tag1 Tag2</tags>
      </metadata>
    </package>
    

Upravit manifestEdit the manifest

  1. NuGet vyvolá chybu, pokud se pokusíte vytvořit balíček s výchozími hodnotami v souboru .nuspec, takže před pokračováním musíte upravit následující pole.NuGet produces an error if you try to create a package with default values in your .nuspec file, so you must edit the following fields before proceeding. Viz odkaz na soubor. nuspec – volitelné prvky metadat pro popis způsobu jejich použití.See .nuspec file reference - optional metadata elements for a description of how these are used.

    • licenseUrllicenseUrl
    • projectUrlprojectUrl
    • iconUrliconUrl
    • releaseNotesreleaseNotes
    • značkytags
  2. 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 balíček na zdrojích, jako je NuGet.org, a pochopit, co dělá.For packages built for public consumption, pay special attention to the Tags property, as tags help others find your package on sources like nuget.org and understand what it does.

  3. V tomto okamžiku můžete také přidat další prvky do manifestu, jak je popsáno v souboru. nuspec reference.You can also add any other elements to the manifest at this time, as described on .nuspec file reference.

  4. Než budete pokračovat, soubor uložte.Save the file before proceeding.

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

  1. Z příkazového řádku ve složce, která obsahuje soubor .nuspec, spusťte příkaz nuget pack.From a command prompt in the folder containing your .nuspec file, run the command nuget pack.

  2. NuGet vygeneruje soubor .nupkg ve formě identifikátor-Version. nupkg, který najdete v aktuální složce.NuGet generates a .nupkg file in the form of identifier-version.nupkg, which you'll find in the current folder.

Publikování balíčkuPublish the package

Až budete mít soubor .nupkg, publikujete ho do nuget.org pomocí nuget.exe s klíčem rozhraní API získaným z nuget.org. Pro nuget.org musíte použít nuget.exe 4.1.0 nebo vyšší.Once you have a .nupkg file, you publish it to nuget.org using nuget.exe with an API key acquired from nuget.org. For nuget.org you must use nuget.exe 4.1.0 or higher.

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í s nabízeným oznámením NuGetPublish with nuget push

  1. Otevřete příkazový řádek a přejděte do složky, která obsahuje soubor .nupkg.Open a command line and change to the folder containing the .nupkg file.

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

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

    Pushing AppLogger.1.0.0.nupkg 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.
    

Viz push NuGet.See 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

Další krokyNext steps

Blahopřejeme k vytvoření prvního balíčku NuGet!Congratulations on creating your first NuGet package!

Pokud chcete prozkoumat další možnosti, které NuGet nabízí, vyberte odkazy níže.To explore more that NuGet has to offer, select the links below.