Vytvoření balíčku NuGet pomocí rozhraní příkazového řádku dotnetCreate a NuGet package using the dotnet CLI

Bez ohledu na to, co váš balíček obsahuje, nebo jaký kód obsahuje, můžete použít jeden z nástrojů rozhraní příkazového řádku, buď nuget.exe nebo dotnet.exe, a zabalit tyto funkce do komponenty, kterou lze sdílet s a používat v jakémkoli počtu jiných vývojářů.No matter what your package does or what code it contains, you use one of the CLI tools, either nuget.exe or dotnet.exe, to package that functionality into a component that can be shared with and used by any number of other developers. Tento článek popisuje, jak vytvořit balíček pomocí rozhraní příkazového řádku dotnet.This article describes how to create a package using the dotnet CLI. Pokud chcete nainstalovat dotnet CLI, přečtěte si téma Instalace nástrojů klienta NuGet.To install the dotnet CLI, see Install NuGet client tools. Počínaje sadou Visual Studio 2017 je rozhraní příkazového řádku dotnet součástí úloh .NET Core.Starting in Visual Studio 2017, the dotnet CLI is included with .NET Core workloads.

Pro projekty .NET Core a .NET Standard, které používají Formát styly sady SDKa všechny další projekty ve stylu sady SDK, nástroj NuGet používá informace v souboru projektu přímo k vytvoření balíčku.For .NET Core and .NET Standard projects that use the SDK-style format, and any other SDK-style projects, NuGet uses information in the project file directly to create a package. Podrobné kurzy najdete v tématech vytváření .NET Standard balíčků pomocí příkazu DOTNET CLI nebo vytváření balíčků .NET Standard pomocí sady Visual Studio.For step-by-step tutorials, see Create .NET Standard Packages with dotnet CLI or Create .NET Standard Packages with Visual Studio.

msbuild -t:pack je funkce ekvivalentní dotnet pack.msbuild -t:pack is functionality equivalent to dotnet pack. Pro sestavení pomocí nástroje MSBuild si přečtěte téma Vytvoření balíčku NuGet pomocí MSBuild.To build with MSBuild, see Create a NuGet package using MSBuild.

Důležité

Toto téma se vztahuje na projekty ve stylu sady SDK , obvykle v projektech .NET Core a .NET Standard.This topic applies to SDK-style projects, typically .NET Core and .NET Standard projects.

Nastavení vlastnostíSet properties

Pro vytvoření balíčku jsou vyžadovány následující vlastnosti.The following properties are required to create a package.

  • PackageId, identifikátor balíčku, který musí být jedinečný v rámci Galerie, která hostuje balíček.PackageId, the package identifier, which must be unique across the gallery that hosts the package. Pokud není zadaný, použije se výchozí hodnota AssemblyName.If not specified, the default value is AssemblyName.
  • Version– konkrétní číslo verze ve formátu hlavní. podverze. Oprava [-přípona] , kde -přípona identifikuje předběžné verze verzí.Version, a specific version number in the form Major.Minor.Patch[-Suffix] where -Suffix identifies pre-release versions. Pokud není zadaný, použije se výchozí hodnota 1.0.0.If not specified, the default value is 1.0.0.
  • Název balíčku, jak by měl být zobrazen na hostiteli (například nuget.org)The package title as it should appear on the host (like nuget.org)
  • Authors, informace o autorovi a vlastníkovi.Authors, author and owner information. Pokud není zadaný, použije se výchozí hodnota AssemblyName.If not specified, the default value is AssemblyName.
  • Companynázev vaší společnosti.Company, your company name. Pokud není zadaný, použije se výchozí hodnota AssemblyName.If not specified, the default value is AssemblyName.

V sadě Visual Studio můžete nastavit tyto hodnoty ve vlastnostech projektu (klikněte pravým tlačítkem myši na projekt v Průzkumník řešení, zvolte vlastnostia vyberte kartu balíček ).In Visual Studio, you can set these values in the project properties (right-click the project in Solution Explorer, choose Properties, and select the Package tab). Tyto vlastnosti lze také nastavit přímo v souborech projektu (.csproj).You can also set these properties directly in the project files (.csproj).

<PropertyGroup>
  <PackageId>AppLogger</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Důležité

