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 package
• PackageVersion This is semver compatible, for example 1.0.0, 1.0.0-beta, or 1.0.0-beta-00345. Defaults to Version if not set
• Authors 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 authors
• Description A long description for the assembly. If PackageDescription is not specified, then this property is also used as the description of the package
• RepositoryUrl 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 PackageIcon
• PackageIcon Specifies the package icon path, relative to the root of the package
• PackageLicenseExpression Corresponds to license expression. Read more
• RequireLicenseAcceptance 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:

1. 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.

1. Build using the /p:Version=0.0.0.2 parameter or simply increment the <Version> number in your .csproj file
2. 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!!