Erstellen eines NuGet-Pakets mithilfe der dotnet-CLICreate a NuGet package using the dotnet CLI

Unabhängig davon, welchen Zweck Ihr Paket erfüllt oder welchen Code es enthält, verwenden Sie eines der CLI-Tools (entweder nuget.exe oder dotnet.exe), um diese Funktionalität in einer Komponente zu verpacken, die für andere Entwickler freigegeben und von ihnen verwendet werden kann.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. In diesem Artikel wird das Erstellen eines Pakets mithilfe der dotnet-CLI beschrieben.This article describes how to create a package using the dotnet CLI. Informationen zur Installation der dotnet-CLI finden Sie unter Installieren von NuGet-Clienttools.To install the dotnet CLI, see Install NuGet client tools. Ab Visual Studio 2017 ist die dotnet-CLI in .NET Core-Workloads enthalten.Starting in Visual Studio 2017, the dotnet CLI is included with .NET Core workloads.

Für .NET Core- und .NET Standard-Projekte, die das SDK-Format verwenden, und für alle anderen Projekte im SDK-Format verwendet NuGet Informationen in der Projektdatei direkt zum Erstellen eines Pakets.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. Schritt-für-Schritt-Tutorials finden Sie unter Erstellen von .NET Standard-Paketen mit der dotnet-CLI und Erstellen von .NET Standard-Paketen mit 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 ist funktionell gleichwertig mit dotnet pack.msbuild -t:pack is functionality equivalent to dotnet pack. Informationen zum Erstellen mit MSBuild finden Sie unter Erstellen eines NuGet-Pakets mit MSBuild.To build with MSBuild, see Create a NuGet package using MSBuild.

Wichtig

Dieses Thema bezieht sich auf Projekte im SDK-Stil, in der Regel .NET Core- und .NET Standard-Projekte.This topic applies to SDK-style projects, typically .NET Core and .NET Standard projects.

Eigenschaften festlegenSet properties

Die folgenden Eigenschaften sind für die Erstellung eines Pakets erforderlich.The following properties are required to create a package.

  • PackageId, der Paketbezeichner. Dieser muss im Katalog, der das Paket hostet, eindeutig sein.PackageId, the package identifier, which must be unique across the gallery that hosts the package. Wenn Sie hier nichts angeben, lautet der Standardwert AssemblyName.If not specified, the default value is AssemblyName.
  • Version, eine bestimmte Versionsnummer in der Schreibweise Hauptversion.Nebenversion.Patch[-Suffix] , wobei im -Suffix die Vorabversionen angegeben werden.Version, a specific version number in the form Major.Minor.Patch[-Suffix] where -Suffix identifies pre-release versions. Wenn Sie hier nichts angeben, lautet der Standardwert 1.0.0.If not specified, the default value is 1.0.0.
  • Der Titel des Pakets, so wie er auf dem Host (z.B. „nuget.org“) angezeigt werden sollteThe package title as it should appear on the host (like nuget.org)
  • Authors, Informationen zum Autor und Besitzer.Authors, author and owner information. Wenn Sie hier nichts angeben, lautet der Standardwert AssemblyName.If not specified, the default value is AssemblyName.
  • Company, der Firmenname.Company, your company name. Wenn Sie hier nichts angeben, lautet der Standardwert AssemblyName.If not specified, the default value is AssemblyName.