Poskytněte balíčku identifikátor, který je jedinečný v rámci nuget.org nebo jakýkoli ze zdrojů balíčku, který používáte.Give the package an identifier that's unique across nuget.org or whatever package source you're using.

Následující příklad ukazuje jednoduchý a kompletní soubor projektu s těmito vlastnostmi, které jsou k dispozici.The following example shows a simple, complete project file with these properties included. (Nový výchozí projekt můžete vytvořit pomocí příkazu dotnet new classlib.)(You can create a new default project using the dotnet new classlib command.)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>AppLogger</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

Můžete také nastavit volitelné vlastnosti, například Title, PackageDescriptiona PackageTags, jak je popsáno v tématu cíle sady MSBuild, řízení prostředků závislostia vlastnosti metadat NuGet.You can also set the optional properties, such as Title, PackageDescription, and PackageTags, as described in MSBuild pack targets, Controlling dependency assets, and NuGet metadata properties.

Poznámka

Pro balíčky sestavené pro veřejnou spotřebu věnujte zvláštní pozornost vlastnosti PackageTags , 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 PackageTags property, as tags help others find your package and understand what it does.

Podrobnosti o deklarování závislostí a zadání čísel verzí naleznete v tématu odkazy na balíčky v souborech projektu a Správa verzí balíčků.For details on declaring dependencies and specifying version numbers, see Package references in project files and Package versioning. Je také možné Surface prostředků ze závislostí přímo v balíčku pomocí atributů <IncludeAssets> a <ExcludeAssets>.It is also possible to surface assets from dependencies directly in the package by using the <IncludeAssets> and <ExcludeAssets> attributes. Další informace najdete v Seee řízení prostředků závislostí.For more information, seee Controlling dependency assets.

Vyberte jedinečný identifikátor balíčku a nastavte číslo verze.Choose a unique package identifier and set the version number

Identifikátor balíčku a číslo verze jsou dvě nejdůležitější hodnoty v projektu, protože jednoznačně identifikují přesný kód obsažený v balíčku.The package identifier and the version number are the two most important values in the project because they uniquely identify the exact code that's contained in the package.

Osvědčené postupy pro identifikátor balíčku:Best practices for the package identifier:

  • Jedinečnost: identifikátor musí být jedinečný v rámci NuGet.org nebo bez ohledu na to, jakou galerii hostují balíček.Uniqueness: The identifier must be unique across nuget.org or whatever gallery hosts the package. Než se rozhodnete pro identifikátor, vyhledejte příslušnou galerii a ověřte, jestli se tento název už používá.Before deciding on an identifier, search the applicable gallery to check if the name is already in use. Aby nedocházelo ke konfliktům, dobrým vzorem je použít název vaší společnosti jako první část identifikátoru, například Contoso..To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as Contoso..
  • Obor názvů jako názvy: Sledujte vzor podobný oborům názvů v rozhraní .NET pomocí notace tečky namísto spojovníků.Namespace-like names: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. Použijte například Contoso.Utility.UsefulStuff místo Contoso-Utility-UsefulStuff nebo Contoso_Utility_UsefulStuff.For example, use Contoso.Utility.UsefulStuff rather than Contoso-Utility-UsefulStuff or Contoso_Utility_UsefulStuff. Příjemci také naleznou užitečné, pokud se identifikátor balíčku shoduje s obory názvů použitými v kódu.Consumers also find it helpful when the package identifier matches the namespaces used in the code.
  • Ukázkové balíčky: Pokud vytváříte balíček ukázkového kódu, který ukazuje, jak použít jiný balíček, připojte .Sample jako příponu k identifikátoru, jako v Contoso.Utility.UsefulStuff.Sample.Sample Packages: If you produce a package of sample code that demonstrates how to use another package, attach .Sample as a suffix to the identifier, as in Contoso.Utility.UsefulStuff.Sample. (Vzorový balíček samozřejmě má závislost na druhém balíčku.) Při vytváření ukázkového balíčku použijte hodnotu contentFiles v <IncludeAssets>.(The sample package would of course have a dependency on the other package.) When creating a sample package, use the contentFiles value in <IncludeAssets>. Ve složce content uspořádejte vzorový kód do složky s názvem \Samples\<identifier> jako v \Samples\Contoso.Utility.UsefulStuff.Sample.In the content folder, arrange the sample code in a folder called \Samples\<identifier> as in \Samples\Contoso.Utility.UsefulStuff.Sample.

