Control de versiones

Una biblioteca de software rara vez se completa en la versión 1.0. Las buenas bibliotecas evolucionan con el tiempo, agregando características, corrigiendo errores y mejorando el rendimiento. Es importante que pueda publicar nuevas versiones de una biblioteca de .NET sin interrumpir los usuarios existentes.

Cambios importantes

Para información sobre el control de cambios importantes entre versiones, vea cambios importantes.

Números de versión

Una biblioteca de .NET tiene muchas maneras de especificar una versión. Estas versiones son las más importantes:

• versión del paquete NuGet
• Versión de ensamblado
• Versión del archivo de ensamblado
• Versión informativa del ensamblado

Versión del paquete NuGet

La versión del paquete NuGet se muestra en NuGet.org y en el administrador de paquetes NuGet de Visual Studio, y se agrega al código fuente cuando se utiliza el paquete. La versión del paquete NuGet es el número de versión que los usuarios verán normalmente y se referirán a ella cuando hablen sobre la versión de una biblioteca que usan. La versión del paquete de NuGet la usa NuGet y no tiene ningún efecto en el comportamiento durante el tiempo de ejecución.

<PackageVersion>1.0.0-alpha1</PackageVersion>

El identificador del paquete NuGet combinado con la versión del paquete NuGet se usa para identificar un paquete en NuGet. Por ejemplo, Newtonsoft.Json + 11.0.2. Un paquete con un sufijo es un paquete de versión preliminar y tiene un comportamiento especial que hace que sea ideal para las pruebas. Para obtener más información, consulte los paquetes de versión preliminar .

Dado que la versión del paquete NuGet es la versión más visible para los desarrolladores, es una buena idea actualizarla mediante control de versiones semánticas (SemVer). SemVer indica la importancia de los cambios entre versiones y ayuda a los desarrolladores a tomar una decisión informada al elegir qué versión usar. Por ejemplo, pasar de 1.0 a 2.0 indica que hay cambios potencialmente importantes.

✔️ CONSIDERE la posibilidad de usar semVer 2.0.0 para la versión del paquete NuGet.

✔️ Use la versión del paquete NuGet en la documentación pública, ya que es el número de versión que los usuarios verán normalmente.

✔️ INCLUYA un sufijo de versión preliminar cuando publique un paquete que no sea estable. (Para obtener más información sobre cómo marcar las API como versión preliminar o experimental, consulte API en versión preliminar).

Los usuarios deben optar por obtener paquetes de versión preliminar, por lo que saben que el paquete no está completo.

Versión de ensamblado

La versión del ensamblado es lo que CLR usa en tiempo de ejecución para seleccionar qué versión de un ensamblado se va a cargar. La selección de un ensamblado mediante control de versiones solo se aplica a los ensamblados con un nombre seguro.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

CLR de .NET Framework exige una coincidencia exacta para cargar un ensamblado con nombre seguro. Por ejemplo, Library1, Version=1.0.0.0 se compiló con una referencia a Newtonsoft.Json, Version=11.0.0.0. .NET Framework solo cargará esa versión exacta 11.0.0.0. Para cargar una versión diferente en tiempo de ejecución, se debe agregar un redireccionamiento de enlace al archivo de configuración de la aplicación .NET.

La asignación de nombres seguros junto con la versión de ensamblado permite la carga de la versión de ensamblado estricta. Aunque la asignación de nombres seguros a una biblioteca tiene una serie de ventajas, suele dar lugar a excepciones en tiempo de ejecución que indican que no se puede encontrar un ensamblado y requiere que se corrijan las redirecciones de enlace de app.config o web.config. En .NET (Core), la carga de ensamblados no es tan estricta. El entorno de ejecución de .NET (Core) carga automáticamente ensamblados con una versión superior en tiempo de ejecución.

✔️ CONSIDERE la posibilidad de incluir solo una versión principal en AssemblyVersion.

Por ejemplo, Biblioteca 1.0 y Biblioteca 1.0.1 tienen AssemblyVersion de 1.0.0.0, mientras que Biblioteca 2.0 tiene AssemblyVersion de 2.0.0.0. Cuando la versión del ensamblado cambia con menos frecuencia, reduce las redirecciones de enlace.

✔️ CONSIDERE la posibilidad de mantener sincronizado el número de versión principal de AssemblyVersion y la versión del paquete NuGet.

AssemblyVersion se incluye en algunos mensajes informativos que se muestran al usuario, por ejemplo, el nombre del ensamblado y los nombres de tipo completos del ensamblado en los mensajes de excepción. Mantener una relación entre las versiones proporciona más información a los desarrolladores sobre la versión que usan.

❌ NO tenga una AssemblyVersion fija.

Aunque una AssemblyVersion invariable evita la necesidad de redirecciones de enlace, significa que se puede instalar solo una única versión del ensamblado en la memoria caché de ensamblados global (GAC). Además, las aplicaciones que hacen referencia al ensamblado en la memoria caché de ensamblados global se interrumpirán si otra aplicación actualiza el ensamblado de dicha memoria con cambios importantes.

Versión del archivo de ensamblado

La versión del archivo de ensamblado se usa para mostrar una versión de archivo en Windows y no tiene ningún efecto en el comportamiento en tiempo de ejecución. Establecer esta versión es opcional. Está visible en el cuadro de diálogo Propiedades del archivo en el Explorador de Windows:

<FileVersion>11.0.2.21924</FileVersion>

✔️ ES RECOMENDABLE incluir un número de compilación de integración continua como la revisión AssemblyFileVersion.

Por ejemplo, va a compilar la versión 1.0.0 del proyecto y el número de compilación de integración continua es 99, por lo que AssemblyFileVersion es 1.0.0.99.

✔️ USE el formato Major.Minor.Build.Revision para la versión de archivo.

Aunque .NET nunca usa la versión del archivo, Windows espera que la versión del archivo esté en el formato Major.Minor.Build.Revision. Se genera una advertencia si la versión no sigue este formato.

Versión informativa del ensamblado

La versión informativa del ensamblado se usa para registrar información de versión adicional y no tiene ningún efecto en el comportamiento en tiempo de ejecución. Establecer esta versión es opcional. Si usa Source Link, esta versión se establecerá en la compilación con la versión del paquete NuGet más una versión de control de código fuente. Por ejemplo, 1.0.0-beta1+204ff0a incluye el hash de confirmación del código fuente desde el que se creó el ensamblado. Para obtener más información, vea Source Link.

<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>

Nota

Las versiones anteriores de Visual Studio generan una advertencia de compilación si esta versión no sigue el formato Major.Minor.Build.Revision. La advertencia se puede omitir de forma segura.

❌ EVITE establecer usted mismo la versión informativa del ensamblado.

Permitir que SourceLink genere automáticamente la versión que contiene metadatos de control de código fuente y NuGet.

siguiente