How to create nuget package

21.08.202221.08.2022 admin 0 Comments how, how to made, как, как сделать, как создать, совими руками

How to create nuget package

Create a package using the nuget.exe CLI

Packaging begins with the compiled code (assemblies), symbols, and/or other files that you want to deliver as a package (see Overview and workflow). This process is independent from compiling or otherwise generating the files that go into the package, although you can draw from information in a project file to keep the compiled assemblies and packages in sync.

Decide which assemblies to package

Most general-purpose packages contain one or more assemblies that other developers can use in their own projects.

If your library contains COM interop assemblies, follow additional the guidelines in Create packages with COM interop assemblies.

Common optional properties:

Because the manifest is included in the package created from it, you can find any number of additional examples by examining existing packages. A good source is the global-packages folder on your computer, the location of which is returned by the following command:

You then edit the file by hand so that it describes the exact content you want in the final package.

From a convention-based working directory

The advantage to this approach is that you don’t need to specify in the manifest which files you want to include in the package (as explained later in this topic). You can simply have your build process produce the exact folder structure that goes into the package, and you can easily include other files that might not be part of a project otherwise:

The folder conventions are as follows:

Because your folder structure can contain any number of assemblies for any number of target frameworks, this method is necessary when creating packages that support multiple frameworks.

From an assembly DLL

Using this form replaces a few placeholders in the manifest with specific values from the assembly. For example, the property is set to the assembly name, and is set to the assembly version. Other properties in the manifest, however, don’t have matching values in the assembly and thus still contain placeholders.

From a Visual Studio project

.nuspec file contains tokens that are replaced at packaging time with values from the project, including references to any other packages that have already been installed.

Solution-level packages

NuGet 2.x only. Not available in NuGet 3.0+.

New file with default values

The following command creates a default manifest with placeholders, which ensures you start with the proper file structure:

Choose a unique package identifier and setting the version number

The package identifier ( element) and the version number ( element) are the two most important values in the manifest because they uniquely identify the exact code that’s contained in the package.

Best practices for the package identifier:

Best practices for the package version:

The following series of brief blog posts are also helpful to understand versioning:

Add a readme and other files

When using the convention-based working directory approach, you can place the readme.txt in the package root and other content in the content folder. No elements are necessary in the manifest.

When you include a file named readme.txt in the package root, Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Readme files are not displayed for packages installed as dependencies). For example, here’s how the readme for the HtmlAgilityPack package appears:

Include MSBuild props and targets in a package

In some cases, you might want to add custom build targets or properties in projects that consume your package, such as running a custom tool or process during build. You can learn more about MSBuild props and targets in NuGet packages

.props (such as Contoso.Utility.UsefulStuff.targets ) within the build folders of the project.

When packages are added to a project, NuGet will automatically include these props and targets.

with your specific filename:

Additional options

You can use various command-line switches with nuget pack to exclude files, override the version number in the manifest, and change the output folder, among other features. For a complete list, refer to the pack command reference.

The following options are a few that are common with Visual Studio projects:

This inclusion process is recursive, so if MyProject.csproj references projects B and C, and those projects reference D, E, and F, then files from B, C, D, E, and F are included in the package.

Test package installation

Before publishing a package, you typically want to test the process of installing a package into a project. The tests make sure that the necessarily files all end up in their correct places in the project.

You can test installations manually in Visual Studio or on the command line using the normal package installation steps.

For automated testing, the basic process is as follows:

Next Steps

You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:

Finally, there are additional package types to be aware of:

Quickstart: Create and publish a NuGet package using Visual Studio (.NET Standard, Windows only)

If you are using Visual Studio for Mac, refer to this information on creating a NuGet package, or use the dotnet CLI tools.

Prerequisites

If it’s not already installed, install the dotnet CLI.

Register for a free account on nuget.org if you don’t have one already. Creating a new account sends a confirmation email. You must confirm the account before you can upload a package.

Create a class library project

Right-click on the resulting project file and select Build to make sure the project was created properly. The DLL is found within the Debug folder (or Release if you build that configuration instead).

Within a real NuGet package, of course, you implement many useful features with which others can build applications. For this walkthrough, however, you won’t write any additional code because a class library from the template is sufficient to create a package. Still, if you’d like some functional code for the package, use the following:

Configure package properties

Right-click the project in Solution Explorer, and choose Properties menu command, then select the Package tab.

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.

You must give the package an identifier that’s unique across nuget.org or whatever host you’re using. 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).

If you attempt to publish a package with a name that already exists, you see an error.

(Optional) To see the properties directly in the project file, right-click the project in Solution Explorer and select Edit AppLogger.csproj.

This option is only available starting in Visual Studio 2017 for projects that use the SDK-style attribute. Otherwise, right-click the project and choose Unload Project. Then right-click the unloaded project and choose Edit AppLogger.csproj.

Run the pack command

Set the configuration to Release.

Right click the project in Solution Explorer and select the Pack command:

(Optional) Generate package on build

You can configure Visual Studio to automatically generate the NuGet package when you build the project.

In Solution Explorer, right-click the project and choose Properties.

In the Package tab, select Generate NuGet package on build.

When you automatically generate the package, the time to pack increases the build time for your project.

(Optional) pack with MSBuild

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. Open a command prompt, navigate to your project folder and run the following command. (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.)

Publish the package

Virus scanning: All packages uploaded to nuget.org are scanned for viruses and rejected if any viruses are found. All packages listed on nuget.org are also scanned periodically.

Packages published to nuget.org are also publicly visible to other developers unless you unlist them. To host packages privately, see Hosting packages.

Acquire your API key

Sign into your nuget.org account or create an account if you don’t have one already.

For more information on creating your account, see Individual accounts.

Select your user name (on the upper right), then select API Keys.

Select Create, provide a name for your key, select Select Scopes > Push. Enter * for Glob pattern, then select Create. (See below for more about scopes.)

Once the key is created, select Copy to retrieve the access key you need in the CLI:

Always keep your API key a secret! Treat your API key as a password that allows anyone to manage packages on your behalf. You should delete or regenerate your API key if it is accidentally revealed.

Save your key in a secure location because you cannot copy the key again later on. If you return to the API key page, you need to regenerate the key to copy it. You can also remove the API key if you no longer want to push packages.

Scoping allows you to create separate API keys for different purposes. Each key has its expiration timeframe and can be scoped to specific packages (or glob patterns). Each key is also scoped to specific operations: push of new packages and updates, push of updates only, or delisting. 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. For more information, see scoped API keys.

Publish with the dotnet CLI or nuget.exe CLI

Select the tab for your CLI tool, either .NET Core CLI (dotnet CLI) or NuGet (nuget.exe CLI).

Before you can publish the package, you must first open a command line.

Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:

dotnet displays the results of the publishing process:

Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:

nuget.exe displays the results of the publishing process:

Publish errors

Errors from the push command typically indicate the problem. 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.

You also see errors when trying to publish a package using an identifier that already exists on the host. The name «AppLogger», for example, already exists. In such a case, the push command gives the following error:

Manage the published package

From your profile on nuget.org, select Manage Packages to see the one you just published. You also receive a confirmation email. Note that it might take a while for your package to be indexed and appear in search results where others can find it. During that time your package page shows the message below:

And that’s it! You’ve just published your first NuGet package to nuget.org that other developers can use in their own projects.

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:

On nuget.org, select your user name (upper right of the page), then select Manage Packages.

Locate the package you want to unlist under Published and select the trash can icon on the right:

On the subsequent page, clear the box labeled List (package-name) in search results and select Save:

Adding a readme and other files

To directly specify files to include in the package, edit the project file and use the content property:

This will include a file named readme.txt in the package root. Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Readme files are not displayed for packages installed as dependencies). For example, here’s how the readme for the HtmlAgilityPack package appears:

Merely adding the readme.txt at the project root will not result in it being included in the resulting package.

Create a NuGet package using the dotnet CLI

Set properties

The following properties are required to create a package.

Give the package an identifier that’s unique across nuget.org or whatever package source you’re using.

The following example shows a simple, complete project file with these properties included. (You can create a new default project using the dotnet new classlib command.)

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.

For details on declaring dependencies and specifying version numbers, see Package references in project files and Package versioning. It is also possible to surface assets from dependencies directly in the package by using the and attributes. For more information, see Controlling dependency assets.

Add an optional description field

Choose a unique package identifier and set the version number

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.

Best practices for the package identifier:

Best practices for the package version:

For information on dependency resolution, see Dependency resolution with PackageReference. For older information that may also be helpful to better understand versioning, see this series of blog posts.

Run the pack command