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:
MAJORindica un cambio incompatible de la API públicaMINORindica la adición de funcionalidad compatiblePATCHindica 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úblico | Próxima versión | Ejemplo |
|---|---|---|
| Eliminar un método o cambiar el comportamiento de forma incompatible | MAJOR | 1.4.2 → 2.0.0 |
| Agregar un método sin romper consumidores | MINOR | 1.4.2 → 1.5.0 |
| Corregir un defecto sin cambiar el contrato | PATCH | 1.4.2 → 1.4.3 |
| Validar una versión futura | Sufijo pre-release | 1.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 paqueteVersion— define la versión de la distribuciónAuthors— informa la autoríaDescription— resumen útil para búsqueda y descubrimientoPackageTags— búsqueda y clasificación en NuGet.orgPackageReadmeFile— incluye el README dentro del paquetePackageLicenseExpression— licencia SPDX para transparenciaRepositoryUrlyRepositoryType— 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:
| |
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.

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.orgcomo entorno para probar la publicación antes denuget.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:
| |
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.
| Criterio | Azure Artifacts | GitHub Packages |
|---|---|---|
| Plataforma principal | Azure DevOps | GitHub |
| Integración de CI | Azure Pipelines | GitHub Actions |
| Control de acceso | Organización y proyecto | Organización y repositorio |
| Mejor escenario | Equipos centralizados en Azure DevOps | Equipos que ya usan GitHub |
⚠️ Atención: nunca dejes tokens en un
NuGet.Configversionado. 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:
| |
📂 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:
| |
La generación del paquete ocurre en 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:
| |
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
- 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.
- Consume el
.nupkgen otro proyecto. Probar solo la biblioteca compilada no verifica si el paquete contiene el README, las dependencias y los assemblies correctos. - 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.
- Nunca reutilices una versión publicada. Corrige el problema en una nueva versión
PATCHo publica una nueva pre-release; eso preserva la reproducibilidad del restore. - 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. - 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,
MAJORrepresenta un cambio incompatible,MINORagrega funcionalidad compatible yPATCHcorrige un defecto compatible; las pre-releases usan un sufijo como-beta.1. - NuGetVersion — NuGet normaliza versiones como
1,1.0y1.0.0como equivalentes y soporta recursos de SemVer 2 en clientes modernos. - Feed local — consumir el
.nupkgen 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
- C# como Script en .NET — usar bibliotecas y paquetes NuGet en scripts C#.
- EFCore.BulkExtensions: Operaciones Masivas en .NET — ejemplo de biblioteca distribuida por el ecosistema NuGet.
- CI/CD Seguro: Dependabot, SAST y DAST en GitHub — proteger dependencias y pipelines de publicación.
- Configuración .NET 8+: IOptions, Secrets y Docker — administrar secretos y configuración en aplicaciones .NET.
Referencias
- How to publish NuGet packages — documentación oficial de publicación, API keys, indexación y entorno de prueba.
- NuGet Package Version Reference — reglas de versión, pre-releases, normalización y SemVer 2.
- Overview of Hosting Your Own NuGet Feeds — alternativas para la distribución privada de paquetes.
- Semantic Versioning 2.0.0 — especificación del contrato de versionado semántico.
- Azure Artifacts documentation — publicación y consumo de paquetes NuGet en Azure DevOps.
- Working with the NuGet registry — configuración y publicación en GitHub Packages.
- Nuuvify.CommonPack — ejemplo real de una colección de bibliotecas .NET publicada en NuGet, organizada por responsabilidad y proyectos de abstracción.

Al comentar, aceptas nuestra Política de Privacidad, Términos de Uso, Política de Eliminación de Datos.