Compartir a través de

Cambios críticos

Es importante que una biblioteca de .NET encuentre un equilibrio entre la estabilidad de los usuarios existentes y la innovación para el futuro. Los autores de bibliotecas se inclinan hacia la refactorización y replanteamiento del código hasta que sea perfecto, pero romper los usuarios existentes tiene un impacto negativo, especialmente para las bibliotecas de bajo nivel.

Tipos de proyecto y cambios importantes

El uso que la comunidad de .NET realiza de una biblioteca cambia el efecto de los cambios importantes en los usuarios finales.

  • Las bibliotecas de bajo y medio nivel, como un serializador, analizador HTML, mapeador objeto-relacional de base de datos o marco web, son los más afectados por los cambios importantes.

    Los desarrolladores de usuarios finales utilizan paquetes de componentes básicos para desarrollar aplicaciones, y otras bibliotecas los utilizan como dependencias de NuGet. Por ejemplo, va a compilar una aplicación y usa un cliente de código abierto para llamar a un servicio web. Una actualización importante a una dependencia que usa el cliente no es algo que pueda solucionar. Es el cliente de código abierto que debe cambiarse y no tiene control sobre él. Tiene que encontrar versiones compatibles de las bibliotecas o enviar una corrección a la biblioteca cliente y esperar una nueva versión. La peor situación es si desea usar dos bibliotecas que dependen de versiones mutuamente incompatibles de una tercera biblioteca.

  • Las bibliotecas de alto nivel , como un conjunto de controles de interfaz de usuario, son menos sensibles a los cambios importantes.

    Las bibliotecas de alto nivel se referencian directamente en una aplicación de usuario final. Si se producen cambios importantes, el desarrollador puede optar por actualizar a la versión más reciente o modificar su aplicación para que funcione con el cambio importante.

✔️ Piense en cómo se usará la biblioteca. ¿Qué efecto tendrán los cambios importantes en las aplicaciones y bibliotecas que lo usan?

✔️ Minimice los cambios importantes al desarrollar una biblioteca de .NET de bajo nivel.

✔️ CONSIDERE la posibilidad de publicar una reescritura principal de una biblioteca como un nuevo paquete NuGet.

Tipos de cambios importantes

Los cambios importantes se dividen en categorías diferentes y no tienen un impacto igual.

Cambios importantes del código fuente

Un cambio importante del código fuente no afecta a la ejecución del programa, pero provocará errores de compilación la próxima vez que se vuelva a compilar la aplicación. Por ejemplo, una nueva sobrecarga puede crear ambigüedad en las llamadas de método que anteriormente no eran ambiguas o un parámetro cuyo nombre ha cambiado interrumpirá a los autores de la llamada que usan parámetros con nombre.

public class Task
{
    // Adding a type called Task could conflict with System.Threading.Tasks.Task at compilation
}

Dado que un cambio disruptivo en el código fuente solo es perjudicial cuando los desarrolladores vuelven a compilar sus aplicaciones, es el menos disruptivo. Los desarrolladores pueden corregir fácilmente su propio código fuente roto.

Cambios importantes del comportamiento

Los cambios de comportamiento son el tipo más común de cambio disruptivo: casi cualquier cambio en el comportamiento podría provocar un error lógico para el consumidor. Los cambios en tu biblioteca, como las firmas de método, las excepciones lanzadas o los formatos de datos de entrada o salida, podrían afectar negativamente a los usuarios de la librería. Incluso una corrección de errores puede calificar como un cambio importante si los usuarios dependían del comportamiento roto anteriormente.

Agregar características y mejorar comportamientos incorrectos es algo bueno, pero sin cuidado puede dificultar la actualización de los usuarios existentes. Un enfoque para ayudar a los desarrolladores a lidiar con los últimos cambios importantes de comportamiento es ocultarlos en la configuración. La configuración permite a los desarrolladores actualizar a la versión más reciente de la biblioteca, al mismo tiempo que eligen aceptar o rechazar cambios incompatibles. Esta estrategia permite a los desarrolladores mantenerse al día al permitir que el código que consume se adapte con el tiempo.

Por ejemplo, ASP.NET Core MVC tiene el concepto de una versión de compatibilidad que modifica las características habilitadas y deshabilitadas en MvcOptions.

✔️ Considere la posibilidad de dejar desactivadas las nuevas características de forma predeterminada, si afectan a los usuarios existentes y permiten a los desarrolladores participar en la característica con una configuración.

Para obtener más información sobre los cambios importantes de comportamiento en las API de .NET, vea Compatibilidad de los cambios de comportamiento de .NET.

Cambios importantes de archivo binario

Un cambio importante de archivo binario se produce al cambiar la API pública de la biblioteca, ya que los ensamblados compilados con versiones anteriores de la biblioteca ya no pueden llamar a la API. Por ejemplo, si se cambia la firma de un método agregando un nuevo parámetro, los ensamblados compilados con la versión anterior de la biblioteca producirán un MissingMethodException.

Un cambio importante de archivo binario también puede afectar a un ensamblado completo. Cambiar el nombre de un ensamblado con AssemblyName cambiará la identidad del ensamblado, ya que agregará, quitará o cambiará la clave de nomenclatura segura del ensamblado. Un cambio de la identidad de un ensamblado interrumpirá todo el código compilado que lo use.

❌ NO cambie un nombre de ensamblado.

❌ NO agregue, quite ni cambie la clave de nomenclatura segura.

✔️ CONSIDERE la posibilidad de usar clases base abstractas en lugar de interfaces.

Agregar cualquier cosa a una interfaz hará que se produzca un error en los tipos existentes que lo implementan. Una clase base abstracta permite agregar una implementación virtual predeterminada.

✔️ CONSIDERE colocar el ObsoleteAttribute en los tipos y miembros que quiere quitar. El atributo debe tener instrucciones para actualizar el código para que ya no use la API obsoleta.

El código que llama a tipos y métodos con ObsoleteAttribute generará una advertencia de compilación con el mensaje proporcionado al atributo . Las advertencias proporcionan a las personas que usan la API obsoleta tiempo para migrar, de manera que, cuando se elimine la API obsoleta, la mayoría ya no la utilicen.

public class Document
{
    [Obsolete("LoadDocument(string) is obsolete. Use LoadDocument(Uri) instead.")]
    public static Document LoadDocument(string uri)
    {
        return LoadDocument(new Uri(uri));
    }

    public static Document LoadDocument(Uri uri)
    {
        // Load the document
    }
}

✔️ ES RECOMENDABLE mantener tipos y métodos con ObsoleteAttribute indefinidamente en las bibliotecas de nivel medio y bajo.

Quitar API es un cambio de archivo binario. Considere la posibilidad de mantener los tipos y métodos obsoletos si mantenerlos es de bajo costo y no agrega mucha deuda técnica a la biblioteca. No quitar tipos y métodos puede ayudar a evitar los peores escenarios mencionados anteriormente.

Para obtener más información sobre los cambios en la API de .NET que rompen la compatibilidad binaria, consulte Compatibilidad de contratos públicos de .NET.

Consulte también

Anterior

  • Last updated on