In Visual Studio können Sie diese Werte in den Projekteigenschaften festlegen (Rechtsklick auf das Projekt im Projektmappen-Explorer, wählen Sie Eigenschaften und dann die Registerkarte Paket aus).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). Sie können diese Eigenschaften auch direkt in den Projektdateien festlegen (.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>

Wichtig

Weisen Sie dem Paket einen Bezeichner zu, der auf nuget.org bzw. in der Paketquelle, den Sie verwenden, einzigartig ist.Give the package an identifier that's unique across nuget.org or whatever package source you're using.

Das folgende Beispiel zeigt eine einfache, vollständige Projektdatei, in der diese Eigenschaften enthalten sind.The following example shows a simple, complete project file with these properties included. (Sie können ein neues Standardprojekt mit dem Befehl dotnet new classlib erstellen.)(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>

Sie können auch die optionalen Eigenschaften wie Title, PackageDescription und PackageTags festlegen, wie in MSBuild-Paketziele, Steuern von Abhängigkeitsobjekten und NuGet-Metadateneigenschaften beschrieben.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.

Hinweis

Bei Paketen für die öffentliche Nutzung sollten Sie besonders auf die PackageTags-Eigenschaft achten, da Tags anderen dabei helfen, Ihr Paket zu finden und dessen Funktion zu verstehen.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.

Weitere Informationen zum Deklarieren von Abhängigkeiten und zum Angeben von Versionsnummern finden Sie unter Paketverweise in Projektdateien und Paketversionsverwaltung.For details on declaring dependencies and specifying version numbers, see Package references in project files and Package versioning. Es ist auch möglich, Ressourcen aus Abhängigkeiten mithilfe der Attribute <IncludeAssets> und <ExcludeAssets> direkt im Paket verfügbar zu machen.It is also possible to surface assets from dependencies directly in the package by using the <IncludeAssets> and <ExcludeAssets> attributes. Weitere Informationen finden Sie unter Steuern von Abhängigkeitsobjekten.For more information, seee Controlling dependency assets.

Hinzufügen eines optionalen BeschreibungsfeldsAdd an optional description field

Die optionale Beschreibung des Pakets, die auf der Seite NuGet.org des Pakets angezeigt wird, wird entweder aus der <description></description> abgerufen, die in der .csproj-Datei verwendet wird, oder sie wird über die $description in der .nuspec-Datei abgerufen.The package's optional description, displayed on the package's NuGet.org page, is either pulled in from the <description></description> used in the .csproj file or pulled in via the $description in the .nuspec file.

Der folgende XML-Text der .csproj-Datei für ein .NET-Paket zeigt ein Beispiel für ein Feld Beschreibung:An example of a description field is shown in the following XML text of the .csproj file for a .NET package:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://docs.microsoft.com/en-us/azure/storage/
      Microsoft Azure Storage REST API Reference - https://docs.microsoft.com/en-us/rest/api/storageservices/
      REST API Reference for Blob Service - https://docs.microsoft.com/en-us/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</PropertyGroup>

Auswählen eines eindeutigen Paketbezeichners und Festlegen der VersionsnummerChoose a unique package identifier and set the version number

Der Paketbezeichner und die Versionsnummer sind die beiden wichtigsten Werte im Projekt, da sie eindeutig den exakten Code bezeichnen, der im Paket enthalten ist.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.

Bewährte Methoden für den Paketbezeichner:Best practices for the package identifier:

  • Eindeutigkeit: Der Bezeichner muss auf „nuget.org“ bzw. in dem Katalog, in dem das Paket gehostet wird, eindeutig sein.Uniqueness: The identifier must be unique across nuget.org or whatever gallery hosts the package. Bevor Sie sich für einen Bezeichner entscheiden, vergewissern Sie sich, dass dieser im entsprechenden Katalog nicht bereits verwendet wird.Before deciding on an identifier, search the applicable gallery to check if the name is already in use. Zur Vermeidung von Konflikten empfiehlt es sich, den Namen Ihres Unternehmens im ersten Teil des Bezeichners zu nutzen, z.B. Contoso..To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as Contoso..
  • Namespace-ähnliche Namen: Verwenden Sie Punkte statt Bindestrichen, wie bei der Notation von Namespaces in .NET.Namespace-like names: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. Schreiben Sie z.B. Contoso.Utility.UsefulStuff statt Contoso-Utility-UsefulStuff oder Contoso_Utility_UsefulStuff.For example, use Contoso.Utility.UsefulStuff rather than Contoso-Utility-UsefulStuff or Contoso_Utility_UsefulStuff. Benutzer finden es auch hilfreich, wenn der Paketbezeichner den im Code verwendeten Namespaces entspricht.Consumers also find it helpful when the package identifier matches the namespaces used in the code.
  • Beispielpakete: Wenn Sie ein Paket mit Beispielcode erstellen, das veranschaulicht, wie ein anderes Paket verwendet wird, fügen Sie .Sample als Suffix an den Bezeichner an, z. B. 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. Das Beispielpaket würde natürlich vom anderen Paket abhängen. Wenn Sie ein Beispielpaket erstellen, verwenden Sie den contentFiles-Wert in <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>. Arrangieren Sie den Beispielcode im Ordner content in einem Ordner namens \Samples\<identifier>, z.B. \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.

Bewährte Methoden für die Paketversion:Best practices for the package version:

  • Legen Sie die Version des Pakets auf die des Projekts (der Assembly) fest, obwohl dies nicht zwingend erforderlich ist.In general, set the version of the package to match the project (or assembly), though this is not strictly required. Dies ist eine einfache Sache, wenn Sie ein Paket auf eine einzelne Assembly beschränken.This is a simple matter when you limit a package to a single assembly. Bedenken Sie, dass NuGet sich beim Auflösen der Abhängigkeiten nach den Paketversionen richtet, nicht nach den Assemblyversionen.Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions.
  • Wenn Sie ein nicht standardmäßiges Versionsschema verwenden, müssen Sie die NuGet-Versionsregeln wie unter Package versioning (Paketversionsverwaltung beschrieben anwenden.When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in Package versioning. NuGet ist größtenteils semver 2-kompatibel.NuGet is mostly semver 2 compliant.

Weitere Informationen zur Abhängigkeitsauflösung finden Sie unter Abhängigkeitsauflösung mit PackageReference.For information on dependency resolution, see Dependency resolution with PackageReference. Ältere Informationen, die möglicherweise auch hilfreich sein können, um die Versionierung besser zu verstehen, finden Sie in dieser Reihe von Blog-Einträgen.For older information that may also be helpful to better understand versioning, see this series of blog posts.

Ausführen des Befehls packRun the pack command

Um ein NuGet-Paket (eine .nupkg-Datei) aus dem Projekt zu erstellen, führen Sie den dotnet pack-Befehl aus, der auch das Projekt automatisch erstellt: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

Die Ausgabe zeigt den Pfad zur .nupkg-Datei.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'.

Automatisches Generieren des Pakets bei der ErstellungAutomatically generate package on build

Um automatisch dotnet pack auszuführen, wenn Sie dotnet build ausführen, fügen Sie folgende Zeile zu Ihrer Projektdatei in <PropertyGroup> hinzu:To automatically run dotnet pack when you run dotnet build, add the following line to your project file within <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Wenn Sie dotnet pack für eine Lösung ausführen, werden alle Projekte in der Lösung verpackt, die verpackt werden können (die Eigenschaft wird auf true festgelegt).When you run dotnet pack on a solution, this packs all the projects in the solution that are packable ( property is set to true).

Hinweis

Wenn Sie das Paket automatisch generieren, erhöht die Zeit zum Verpacken die Erstellungszeit für Ihr Projekt.When you automatically generate the package, the time to pack increases the build time for your project.

Testen der PaketinstallationTest package installation

Vor dem Veröffentlichen eines Pakets testen Sie in der Regel die Installation eines Pakets in einem Projekt.Before publishing a package, you typically want to test the process of installing a package into a project. Diese Tests stellen sicher, dass die erforderlichen Dateien an den richtigen Orten im Projekt installiert werden.The tests make sure that the necessarily files all end up in their correct places in the project.

Installationen lassen sich manuell in Visual Studio oder mithilfe der normalen Paketinstallationsschritte über die Befehlszeile testen.You can test installations manually in Visual Studio or on the command line using the normal package installation steps.

Wichtig

Pakete sind unveränderlich.Packages are immutable. Wenn Sie ein Problem beheben, ändern Sie den Inhalt des Pakets und verpacken Sie es erneut. Wenn Sie es erneut testen, verwenden Sie weiterhin die alte Version des Pakets, bis Sie Ihren Ordner für globale Pakete löschen.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. Dies ist besonders relevant, wenn Sie Pakete testen, die nicht bei jedem Build eine eindeutige Vorabversionsbezeichnung verwenden.This is especially relevant when testing packages that don't use a unique prerelease label on every build.

Nächste SchritteNext Steps

Nachdem Sie ein Paket erstellt haben, das eine .nupkg-Datei ist, können Sie sie wie unter Publishing packages (Veröffentlichen von Paketen) beschrieben im Katalog Ihrer Wahl veröffentlichen.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.

Sie können auch die Funktionen des Pakets erweitern oder wie in den folgenden Themen beschrieben andere Szenarios unterstützen:You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:

Außerdem sollten Sie die folgenden zusätzlichen Pakettypen berücksichtigen:Finally, there are additional package types to be aware of: