Introducción

Publicar una biblioteca .NET en NuGet.org no es solo empaquetar un proyecto y enviar el .nupkg al servidor. El punto más importante es tratar la API pública como un contrato que otras personas y otros equipos van a consumir. Si publico una API sin pensar en compatibilidad, el problema no se queda en el paquete: se extiende a dependencias, pipelines y aplicaciones que dependen del mismo assembly. Por eso, la publicación segura combina tres pilares: contrato estable, versionado consciente y validación real del artefacto en un entorno de consumidor separado.

La idea de este artículo es explicar el recorrido completo de una biblioteca .NET: preparar la API, decidir el tipo de distribución, validar localmente, publicar en un entorno de prueba y, por último, liberar la versión estable en nuget.org. También mostraré cuándo el paquete debe quedarse en un feed público y cuándo necesita ir a Azure Artifacts o GitHub Packages. El objetivo es dar una visión práctica a quien publica su primer paquete o intenta organizar la distribución interna de la empresa.

Si ya usaste paquetes NuGet en proyectos de aplicación, sabes que el flujo de consumo parece simple en la superficie: restaurar, compilar y ejecutar. El punto delicado es el contrato. Una biblioteca que parece compatible en el build puede generar errores de runtime cuando el paquete se consume en un proyecto externo con metadatos o dependencias diferentes. Por eso conviene separar la publicación en etapas: feed local, entorno de prueba de NuGet, publicación pública y feeds privados. El recorrido es fácil de entender, pero la disciplina es lo que evita retrabajo y clientes rotos.

⚠️ Atención: el entorno de prueba de NuGet no sustituye a un feed privado. Sirve para validar el flujo de publicación antes de subir la versión definitiva. Azure Artifacts y GitHub Packages existen para una distribución interna persistente y autenticada.

Requisitos previos

Antes de empaquetar el primer paquete, me gusta validar algunas premisas básicas para evitar la sensación de que la publicación fue exitosa y, después, el paquete no resultó útil para quien lo va a consumir. En primer lugar, necesitas el .NET SDK instalado y funcionando; la comprobación mínima es dotnet --info. El lado operativo también importa: una cuenta en nuget.org y una API key con alcance limitado al paquete. Eso reduce el impacto de una filtración o de un uso indebido.

El siguiente paso es separar el escenario de distribución. Si el paquete es público, un flujo de publicación en nuget.org exige revisión e indexación. Si es interno, la mejor alternativa suele ser Azure Artifacts o GitHub Packages, con autenticación y control de acceso. En cualquier caso, lo ideal es no exponer nunca tokens en archivos versionados ni en comandos de terminal que queden en el historial del shell.

También conviene dejar claro que este proceso no es solo “empaquetar y publicar”. Es “empaquetar y validar”. La rutina de publicación tiene un ejercicio importante: crear un proyecto consumidor separado e instalar el paquete que se acaba de generar. Solo así es posible verificar si README, dependencias, archivos y metadatos son correctos.

Define el Contrato y la Estrategia de Versionado SemVer

La publicación de bibliotecas .NET exige que el versionado se trate como parte del contrato público. SemVer es la convención más usada en el ecosistema y define que la versión siga la estructura MAJOR.MINOR.PATCH. Cada componente comunica algo diferente:

  • MAJOR indica un cambio incompatible de la API pública
  • MINOR indica la adición de funcionalidad compatible
  • PATCH indica la corrección de un defecto sin cambiar la API

No es solo una convención estética. El número de versión comunica al consumidor el riesgo de la actualización. Si elimino un método público o cambio el comportamiento de forma que un cliente dependa del contrato antiguo, el cambio es MAJOR. Si agrego un nuevo método a una API sin romper a nadie, el cambio es MINOR. Si corrijo un bug internamente sin alterar la interfaz, el cambio es PATCH.

También me gusta reforzar la importancia de las versiones pre-release. En bibliotecas, 1.5.0-beta.1, 1.5.0-rc.1 y 1.6.0-alpha.3 son útiles para validar una funcionalidad antes de publicar el paquete como estable. Eso reduce el riesgo de anunciar una versión definitiva sin probar los impactos reales. La regla más importante es simple: una versión publicada es inmutable. Si está mal, la corriges en una nueva versión; no reescribes la antigua.

Cambio en el contrato públicoPróxima versiónEjemplo
Eliminar un método o cambiar el comportamiento de forma incompatibleMAJOR1.4.2 → 2.0.0
Agregar un método sin romper consumidoresMINOR1.4.2 → 1.5.0
Corregir un defecto sin cambiar el contratoPATCH1.4.2 → 1.4.3
Validar una versión futuraSufijo pre-release1.5.0-beta.1

💡 Consejo: el llamado SemVer 2 también permite pre-releases con etiquetas y reglas de normalización que NuGet acepta. Eso importa cuando quieres probar una nueva funcionalidad con consumidores que todavía no quieren depender de ella en producción.

Prepara la Biblioteca para la Distribución

Una biblioteca puede ser pequeña y aun así necesita elementos mínimos de calidad para publicarse. El proyecto de ejemplo usado en este artículo está en el repositorio de ejemplos del blog y se llama Contoso.TextRules. Expone reglas reutilizables para validación y normalización de texto. La estructura del paquete es simple, pero la forma en que se describe en el .csproj es lo que permite que NuGet genere una página útil en el sitio y que el tooling de .NET reconozca correctamente el paquete.

En el archivo de proyecto, algunos metadatos son fundamentales:

  • PackageId — identifica el paquete
  • Version — define la versión de la distribución
  • Authors — informa la autoría
  • Description — resumen útil para búsqueda y descubrimiento
  • PackageTags — búsqueda y clasificación en NuGet.org
  • PackageReadmeFile — incluye el README dentro del paquete
  • PackageLicenseExpression — licencia SPDX para transparencia
  • RepositoryUrl y RepositoryType — ayudan en la navegación y la trazabilidad

Además, conviene empaquetar los símbolos cuando la biblioteca es relevante para depuración y diagnóstico. dotnet pack también puede incluir archivos del paquete, como README.md y LICENSE, lo que mejora mucho la experiencia de quien consume la biblioteca.

La separación entre abstracción e implementación también es relevante como buena práctica. NuGet tiene una cultura muy fuerte de paquetes pequeños y de responsabilidad clara. En proyectos más grandes, es común separar un contrato de la implementación: por ejemplo, diseñar una biblioteca de abstracción con interfaces y contratos y otra biblioteca con la implementación concreta. Eso evita que los consumidores dependan de todo el conjunto de funcionalidades y permite que la API pública evolucione con más claridad. No es obligatorio para todo proyecto pequeño, pero es un patrón útil para bibliotecas de plataforma o componentes de dominio.

📂 Código Fuente: El ejemplo completo está disponible en el repositorio de ejemplos del blog: BlogSamples/Packaging/NuGetPublish/

Empaqueta y Valida Localmente Antes del Push

Después de preparar la biblioteca, el siguiente paso es empaquetar el artefacto en modo Release. Este es el punto en el que verifico si el proyecto realmente genera un paquete completo. El comando principal es:

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

El resultado esperado es un .nupkg en la carpeta bin/Release. Pero el simple hecho de que exista un archivo no basta. Siempre inspecciono el paquete para confirmar que contiene el README, la licencia y las dependencias correctas. El paquete puede compilar y aun así tener metadatos incompletos o archivos faltantes, algo que suele aparecer cuando la biblioteca es consumida por un proyecto externo.

La validación más importante es consumir el paquete en otro proyecto. Eso cambia el escenario: el consumidor no está dentro del mismo repositorio ni del mismo assembly. Instala el paquete vía dotnet add package o vía un feed local, y entonces aparecen errores de integración que las pruebas de la propia biblioteca no capturan. Un error clásico es un archivo que queda fuera del paquete o un README que no se incluyó correctamente. El paquete necesita funcionar como un elemento distribuido, no solo como un proyecto compilado localmente.

Valida en el Entorno de Prueba de NuGet

Cuando el paquete funciona localmente, el siguiente entorno natural es el de prueba de NuGet. La dirección oficial es https://int.nugettest.org. Este entorno se creó para validar el flujo de publicación antes del envío al feed público. El objetivo no es sustituir el proceso de producción, sino confirmar que el paquete puede enviarse, restaurarse y consumirse en un escenario similar al real.

Flujo de publicación de una biblioteca .NET con paquetes NuGet, entorno de prueba y feeds privados

En general, el flujo es simple: configurar una fuente de paquetes con nombre para el entorno de prueba, autenticarse con el usuario y enviar la versión. Con el paquete en mano, un proyecto consumidor diferente puede restaurarlo y ejecutar el código real. Esa validación reduce el riesgo de una falla de packaging o de una API pública que todavía no está lista para el feed público.

ℹ️ Información: la documentación oficial de NuGet usa int.nugettest.org como entorno para probar la publicación antes de nuget.org. Los paquetes enviados a ese entorno pueden no conservarse, por eso es útil para validación, no para distribución persistente.

Publica una Versión Estable en NuGet.org

Cuando la API pública está lista y el paquete pasó la validación de consumo, la siguiente etapa es publicar la versión estable en nuget.org. Este proceso exige una API key de NuGet con alcance mínimo: lo ideal es restringir el token al prefijo del paquete y al tiempo de validez necesario. Eso reduce mucho el impacto de una filtración de credenciales.

El comando más común es dotnet nuget push, normalmente con el paquete ya empaquetado en 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

En la práctica, la publicación en nuget.org no es el final del proceso: también dispara la indexación y la disponibilidad del paquete para búsqueda y restauración. El paquete pasa por validaciones de NuGet y, en algunos casos, tarda algunos minutos en aparecer como disponible para instalación. Es normal y forma parte del flujo oficial. También conviene dejar claro que usar unlist tiene sentido para quitar una versión de la visibilidad pública sin borrarla por completo; “eliminar” una versión no es el enfoque recomendado para distribuir un artefacto público de forma segura.

La regla más importante es reservar la primera versión estable 1.0.0 para el momento adecuado. En bibliotecas, prefiero validar la API primero en pre-release. Eso da tiempo para ajustar el comportamiento sin la presión de “una versión potencialmente rota” ya disponible públicamente.

Distribuye Bibliotecas Internas con Azure Artifacts y GitHub Packages

No todo paquete merece ir a nuget.org. Cuando la biblioteca es interna, un feed privado es la opción más segura y fácil de operar. Azure Artifacts y GitHub Packages atienden ese escenario con autenticación y control de acceso. La decisión suele depender de la plataforma que usa la organización.

Azure Artifacts

Azure Artifacts funciona muy bien cuando la organización ya usa Azure DevOps y tiene pipelines centralizados. El feed de paquetes queda asociado a la organización y al proyecto de Azure DevOps, y la autenticación puede integrarse con pipelines y reglas de seguridad. Para equipos que usan Azure como plataforma principal, es una forma natural de publicar bibliotecas internas con políticas de acceso y revisión de versiones.

GitHub Packages

GitHub Packages encaja bien en equipos que ya viven dentro de GitHub. La autenticación usa un token con alcance y permisos mínimos, y la integración con GitHub Actions suele ser directa. Eso facilita mucho la publicación de componentes internos, bibliotecas compartidas y dependencias para repositorios privados y públicos en distintos flujos de desarrollo.

CriterioAzure ArtifactsGitHub Packages
Plataforma principalAzure DevOpsGitHub
Integración de CIAzure PipelinesGitHub Actions
Control de accesoOrganización y proyectoOrganización y repositorio
Mejor escenarioEquipos centralizados en Azure DevOpsEquipos que ya usan GitHub

⚠️ Atención: nunca dejes tokens en un NuGet.Config versionado. El archivo de configuración puede apuntar a diferentes fuentes, pero los secretos deben salir del repositorio y entrar por variables de entorno o secret stores del CI.

Automatiza Releases sin Romper Consumidores

La automatización de la publicación es importante, pero debe ser un guard rail, no un atajo. El flujo ideal de CI/CD para una biblioteca .NET es: ejecutar las pruebas, empaquetar, verificar si la versión ya existe en el feed y solo entonces publicar. Eso evita que un intento de push reescriba una versión ya publicada o publique un paquete roto en el feed equivocado.

Una buena estrategia es separar release y publicación en dos momentos. El proceso de tag y changelog queda en Git; la publicación de pre-release puede ir a un feed privado o al entorno de prueba; la versión estable va a nuget.org solo después de una revisión de compatibilidad. Eso ayuda a mantener el control de la API pública y hace que la decisión de publicar una nueva versión sea más consciente.

En los pipelines, la regla es proteger los secretos. Lo principal es mantener el token en un secret del CI, usarlo en un paso específico de publish y restringir los permisos. El código de la biblioteca puede ser automático, pero la decisión de liberar una nueva versión estable sigue exigiendo atención humana y documentación de breaking changes.

Ejemplo Práctico

Usaré el mismo escenario del proyecto de ejemplo: una biblioteca llamada Contoso.TextRules con reglas de validación reutilizables. El objetivo es demostrar la parte del contrato: la API pública se mantiene estable, la versión del paquete empieza como 1.0.0-alpha.1, y la promoción a 1.0.0 ocurre después de validar la biblioteca en un entorno de consumidor separado.

Primero, la biblioteca en sí. El fragmento principal muestra que la API pública es simple y predecible:

 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));
    }
}

📂 Código Fuente: El ejemplo completo está disponible en el repositorio de ejemplos del blog: BlogSamples/Packaging/NuGetPublish/Contoso.TextRules/

A continuación, agrego los metadatos importantes para el paquete:

 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>

La generación del paquete ocurre en Release:

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

Para consumirlo en un proyecto separado, también me gusta configurar una fuente local o de prueba e instalar el paquete en un consumidor mínimo:

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

Este paso es esencial. Confirma que la biblioteca no depende solo del proyecto en el que se compiló, sino del artefacto que se entregará al consumidor final. Después de la validación, la promoción a 1.0.0 se vuelve mucho más segura y la decisión de publicar en nuget.org pasa a ser una elección técnica, no solo una sensación de que “funciona”.

Consejos y Buenas Prácticas

  1. Trata la API pública como un contrato. Cualquier cambio de firma, comportamiento observable o semántica documentada debe evaluarse por su impacto en los consumidores antes de elegir la versión SemVer.
  2. Consume el .nupkg en otro proyecto. Probar solo la biblioteca compilada no verifica si el paquete contiene el README, las dependencias y los assemblies correctos.
  3. Crea API keys y tokens con alcance mínimo. Una credencial limitada al prefijo del paquete y a la operación de push reduce el impacto de una filtración accidental.
  4. Nunca reutilices una versión publicada. Corrige el problema en una nueva versión PATCH o publica una nueva pre-release; eso preserva la reproducibilidad del restore.
  5. Separa fuentes públicas y privadas en NuGet.Config. Da nombres claros a las fuentes, restringe el mapeo de paquetes cuando corresponda y evita que las dependencias internas se busquen en nuget.org.
  6. Automatiza, pero conserva la revisión. El CI debe garantizar pruebas y empaquetado repetibles; la decisión de una release estable sigue exigiendo revisión de compatibilidad y changelog.

Resumen Objetivo

  • SemVer — en una biblioteca .NET, MAJOR representa un cambio incompatible, MINOR agrega funcionalidad compatible y PATCH corrige un defecto compatible; las pre-releases usan un sufijo como -beta.1.
  • NuGetVersion — NuGet normaliza versiones como 1, 1.0 y 1.0.0 como equivalentes y soporta recursos de SemVer 2 en clientes modernos.
  • Feed local — consumir el .nupkg en un proyecto separado verifica el artefacto distribuido, incluidas dependencias, metadatos y archivos adjuntos.
  • int.nugettest.org — es el entorno de prueba documentado por NuGet para validar la publicación antes de nuget.org, pero los paquetes pueden no conservarse.
  • nuget.org — exige una versión exacta en el paquete y valida el upload antes de indexarlo; las API keys deben tener alcance y expiración mínimos.
  • Feeds privados — Azure Artifacts y GitHub Packages distribuyen bibliotecas internas con autenticación y control de acceso, una función diferente de la validación en el entorno de prueba público.

Lee También

Referencias