Osvědčené postupy pro verzi balíčku:Best practices for the package version:

  • Obecně platí, že nastavte verzi balíčku tak, aby odpovídala projektu (nebo sestavení), i když to není bezpodmínečně nutné.In general, set the version of the package to match the project (or assembly), though this is not strictly required. Toto je jednoduchá skutečnost při omezení balíčku na jediné sestavení.This is a simple matter when you limit a package to a single assembly. Celkově mějte na paměti, že aplikace NuGet pracuje s verzemi balíčku při řešení závislostí, nikoli ve verzích sestavení.Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions.
  • Při použití nestandardního schématu verzí nezapomeňte zvážit pravidla správy verzí NuGet, jak je vysvětleno v tématu Správa verzí balíčků.When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in Package versioning. NuGet je většinou kompatibilní s semver 2.NuGet is mostly semver 2 compliant.

Informace o řešení závislostí najdete v tématu věnovaném řešení závislostí s PackageReference.For information on dependency resolution, see Dependency resolution with PackageReference. Starší informace, které mohou být užitečné také pro lepší pochopení správy verzí, najdete v této sérii příspěvků na blogu.For older information that may also be helpful to better understand versioning, see this series of blog posts.

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

Chcete-li vytvořit balíček NuGet (.nupkg soubor) z projektu, spusťte příkaz dotnet pack, který také automaticky vytvoří projekt:To build a NuGet package (a .nupkg file) from the project, run the dotnet pack command, which also builds the project automatically:

# Uses the project file in the current folder by default
dotnet pack

Výstup zobrazuje cestu k souboru .nupkg.The output shows the path to the .nupkg file.

Microsoft (R) Build Engine version 15.5.180.51428 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 29.91 ms for D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj.
  AppLogger -> D:\proj\AppLoggerNet\AppLogger\bin\Debug\netstandard2.0\AppLogger.dll
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Automaticky generovat balíček při sestaveníAutomatically generate package on build

Chcete-li automaticky spouštět dotnet pack při spuštění dotnet build, přidejte do souboru projektu v rámci <PropertyGroup>následující řádek:To automatically run dotnet pack when you run dotnet build, add the following line to your project file within <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Když spustíte dotnet pack v řešení, budou všechny projekty v řešení, které lze zabalit (vlastnost nastavená na true).When you run dotnet pack on a solution, this packs all the projects in the solution that are packable ( property is set to true).

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.

Instalace testovacího balíčkuTest package installation

Před publikováním balíčku obvykle budete chtít otestovat proces instalace balíčku do projektu.Before publishing a package, you typically want to test the process of installing a package into a project. Testy zajistí, že všechny soubory v projektu budou mít všechny na správném místě.The tests make sure that the necessarily files all end up in their correct places in the project.

Instalaci můžete v aplikaci Visual Studio nebo na příkazovém řádku otestovat ručně pomocí kroků normální instalace balíčku.You can test installations manually in Visual Studio or on the command line using the normal package installation steps.

Důležité

Balíčky jsou neměnné.Packages are immutable. Pokud problém opravíte, znovu ho změňte a znovu spusťte. při opětovném testování bude stále použita stará verze balíčku, dokud nevymažete složku globálních balíčků .If you correct a problem, change the contents of the package and pack again, when you retest you will still be using the old version of the package until you clear your global packages folder. To je obzvláště důležité při testování balíčků, které nepoužívají jedinečný popisek předprodejní verze pro každé sestavení.This is especially relevant when testing packages that don't use a unique prerelease label on every build.

Další krokyNext Steps

Po vytvoření balíčku, který je .nupkg soubor, ho můžete publikovat do Galerie podle svého výběru, jak je popsáno v tématu publikování balíčku.Once you've created a package, which is a .nupkg file, you can publish it to the gallery of your choice as described on Publishing a Package.

Můžete také chtít zvětšit možnosti vašeho balíčku nebo jinak podporovat jiné scénáře, jak je popsáno v následujících tématech:You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:

Nakonec existují další typy balíčků, o kterých byste měli vědět:Finally, there are additional package types to be aware of: