Vytvoření balíčku NuGet pomocí nástroje MSBuildCreate a NuGet package using MSBuild

Když vytvoříte balíček NuGet z kódu, zabalíte tuto funkci do komponenty, kterou můžete sdílet s a používat v jakémkoli počtu jiných vývojářů.When you create a NuGet package from your code, you 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í nástroje MSBuild.This article describes how to create a package using MSBuild. Nástroj MSBuild přináší předinstalované všechny úlohy sady Visual Studio, které obsahují NuGet.MSBuild comes preinstalled with every Visual Studio workload that contains NuGet. Kromě toho můžete také použít MSBuild prostřednictvím rozhraní příkazového řádku dotnet s nástrojem dotnet MSBuild.Additionally you can also use MSBuild through the dotnet CLI with dotnet msbuild.

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. Pro projekt bez sady SDK, který používá <PackageReference> používá nástroj NuGet také soubor projektu k vytvoření balíčku.For a non-SDK-style project that uses <PackageReference>, NuGet also uses the project file to create a package.

Projekty ve stylu sady SDK mají ve výchozím nastavení dostupné funkce balíčku.SDK-style projects have the pack functionality available by default. Pro projekty PackageReference bez sady SDK je nutné přidat balíček NuGet. Build. Tasks. Pack do závislostí projektu.For non SDK-style PackageReference projects, you need to add the NuGet.Build.Tasks.Pack package to the project dependencies. Podrobné informace o cílech sady MSBuild Pack naleznete v tématu sada NuGet Pack a obnovení jako cíle MSBuild.For detailed information about MSBuild pack targets, see NuGet pack and restore as MSBuild targets.

Příkaz, který vytváří balíček, msbuild -t:pack, je funkce ekvivalentní dotnet pack.The command that creates a package, msbuild -t:pack, is functionality equivalent to dotnet pack.

Důležité

Toto téma se vztahuje na projekty ve stylu sady SDK , obvykle v projektech .NET Core a .NET Standard a na projekty ve stylu jiné než SDK, které používají PackageReference.This topic applies to SDK-style projects, typically .NET Core and .NET Standard projects, and to non-SDK-style projects that use PackageReference.

Nastavit vlastnostiSet 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í zadán, výchozí hodnota je 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í zadán, výchozí hodnota je AssemblyName.If not specified, the default value is AssemblyName.
  • Companynázev vaší společnosti.Company, your company name. Pokud není zadán, výchozí hodnota je 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>ClassLibDotNetStandard</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.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</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, PackageDescription a 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.

Přidat balíček NuGet. Build. Tasks. PackAdd the NuGet.Build.Tasks.Pack package

Pokud používáte nástroj MSBuild s projektem a PackageReference, který není typu SDK, přidejte do projektu balíček NuGet. Build. Tasks. Pack.If you are using MSBuild with a non-SDK-style project and PackageReference, add the NuGet.Build.Tasks.Pack package to your project.

  1. Otevřete soubor projektu a přidejte následující za <PropertyGroup> elementu:Open the project file and add the following after the <PropertyGroup> element:

    <ItemGroup>
      <!-- ... -->
      <PackageReference Include="NuGet.Build.Tasks.Pack" Version="5.2.0"/>
      <!-- ... -->
    </ItemGroup>
    
  2. Otevřete příkazový řádek pro vývojáře (do vyhledávacího pole zadejte příkaz Developer Command Prompt).Open a Developer command prompt (In the Search box, type Developer command prompt).

    Obvykle chcete spustit Developer Command Prompt pro Visual Studio z nabídky Start , jak bude nakonfigurován 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.

  3. Přepněte do složky obsahující soubor projektu a zadejte následující příkaz pro instalaci balíčku NuGet. Build. Tasks. Pack.Switch to the folder containing the project file and type the following command to install the NuGet.Build.Tasks.Pack package.

    # Uses the project file in the current folder by default
    msbuild -t:restore
    

    Ujistěte se, že výstup nástroje MSBuild označuje, že sestavení bylo úspěšně dokončeno.Make sure that the MSBuild output indicates that the build completed successfully.

Spuštění příkazu MSBuild-t:PackRun the msbuild -t:pack command

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

Do příkazového řádku pro vývojáře pro Visual Studio zadejte následující příkaz:In the Developer command prompt for Visual Studio, type the following command:

# Uses the project file in the current folder by default
msbuild -t:pack

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

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

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

Chcete-li automaticky spustit msbuild -t:pack při sestavování nebo obnovování projektu, přidejte následující řádek do souboru projektu v rámci <PropertyGroup>:To automatically run msbuild -t:pack when you build or restore the project, add the following line to your project file within <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Když na řešení spustíte msbuild -t:pack, jsou všechny projekty v řešení, které jsou packné (vlastnost ) nastavené na hodnotu true).When you run msbuild -t: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 soubor .nupkg, 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: