Introduction

Publishing a .NET library on NuGet.org is not just packing a project and sending the .nupkg to the server. The most important point is treating the public API as a contract that other people and other teams will consume. If I publish an API without thinking about compatibility, the problem does not stay in the package: it spreads to dependencies, pipelines and applications that depend on the same assembly. That is why safe publishing combines three pillars: a stable contract, deliberate versioning and real validation of the artifact in a separate consumer environment.

The idea of this article is to explain the complete journey of a .NET library: preparing the API, deciding the distribution type, validating locally, publishing to a test environment and, finally, releasing the stable version on nuget.org. I will also show when the package should live in a public feed and when it needs to go to Azure Artifacts or GitHub Packages. The goal is to give a practical view to anyone publishing their first package or trying to organize internal distribution in a company.

If you have already used NuGet packages in application projects, you know that the consumption flow looks simple on the surface: restore, build and run. The delicate point is the contract. A library that looks compatible at build time can produce runtime errors when the package is consumed in an external project with different metadata or dependencies. That is why it is worth splitting publishing into stages: local feed, NuGet test environment, public publishing and private feeds. The path is easy to understand, but discipline is what prevents rework and broken clients.

⚠️ Warning: the NuGet test environment does not replace a private feed. It is meant to validate the publishing flow before uploading the final version. Azure Artifacts and GitHub Packages exist for persistent, authenticated internal distribution.

Prerequisites

Before packing the first package, I like to validate some basic premises to avoid the feeling that publishing succeeded and, later, the package was not useful to whoever consumes it. First, you need the .NET SDK installed and working; the minimum check is dotnet --info. The operational side also matters: an account on nuget.org and an API key with a scope limited to the package. That reduces the impact of a leak or misuse.

The next step is to separate the distribution scenario. If the package is public, a publishing flow on nuget.org requires review and indexing. If it is internal, the best alternative is usually Azure Artifacts or GitHub Packages, with authentication and access control. In any case, the ideal is never to expose tokens in versioned files or in terminal commands that stay in the shell history.

It is also worth making it clear that this process is not only about “pack and publish”. It is about “pack and validate”. The publishing routine has an important exercise: creating a separate consumer project and installing the package that was just generated. Only then can you check whether README, dependencies, files and metadata are correct.

Define the Contract and the SemVer Versioning Strategy

Publishing .NET libraries requires versioning to be treated as part of the public contract. SemVer is the most used convention in the ecosystem and defines that the version follows the MAJOR.MINOR.PATCH structure. Each component communicates something different:

  • MAJOR indicates an incompatible change to the public API
  • MINOR indicates a compatible feature addition
  • PATCH indicates a defect fix without changing the API

It is not just an aesthetic convention. The version number tells the consumer the risk of the update. If I remove a public method or change behavior in a way that a client depends on the old contract, the change is MAJOR. If I add a new method to an API without breaking anyone, the change is MINOR. If I fix a bug internally without changing the interface, the change is PATCH.

I also like to reinforce the importance of pre-release versions. In libraries, 1.5.0-beta.1, 1.5.0-rc.1 and 1.6.0-alpha.3 are useful to validate a feature before the package is published as stable. That reduces the risk of announcing a final version without testing the real impact. The most important rule is simple: a published version is immutable. If it is wrong, you fix it in a new version; you do not rewrite the old one.

Change in the public contractNext versionExample
Remove a method or change behavior incompatiblyMAJOR1.4.2 → 2.0.0
Add a method without breaking consumersMINOR1.4.2 → 1.5.0
Fix a defect without changing the contractPATCH1.4.2 → 1.4.3
Validate a future versionPre-release suffix1.5.0-beta.1

💡 Tip: so-called SemVer 2 also allows pre-releases with labels and normalization rules that NuGet accepts. That matters when you want to test a new feature with consumers who do not yet want to depend on it in production.

Prepare the Library for Distribution

A library can be small and still needs minimum quality items to be published. The sample project used in this article lives in the blog’s samples repository and is called Contoso.TextRules. It exposes reusable rules for text validation and normalization. The package structure is simple, but the way it is described in the .csproj is what lets NuGet generate a useful page on the site and lets the .NET tooling recognize the package correctly.

In the project file, some metadata is essential:

  • PackageId — identifies the package
  • Version — defines the distribution version
  • Authors — states authorship
  • Description — a useful summary for search and discovery
  • PackageTags — search and classification on NuGet.org
  • PackageReadmeFile — includes the README inside the package
  • PackageLicenseExpression — SPDX license for transparency
  • RepositoryUrl and RepositoryType — help navigation and traceability

In addition, it is worth packing symbols when the library matters for debugging and diagnostics. dotnet pack can also include package files such as README.md and LICENSE, which greatly improves the experience of whoever consumes the library.

Separating abstraction from implementation is also relevant as a good practice. NuGet has a very strong culture of small packages with clear responsibilities. In larger projects, it is common to separate a contract from its implementation: for example, designing an abstraction library with interfaces and contracts and another library with the concrete implementation. That prevents consumers from depending on the whole set of features and lets the public API evolve more clearly. It is not mandatory for every small project, but it is a useful pattern for platform libraries or domain components.

📂 Source Code: The complete example is available in the blog’s samples repository: BlogSamples/Packaging/NuGetPublish/

Pack and Validate Locally Before the Push

After preparing the library, the next step is to pack the artifact in Release mode. This is where I check whether the project really generates a complete package. The main command is:

1
dotnet pack src/BlogSamples/Packaging/NuGetPublish/Contoso.TextRules/Contoso.TextRules.csproj -c Release

The expected result is a .nupkg in the bin/Release folder. But the mere existence of a file is not enough. I always inspect the package to confirm that it contains the README, the license and the correct dependencies. The package can build and still have incomplete metadata or missing files, which usually shows up when the library is consumed by an external project.

The most important validation is consuming the package in another project. That changes the scenario: the consumer is not inside the same repository or the same assembly. It installs the package via dotnet add package or via a local feed, and then integration errors appear that the library’s own tests do not capture. A classic error is a file missing from the package or a README that was not included correctly. The package needs to work as a distributed item, not only as a project compiled locally.

Validate in the NuGet Test Environment

Once the package works locally, the next natural environment is the NuGet test environment. The official address is https://int.nugettest.org. This environment was created to validate the publishing flow before sending to the public feed. The goal is not to replace the production process, but to confirm that the package can be uploaded, restored and consumed in a scenario similar to the real one.

Publishing flow of a .NET library with NuGet packages, a test environment and private feeds

In general, the flow is simple: configure a named package source for the test environment, authenticate with the user and push the version. With the package in hand, a different consumer project can restore it and run the real code. That validation reduces the risk of a packaging failure or of a public API that is not yet ready for the public feed.

ℹ️ Info: the official NuGet documentation uses int.nugettest.org as the environment to test publishing before nuget.org. Packages pushed to that environment may not be preserved, so it is useful for validation, not for persistent distribution.

Publish a Stable Version on NuGet.org

When the public API is ready and the package has passed consumption validation, the next step is to publish the stable version on nuget.org. That process requires a NuGet API key with minimum scope: ideally, restrict the token to the package prefix and to the required validity period. That greatly reduces the impact of a credential leak.

The most common command is dotnet nuget push, usually with the package already packed in Release:

1
dotnet nuget push ./artifacts/Contoso.TextRules.1.0.0.nupkg --api-key $NUGET_API_KEY --source https://api.nuget.org/v3/index.json

In practice, publishing on nuget.org is not the end of the process: it also triggers indexing and makes the package available for search and restore. The package goes through NuGet validations and, in some cases, takes a few minutes to show up as available for installation. That is normal and part of the official flow. It is also worth making clear that using unlist makes sense to remove a version from public visibility without deleting it completely; “deleting” a version is not the recommended approach to distribute a public artifact safely.

The most important rule is to reserve the first stable 1.0.0 for the right moment. For libraries, I prefer to validate the API in pre-release first. That gives time to adjust behavior without the pressure of “a potentially broken version” already publicly available.

Distribute Internal Libraries with Azure Artifacts and GitHub Packages

Not every package deserves to go to nuget.org. When the library is internal, a private feed is the safest and easiest option to operate. Azure Artifacts and GitHub Packages serve that scenario with authentication and access control. The decision usually depends on the platform subscription used by the organization.

Azure Artifacts

Azure Artifacts works very well when the organization already uses Azure DevOps and has centralized pipelines. The package feed is associated with the Azure DevOps organization and project, and authentication can be integrated into pipelines and security rules. For teams using Azure as the main platform, it is a natural way to publish internal libraries with access policies and version review.

GitHub Packages

GitHub Packages fits teams that already live inside GitHub. Authentication uses a token with minimum scope and permissions, and the integration with GitHub Actions is usually straightforward. That makes publishing internal components, shared libraries and dependencies much easier for private and public repositories across different development flows.

CriterionAzure ArtifactsGitHub Packages
Main platformAzure DevOpsGitHub
CI integrationAzure PipelinesGitHub Actions
Access controlOrganization and projectOrganization and repository
Best scenarioTeams centralized on Azure DevOpsTeams already using GitHub

⚠️ Warning: never leave tokens in a versioned NuGet.Config. The configuration file can point to different sources, but secrets must stay out of the repository and come in through environment variables or CI secret stores.

Automate Releases without Breaking Consumers

Publishing automation is important, but it needs to be a guard rail, not a shortcut. The ideal CI/CD flow for a .NET library is: run the tests, pack, check whether the version already exists in the feed and only then publish. That prevents a push attempt from rewriting an already published version or publishing a broken package to the wrong feed.

A good strategy is to separate release and publishing into two moments. The tag and changelog process stays in Git; the pre-release publishing can go to a private feed or test environment; the stable version goes to nuget.org only after a compatibility review. That helps keep control of the public API and makes the decision to publish a new version more deliberate.

In pipelines, the rule is to protect secrets. The main point is to keep the token in a CI secret, use it in a specific publish step and restrict permissions. The library code can be automated, but the decision to release a new stable version still requires human attention and breaking change documentation.

Practical Example

I will use the same scenario as the sample project: a library called Contoso.TextRules with reusable validation rules. The goal is to demonstrate the contract part: the public API stays stable, the package version starts as 1.0.0-alpha.1, and the promotion to 1.0.0 happens after the library is validated in a separate consumer environment.

First, the library itself. The main snippet shows how the public API is simple and predictable:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
namespace BlogSamples.Packaging.NuGetPublish;

public sealed class TextRuleSet
{
    public bool IsValidEmail(string value)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(value);

        return value.Contains('@')
            && value.Contains('.')
            && value.IndexOf('@', StringComparison.Ordinal) > 0;
    }

    public string NormalizeWhitespace(string value)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(value);

        return string.Join(' ', value.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries));
    }
}

📂 Source Code: The complete example is available in the blog’s samples repository: BlogSamples/Packaging/NuGetPublish/Contoso.TextRules/

Next, I add the important metadata for the package:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <PackageId>Contoso.TextRules</PackageId>
    <Version>1.0.0-alpha.1</Version>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <RepositoryUrl>https://github.com/lzocateli/blog-zocateli-sample</RepositoryUrl>
    <RepositoryType>git</RepositoryType>
  </PropertyGroup>
</Project>

The package is generated in Release:

1
dotnet pack src/BlogSamples/Packaging/NuGetPublish/Contoso.TextRules/Contoso.TextRules.csproj -c Release

For consumption in a separate project, I also like to configure a local or test source and install the package in a minimal consumer:

1
2
3
4
dotnet new classlib -n Contoso.TextRules.Consumer
cd Contoso.TextRules.Consumer

dotnet add package Contoso.TextRules --version 1.0.0-alpha.1 --source /caminho/para/o/feed

This step is essential. It confirms that the library does not depend only on the project in which it was compiled, but on the artifact that will be delivered to the final consumer. After validation, the promotion to 1.0.0 becomes much safer and the decision to publish on nuget.org becomes a technical choice, not just a feeling that “it works”.

Tips and Good Practices

  1. Treat the public API as a contract. Any change to a signature, observable behavior or documented semantics must be assessed for its impact on consumers before choosing the SemVer version.
  2. Consume the .nupkg in another project. Testing only the compiled library does not check whether the package contains the correct README, dependencies and assemblies.
  3. Create API keys and tokens with minimum scope. A credential limited to the package prefix and to the push operation reduces the impact of an accidental leak.
  4. Never reuse a published version. Fix the problem in a new PATCH version or publish a new pre-release; that preserves restore reproducibility.
  5. Separate public and private sources in NuGet.Config. Give sources clear names, restrict package source mapping when appropriate and prevent internal dependencies from being looked up on nuget.org.
  6. Automate, but keep the review. CI must guarantee repeatable tests and packing; the decision to make a stable release still requires a compatibility review and a changelog.

Objective Summary

  • SemVer — in a .NET library, MAJOR represents an incompatible change, MINOR adds compatible functionality and PATCH fixes a compatible defect; pre-releases use a suffix such as -beta.1.
  • NuGetVersion — NuGet normalizes versions such as 1, 1.0 and 1.0.0 as equivalent and supports SemVer 2 features in modern clients.
  • Local feed — consuming the .nupkg in a separate project checks the distributed artifact, including dependencies, metadata and attached files.
  • int.nugettest.org — the test environment documented by NuGet to validate publishing before nuget.org, but packages may not be preserved.
  • nuget.org — requires an exact version in the package and validates the upload before indexing it; API keys must have minimum scope and expiration.
  • Private feeds — Azure Artifacts and GitHub Packages distribute internal libraries with authentication and access control, a different role from validation in the public test environment.

Read Also

References