Publish C# Project to Nuget.org
Using NuGet packages and nuget.org are a great way to share our .NET projects with other developers and also distribute your code across multiple projects.
In this guide, we'll walk through the process of publishing an existing .NET project as a NuGet package on NuGet.org. Let's use the Rmauro.Extensions.Configuration.EnvFiles
project as an example, which is hosted on GitHub.
Prepare the Project for Packaging
Let's start by cloning the project or using DevContainers to edit in Github Cloud (as demonstrated here Create and Configure a GitHub Codespace
# clones the project
> git clone https://github.com/ricardodemauro/Rmauro.Extensions.Configuration.EnvFiles.git
> cd Rmauro.Extensions.Configuration.EnvFiles
Open the Rmauro.Extensions.Configuration.Env.csproj
file and include the necessary NuGet package metadata.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<!--Starts here-->
<PackageId>Rmauro.Extensions.Configuration.EnvFiles</PackageId>
<PackageVersion>1.0.0</Version>
<Authors>Ricardo Mauro</Authors>
<Description>Extension to read .env files in dotnet core projects</Description>
<RepositoryUrl>https://github.com/ricardodemauro/Rmauro.Extensions.Configuration.EnvFiles.git</RepositoryUrl>
<PackageIconUrl>rmauro-favico-32.png</PackageIconUrl>
<PackageIcon>rmauro-favico-32.png</PackageIcon>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<RequireLicenseAcceptance>false</RequireLicenseAcceptance>
<!--Ends here-->
</PropertyGroup>
<!--https://stackoverflow.com/a/76122058/1652594-->
<ItemGroup>
<None Include="../../assets/rmauro-favico-32.png" Pack="true" PackagePath=""/>
</ItemGroup>
</Project>
Properties Definition
PackageId
Specifies the name for the resulting packagePackageVersion
This is semver compatible, for example 1.0.0, 1.0.0-beta, or 1.0.0-beta-00345. Defaults to Version if not setAuthors
A semicolon-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authorsDescription
A long description for the assembly. If PackageDescription is not specified, then this property is also used as the description of the packageRepositoryUrl
Repository URL used to clone or retrieve source code.PackageIconUrl
PackageIconUrl is deprecated in favor of PackageIcon. However, for the best downlevel experience, you should specify PackageIconUrl in addition to PackageIconPackageIcon
Specifies the package icon path, relative to the root of the packagePackageLicenseExpression
Corresponds to license expression. Read moreRequireLicenseAcceptance
A Boolean value that specifies whether the client must prompt the consumer to accept the package license before installing the package.
For more properties read the Microsoft's Official Docs: https://learn.microsoft.com/en-us/nuget/reference/msbuild-targets#pack-target
Tip: If you need to include Icon, you need to first import into the project by using
<ItemGroup>
and<None>
tags and then use it.
Pack the NuGet Package
All set with our project, let's create the NuGet package.
Navigate to the project directory containing the .csproj
file and run the following command.
# build the package and sets the version to 0.0.1
> dotnet build -c Release /p:Version=0.0.1
# packs the package
> dotnet pack --configuration Release
This command will generate a .nupkg
file in the bin/Release
directory.
Auto Generate the Package on Build
Include the following property to auto generate the package.
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
Create a NuGet.org Account and Get an API Key
Before you can publish your package, we need a NuGet.org account and an API key.
Go to NuGet.org and click "Sign in" in the top right corner.
- Click "Create a new account" if you don't have one. You can sign up using a Microsoft account or create a new account with your email.
- Follow the prompts to complete your registration, including email verification.
Generate an API Key
Once logged in, click on your username in the top right corner and select "API Keys".
Click "Create" to generate a new API key.
Provide a name for your key (e.g., "MyAwesomeLibrary Publishing Key").
Choose the scope for the key:
- "Push new packages and package versions" if you're only publishing.
- "Push and unlist packages" if you also want the ability to unlist packages.
Select the glob pattern for the packages this key can push. Use *
for all packages or specify package names. Then click "Create".
Copy the generated API Key.
Remember to keep your API key confidential. Never share it or commit it to source control.
Publish to NuGet.org
Now that you have your API key, you can publish your package:
- Use the following command to publish your package, replacing
your_api_key
with your actual API key:
> dotnet nuget push `
bin/Release/Rmauro.Extensions.Configuration.EnvFiles.1.0.0.nupkg `
--api-key your_api_key `
--source https://api.nuget.org/v3/index.json
NuGet.org will process our package. It usually takes a few minutes to be available.
Here is our package: https://www.nuget.org/packages/Rmauro.Extensions.Configuration.Env/
Updating Your Package
When you make changes to your project and want increment the published version.
- Build using the
/p:Version=0.0.0.2
parameter or simply increment the<Version>
number in your.csproj
file - Repackage and publish again
> dotnet build -c Release /p:Version=0.0.0.2
> dotnet pack --configuration Release
> dotnet nuget push `
bin/Release/Rmauro.Extensions.Configuration.EnvFiles.0.0.2.nupkg `
--api-key {NUGET_API_KEY} `
--source https://api.nuget.org/v3/index.json
Best Practices for Maintaining Your NuGet Package
- Create/Update the README.md file in the nuget.org website
- Use semantic versioning (MAJOR.MINOR.PATCH) to communicate the nature of updates
- Regularly check for and update any dependencies in your project
- Keep your code updated and secure against know treats
- Rotate your API keys periodically for security
Conclusion
Publishing your existing .NET project as a NuGet package is a great way to share your work with the broader .NET community.
By following these steps, you've made your Rmauro.Extensions.Configuration.EnvFiles
library easily accessible to other developers.
Happy packaging!!