Cambios que afectan a la compatibilidadChanges that affect compatibility

A lo largo de su historia, .NET ha intentado mantener un alto nivel de compatibilidad de versión a versión y a través de los sabores de .NET.Throughout its history, .NET has attempted to maintain a high level of compatibility from version to version and across flavors of .NET. Esto sigue siendo cierto para .NET Core.This continues to be true for .NET Core. Aunque .NET Core se puede considerar como una nueva tecnología que es independiente de .NET Framework, hay dos factores principales que limitan la capacidad de .NET Core para desviarse de .NET Framework:Although .NET Core can be considered as a new technology that is independent of the .NET Framework, two major factors limit the ability of .NET Core to diverge from .NET Framework:

  • Un gran número de desarrolladores desarrollaron originalmente o continúan desarrollando aplicaciones .NET Framework.A large number of developers either originally developed or continue to develop .NET Framework applications. Esperan un comportamiento coherente en las implementaciones de .NET.They expect consistent behavior across .NET implementations.

  • Los proyectos de bibliotecas .NET Standard permiten a los desarrolladores crear bibliotecas dirigidas a las API comunes compartidas por .NET Core y .NET Framework..NET Standard library projects allow developers to create libraries that target common APIs shared by .NET Core and .NET Framework. Los desarrolladores esperan que una biblioteca utilizada en una aplicación .NET Core se comporte de forma idéntica a la misma biblioteca utilizada en una aplicación .NET Framework.Developers expect that a library used in a .NET Core application should behave identically to the same library used in a .NET Framework application.

Junto con la compatibilidad entre las implementaciones de .NET, los desarrolladores esperan un alto nivel de compatibilidad entre las versiones .NET Core.Along with compatibility across .NET implementations, developers expect a high level of compatibility across .NET Core versions. En particular, el código escrito para una versión anterior de .NET Core debería funcionar sin problemas en una versión posterior de .NET Core.In particular, code written for an earlier version of .NET Core should run seamlessly on a later version of .NET Core. De hecho, muchos desarrolladores esperan que las nuevas API que se encuentran en las versiones más recientes de .NET Core también sean compatibles con las versiones preliminares en las que se introdujeron dichas API.In fact, many developers expect that the new APIs found in newly released versions of .NET Core should also be compatible with the pre-release versions in which those APIs were introduced.

En este artículo se describen las categorías de cambios de compatibilidad (o cambios importantes) y la forma en que el equipo de .NET evalúa los cambios en cada una de estas categorías.This article outlines the categories of compatibility changes (or breaking changes) and the way in which the .NET team evaluates changes in each of these categories. Entender cómo el equipo de .NET aborda los posibles cambios importantes es particularmente útil para los desarrolladores que abren solicitudes de incorporación de cambios en el repositorio de GitHub dotnet/runtime que tienen por objetivo modificar el comportamiento de las API existentes.Understanding how the .NET team approaches possible breaking changes is particularly helpful for developers who open pull requests in the dotnet/runtime GitHub repository that modify the behavior of existing APIs.

Nota

Para una definición de las categorías de compatibilidad, como la compatibilidad binaria y la compatibilidad con versiones anteriores, consulte Categorías de cambios importantes.For a definition of compatibility categories, such as binary compatibility and backward compatibility, see Breaking change categories.

En las secciones siguientes se describen las categorías de los cambios realizados en las API de .NET Core y su impacto sobre la compatibilidad de aplicaciones.The following sections describe the categories of changes made to .NET Core APIs and their impact on application compatibility. Los cambios están permitidos ✔️, no permitidos ❌ o requieren un criterio y una evaluación de cuán predecible, obvio y coherente era el comportamiento anterior ❓.Changes are either allowed ✔️, disallowed ❌, or require judgment and an evaluation of how predictable, obvious, and consistent the previous behavior was ❓.

Nota

Además de servir como guía para evaluar los cambios en las bibliotecas .NET Core, los desarrolladores de bibliotecas también pueden utilizar estos criterios para evaluar los cambios en sus bibliotecas que tienen como objetivo varias implementaciones y versiones de .NET.In addition to serving as a guide to how changes to .NET Core libraries are evaluated, library developers can also use these criteria to evaluate changes to their libraries that target multiple .NET implementations and versions.

Modificaciones en el contrato públicoModifications to the public contract

Los cambios en esta categoría modifican el área expuesta pública de un tipo.Changes in this category modify the public surface area of a type. No están permitidos la mayoría de los cambios en esta categoría ya que infringen la compatibilidad con versiones anteriores (la capacidad de una aplicación que se ha desarrollado con una versión anterior de una API para ejecutarse sin recompilación en una versión posterior).Most of the changes in this category are disallowed since they violate backwards compatibility (the ability of an application that was developed with a previous version of an API to execute without recompilation on a later version).

TiposTypes

  • ✔️ PERMITIDO: Supresión de una implementación de interfaz de un tipo cuando la interfaz ya está implementada por un tipo base✔️ ALLOWED: Removing an interface implementation from a type when the interface is already implemented by a base type

  • REQUIERE EVALUACIÓN: Adición de una nueva implementación de interfaz a un tipoREQUIRES JUDGMENT: Adding a new interface implementation to a type

    Este es un cambio aceptable porque no afecta negativamente a los clientes existentes.This is an acceptable change because it does not adversely affect existing clients. Cualquier cambio en el tipo debe funcionar dentro de los límites de los cambios aceptables definidos aquí para que la nueva implementación siga siendo aceptable.Any changes to the type must work within the boundaries of acceptable changes defined here for the new implementation to remain acceptable. Es necesario extremar las precauciones cuando se agregan interfaces que afectan directamente a la capacidad de un diseñador o serializador para generar código o datos que no se pueden consumir a un nivel inferior.Extreme caution is necessary when adding interfaces that directly affect the ability of a designer or serializer to generate code or data that cannot be consumed down-level. Un ejemplo es la interfaz ISerializable.An example is the ISerializable interface.

  • REQUIERE EVALUACIÓN: Introducción a una nueva clase baseREQUIRES JUDGMENT: Introducing a new base class

    Un tipo puede introducirse en una jerarquía entre dos tipos existentes si no introduce nuevos miembros de tipo abstract ni cambia la semántica o el comportamiento de los tipos existentes.A type can be introduced into a hierarchy between two existing types if it doesn't introduce any new abstract members or change the semantics or behavior of existing types. Por ejemplo, en .NET Framework 2.0, la clase DbConnection se ha convertido en una nueva clase base para SqlConnection, que anteriormente había derivado directamente de Component.For example, in .NET Framework 2.0, the DbConnection class became a new base class for SqlConnection, which had previously derived directly from Component.

  • ✔️ PERMITIDO: Traslado de un tipo de un ensamblado a otro✔️ ALLOWED: Moving a type from one assembly to another

    El ensamblado anterior debe estar marcado con el TypeForwardedToAttribute que apunta al nuevo ensamblado.The old assembly must be marked with the TypeForwardedToAttribute that points to the new assembly.

  • ✔️ PERMITIDO: Cambio de un tipo struct a un tipo readonly struct✔️ ALLOWED: Changing a struct type to a readonly struct type

    No se permite cambiar un tipo readonly struct a un tipo struct.Changing a readonly struct type to a struct type is not allowed.

  • ✔️ PERMITIDO: Adición de la palabra clave sealed o abstract a un tipo cuando hay ningún constructor accesible (público o protegido)✔️ ALLOWED: Adding the sealed or abstract keyword to a type when there are no accessible (public or protected) constructors

  • ✔️ PERMITIDO: Expansión de la visibilidad de un tipo✔️ ALLOWED: Expanding the visibility of a type

  • NO PERMITIDO: Cambio del espacio de nombres o del nombre de un tipoDISALLOWED: Changing the namespace or name of a type

  • NO PERMITIDO: Cambio de nombre o eliminación de un tipo públicoDISALLOWED: Renaming or removing a public type

    Esto interrumpe todo el código que utiliza el tipo cuyo nombre se ha cambiado o quitado.This breaks all code that uses the renamed or removed type.

  • NO PERMITIDO: Cambio del tipo subyacente de una enumeraciónDISALLOWED: Changing the underlying type of an enumeration

    Se trata de un cambio importante en tiempo de compilación y de comportamiento, así como de un cambio importante binario que puede hacer que los argumentos de atributos no se puedan analizar.This is a compile-time and behavioral breaking change as well as a binary breaking change that can make attribute arguments unparsable.

  • NO PERMITIDO: Sellado de un tipo que anteriormente no estaba selladoDISALLOWED: Sealing a type that was previously unsealed

  • NO PERMITIDO: Adición de una interfaz al conjunto de tipos base de una interfazDISALLOWED: Adding an interface to the set of base types of an interface

    Si una interfaz implementa una interfaz que antes no se implementaba, todos los tipos que implementaron la versión original de la interfaz se interrumpen.If an interface implements an interface that it previously did not implement, all types that implemented the original version of the interface are broken.

  • REQUIERE EVALUACIÓN: Eliminación de una clase del conjunto de clases base o una interfaz desde el conjunto de interfaces implementadasREQUIRES JUDGMENT: Removing a class from the set of base classes or an interface from the set of implemented interfaces

    Hay una excepción a la regla para la eliminación de interfaces: puede agregar la implementación de una interfaz que se derive de la interfaz eliminada.There is one exception to the rule for interface removal: you can add the implementation of an interface that derives from the removed interface. Por ejemplo, puede quitar IDisposable si el tipo o interfaz ahora implementa IComponent, que implementa IDisposable.For example, you can remove IDisposable if the type or interface now implements IComponent, which implements IDisposable.

  • NO PERMITIDO: Cambio de un tipo readonly struct a un tipo structDISALLOWED: Changing a readonly struct type to a struct type

    No obstante, se permite el cambio de un tipo struct a un tipo readonly struct.The change of a struct type to a readonly struct type is allowed, however.

  • NO PERMITIDO: Cambio de un tipo struct a un tipo ref struct y viceversaDISALLOWED: Changing a struct type to a ref struct type, and vice versa

  • NO PERMITIDO: Reducción de la visibilidad de un tipoDISALLOWED: Reducing the visibility of a type

    Sin embargo, se permite aumentar la visibilidad de un tipo.However, increasing the visibility of a type is allowed.

MiembrosMembers

  • ✔️ PERMITIDO: Expansión de la visibilidad de un miembro que no es virtual✔️ ALLOWED: Expanding the visibility of a member that is not virtual

  • ✔️ PERMITIDO: Adición de un miembro de tipo abstract a un tipo público que no tiene ningún constructor accesible (público o protegido) o el tipo sealed✔️ ALLOWED: Adding an abstract member to a public type that has no accessible (public or protected) constructors, or the type is sealed

    Sin embargo, no se permite agregar un miembro de tipo abstract a un tipo que tenga constructores accesibles (públicos o protegidos) y que no sea sealed.However, adding an abstract member to a type that has accessible (public or protected) constructors and is not sealed is not allowed.

  • ✔️ PERMITIDO: Restricción de la visibilidad de un miembro protected cuando el tipo no tiene constructores accesibles (públicos o protegidos) o el tipo es sealed✔️ ALLOWED: Restricting the visibility of a protected member when the type has no accessible (public or protected) constructors, or the type is sealed

  • ✔️ PERMITIDO: Desplazamiento de un miembro a una clase superior en la jerarquía que el tipo del que fue eliminado✔️ ALLOWED: Moving a member into a class higher in the hierarchy than the type from which it was removed

  • ✔️ PERMITIDO: Adición o eliminación de una invalidación✔️ ALLOWED: Adding or removing an override

    La introducción de una invalidación puede hacer que los consumidores anteriores omitan la invalidación cuando llamen a la base.Introducing an override might cause previous consumers to skip over the override when calling base.

  • ✔️ PERMITIDO: Adición de un constructor a una clase, junto con un constructor sin parámetros si la clase no tenía previamente constructores✔️ ALLOWED: Adding a constructor to a class, along with a parameterless constructor if the class previously had no constructors

    Sin embargo, no se permite agregar un constructor a una clase que antes no tenía constructores sin agregar el constructor sin parámetros.However, adding a constructor to a class that previously had no constructors without adding the parameterless constructor is not allowed.

  • ✔️ PERMITIDO: Cambio de un miembro de tipo abstract a virtual✔️ ALLOWED: Changing a member from abstract to virtual

  • ✔️ PERMITIDO: Cambio de un valor devuelto ref readonly a un ref (excepto para los métodos o interfaces virtuales)✔️ ALLOWED: Changing from a ref readonly to a ref return value (except for virtual methods or interfaces)

  • ✔️ PERMITIDO: Eliminación de readonly desde un campo, a menos que el tipo estático del campo sea un tipo de valor mutable✔️ ALLOWED: Removing readonly from a field, unless the static type of the field is a mutable value type

  • ✔️ PERMITIDO: Llamada a un nuevo evento que no se ha definido anteriormente✔️ ALLOWED: Calling a new event that wasn't previously defined

  • REQUIERE EVALUACIÓN: Adición de un nuevo campo de instancia a un tipoREQUIRES JUDGMENT: Adding a new instance field to a type

    Este cambio afecta a la serialización.This change impacts serialization.

  • NO PERMITIDO: Cambio de nombre o eliminación de un miembro o parámetro públicoDISALLOWED: Renaming or removing a public member or parameter

    Esto interrumpe todo el código que utiliza el miembro o parámetro cuyo nombre se ha cambiado o quitado.This breaks all code that uses the renamed or removed member, or parameter.

    Esto incluye el cambio de nombre o eliminación de un captador o establecedor de una propiedad, así como el cambio de nombre o eliminación de los miembros de la enumeración.This includes removing or renaming a getter or setter from a property, as well as renaming or removing enumeration members.

  • NO PERMITIDO: Adición de un miembro a una interfazDISALLOWED: Adding a member to an interface

  • NO PERMITIDO: Cambio del valor de un miembro constante o de enumeración públicoDISALLOWED: Changing the value of a public constant or enumeration member

  • NO PERMITIDO: Cambio del tipo de una propiedad, campo, parámetro o valor devueltoDISALLOWED: Changing the type of a property, field, parameter, or return value

  • NO PERMITIDO: Adición, eliminación o cambio del orden de los parámetrosDISALLOWED: Adding, removing, or changing the order of parameters

  • NO PERMITIDO: Adición o eliminación de la palabra clave in, out o ref en un parámetroDISALLOWED: Adding or removing the in, out , or ref keyword from a parameter

  • NO PERMITIDO: Cambio de nombre de un parámetro (incluido el cambio de mayúsculas y minúsculas)DISALLOWED: Renaming a parameter (including changing its case)

    Esto se considera importante por dos motivos:This is considered breaking for two reasons:

  • NO PERMITIDO: Cambio de un valor devuelto ref a un valor devuelto ref readonlyDISALLOWED: Changing from a ref return value to a ref readonly return value

  • ❌️ NO PERMITIDO: Cambio de un valor ref readonly a un valor devuelto ref en una interfaz o método virtual❌️ DISALLOWED: Changing from a ref readonly to a ref return value on a virtual method or interface

  • NO PERMITIDO: Adición o eliminación del tipo abstract de un miembroDISALLOWED: Adding or removing abstract from a member

  • NO PERMITIDO: Eliminación de la palabra clave virtual de un miembroDISALLOWED: Removing the virtual keyword from a member

    Aunque esto a menudo no es un cambio importante porque el compilador de C# tiende a emitir las instrucciones de lenguaje intermedio (IL) callvirt para llamar a métodos no virtuales (callvirt realiza una comprobación nula, mientras que una llamada normal no lo hace), este comportamiento no es invariable por varias razones:While this often is not a breaking change because the C# compiler tends to emit callvirt Intermediate Language (IL) instructions to call non-virtual methods (callvirt performs a null check, while a normal call doesn't), this behavior is not invariable for several reasons:

    • C# no es el único lenguaje al que se dirige .NET.C# is not the only language that .NET targets.

    • El compilador de C# intenta cada vez más optimizar callvirt para una llamada normal cuando el método de destino no es virtual y probablemente no es nulo (como un método al que se accede a través del operador de propagación nula ?).The C# compiler increasingly tries to optimize callvirt to a normal call whenever the target method is non-virtual and is probably not null (such as a method accessed through the ?. null propagation operator).

    Convertir un método en virtual significa que el código del consumidor a menudo acabaría llamándolo no virtual.Making a method virtual means that the consumer code would often end up calling it non-virtually.

  • NO PERMITIDO: Adición de la palabra clave virtual a un miembroDISALLOWED: Adding the virtual keyword to a member

  • NO PERMITIDO: Conversión de un miembro virtual en tipo abstractDISALLOWED: Making a virtual member abstract

    Un miembro virtual proporciona una implementación del método que se puede reemplazar por una clase derivada.A virtual member provides a method implementation that can be overridden by a derived class. Un miembro abstract no proporciona ninguna implementación y debe ser reemplazado.An abstract member provides no implementation and must be overridden.

  • NO PERMITIDO: Adición de un miembro de tipo abstract a un tipo público que tiene constructores accesibles (públicos o protegidos) y que no es de tipo sealedDISALLOWED: Adding an abstract member to a public type that has accessible (public or protected) constructors and that is not sealed

  • NO PERMITIDO: Adición y eliminación de la palabra clave static de un miembroDISALLOWED: Adding or removing the static keyword from a member

  • NO PERMITIDO: Adición de una sobrecarga que impide una sobrecarga existente y define un comportamiento diferenteDISALLOWED: Adding an overload that precludes an existing overload and defines a different behavior

    Esto interrumpe a los clientes existentes que se enlazaron a la sobrecarga anterior.This breaks existing clients that were bound to the previous overload. Por ejemplo, si una clase tiene una versión única de un método que acepta un UInt32, un consumidor existente se enlazará correctamente a esa sobrecarga al pasar un valor Int32.For example, if a class has a single version of a method that accepts a UInt32, an existing consumer will successfully bind to that overload when passing a Int32 value. Sin embargo, si agrega una sobrecarga que acepte un Int32, al volver a compilar o utilizar la característica de enlace en tiempo de ejecución, el compilador se enlaza ahora a la nueva sobrecarga.However, if you add an overload that accepts an Int32, when recompiling or using late-binding, the compiler now binds to the new overload. Si se produce un comportamiento diferente, se trata de un cambio importante.If different behavior results, this is a breaking change.

  • NO PERMITIDO: Adición de un constructor a una clase que antes no tenía constructores sin agregar el constructor sin parámetrosDISALLOWED: Adding a constructor to a class that previously had no constructor without adding the parameterless constructor

  • ❌️ NO PERMITIDO: Adición de readonly a un campo❌️ DISALLOWED: Adding readonly to a field

  • NO PERMITIDO: Reducción de la visibilidad de un miembroDISALLOWED: Reducing the visibility of a member

    Esto incluye la reducción de la visibilidad de un miembro protected cuando hay constructores accesible (public o protected) y el tipo no es de tipo sealed.This includes reducing the visibility of a protected member when there are accessible (public or protected) constructors and the type is not sealed. Si no es así, se permite reducir la visibilidad de un miembro protegido.If this is not the case, reducing the visibility of a protected member is allowed.

    Se permite aumentar la visibilidad de un miembro.Increasing the visibility of a member is allowed.

  • NO PERMITIDO: Cambio del tipo de un miembroDISALLOWED: Changing the type of a member

    El valor devuelto de un método o el tipo de propiedad o campo no se pueden modificar.The return value of a method or the type of a property or field cannot be modified. Por ejemplo, la firma de un método que devuelve un Object no se puede cambiar para devolver un String, o viceversa.For example, the signature of a method that returns an Object cannot be changed to return a String, or vice versa.

  • NO PERMITIDO: Adición de un campo a una estructura que previamente no tenía ningún estadoDISALLOWED: Adding a field to a struct that previously had no state

    Las reglas de asignación definidas permiten el uso de variables no inicializadas siempre que el tipo de variable sea una estructura sin estado.Definite assignment rules allow the use of uninitialized variables so long as the variable type is a stateless struct. Si la estructura se realiza con estado, el código podría acabar con datos sin inicializar.If the struct is made stateful, code could end up with uninitialized data. Esto es a la vez una posible interrupción del origen y un cambio importante de archivo binario.This is both potentially a source breaking and a binary breaking change.

  • NO PERMITIDO: Desencadenamiento de un evento existente nunca antes desencadenadoDISALLOWED: Firing an existing event when it was never fired before

Cambios de comportamientoBehavioral changes

EnsambladosAssemblies

  • ✔️ PERMITIDO: Portabilidad de un ensamblado cuando se siguen admitiendo las mismas plataformas✔️ ALLOWED: Making an assembly portable when the same platforms are still supported

  • NO PERMITIDO: Cambio de nombre de un ensambladoDISALLOWED: Changing the name of an assembly

  • NO PERMITIDO: Cambio de la clave pública de un ensambladoDISALLOWED: Changing the public key of an assembly

Propiedades, campos, parámetros y valores devueltosProperties, fields, parameters, and return values

  • ✔️ PERMITIDO: Cambio del valor de una propiedad, un campo, un valor devuelto o del parámetro out a un tipo más derivado✔️ ALLOWED: Changing the value of a property, field, return value, or out parameter to a more derived type

    Por ejemplo, un método que devuelve un tipo de Object puede devolver una instancia de String.For example, a method that returns a type of Object can return a String instance. (Sin embargo, no se puede cambiar la firma del método).(However, the method signature cannot change.)

  • ✔️ PERMITIDO: Aumento del intervalo de valores aceptados para una propiedad o parámetro si el miembro no es virtual✔️ ALLOWED: Increasing the range of accepted values for a property or parameter if the member is not virtual

    Mientras que el rango de valores que se pueden pasar al método o que se devuelven por el miembro puede expandirse, el parámetro o tipo de miembro no pueden.While the range of values that can be passed to the method or are returned by the member can expand, the parameter or member type cannot. Por ejemplo, mientras que los valores pasados a un método pueden expandirse de 0-124 a 0-255, el tipo de parámetro no puede cambiar de Byte a Int32.For example, while the values passed to a method can expand from 0-124 to 0-255, the parameter type cannot change from Byte to Int32.

  • NO PERMITIDO: Aumento del intervalo de valores aceptados para una propiedad o parámetro si el miembro es virtualDISALLOWED: Increasing the range of accepted values for a property or parameter if the member is virtual

    Este cambio interrumpe los miembros invalidados existentes, que no funcionarán correctamente para la gama extendida de valores.This change breaks existing overridden members, which will not function correctly for the extended range of values.

  • NO PERMITIDO: Disminución del intervalo de valores aceptados para una propiedad o parámetroDISALLOWED: Decreasing the range of accepted values for a property or parameter

  • NO PERMITIDO: Aumento del intervalo de valores devueltos para una propiedad, un campo, un valor devuelto o el parámetro outDISALLOWED: Increasing the range of returned values for a property, field, return value, or out parameter

  • NO PERMITIDO: Cambio de los valores devueltos para una propiedad, un campo, un valor devuelto del método o el parámetro outDISALLOWED: Changing the returned values for a property, field, method return value, or out parameter

  • NO PERMITIDO: Cambio del valor predeterminado de una propiedad, un campo o un parámetroDISALLOWED: Changing the default value of a property, field, or parameter

  • NO PERMITIDO: Cambio de la precisión de un valor devuelto numéricoDISALLOWED: Changing the precision of a numeric return value

  • REQUIERE EVALUACIÓN: Un cambio en el análisis de la entrada y el inicio de nuevas excepciones (incluso si el comportamiento de análisis no está especificado en la documentación)REQUIRES JUDGMENT: A change in the parsing of input and throwing new exceptions (even if parsing behavior is not specified in the documentation

ExcepcionesExceptions

  • ✔️ PERMITIDO: Inicio de una excepción más derivada que una excepción existente✔️ ALLOWED: Throwing a more derived exception than an existing exception

    Debido a que la nueva excepción es una subclase de una excepción existente, el código de tratamiento de excepciones anterior continúa controlando la excepción.Because the new exception is a subclass of an existing exception, previous exception handling code continues to handle the exception. Por ejemplo, en .NET Framework 4, los métodos de creación y recuperación de la referencia cultural comenzaron a iniciar un CultureNotFoundException en lugar de un ArgumentException si no se podía encontrar la referencia cultural.For example, in .NET Framework 4, culture creation and retrieval methods began to throw a CultureNotFoundException instead of an ArgumentException if the culture could not be found. Dado que CultureNotFoundException procede de ArgumentException, se trata de un cambio aceptable.Because CultureNotFoundException derives from ArgumentException, this is an acceptable change.

  • ✔️ PERMITIDO: Inicio de una excepción más específica que NotSupportedException, NotImplementedException, NullReferenceException✔️ ALLOWED: Throwing a more specific exception than NotSupportedException, NotImplementedException, NullReferenceException

  • ✔️ PERMITIDO: Inicio de una excepción que se considera irrecuperable✔️ ALLOWED: Throwing an exception that is considered unrecoverable

    Las excepciones irrecuperables no deben capturarse, sino que deben tratarse por un controlador general de alto nivel.Unrecoverable exceptions should not be caught but instead should be handled by a high-level catch-all handler. Por lo tanto, no se espera que los usuarios tengan un código que capte estas excepciones explícitas.Therefore, users are not expected to have code that catches these explicit exceptions. Las excepciones irrecuperables son:The unrecoverable exceptions are:

  • ✔️ PERMITIDO: Inicio de una nueva excepción en una nueva ruta del código✔️ ALLOWED: Throwing a new exception in a new code path

    La excepción debe aplicarse solo a una nueva ruta del código que se ejecute con nuevos valores o estados de parámetros, y que no se pueda ejecutar por código existente que apunte a la versión anterior.The exception must apply only to a new code-path that's executed with new parameter values or state and that can't be executed by existing code that targets the previous version.

  • ✔️ PERMITIDO: Eliminación de una excepción para permitir un comportamiento más sólido o nuevos escenarios✔️ ALLOWED: Removing an exception to enable more robust behavior or new scenarios

    Por ejemplo, un método Divide que anteriormente solo trataba valores positivos e iniciaba un ArgumentOutOfRangeException de lo contrario, puede cambiarse para admitir tanto valores negativos como positivos sin iniciar una excepción.For example, a Divide method that previously only handled positive values and threw an ArgumentOutOfRangeException otherwise can be changed to support both negative and positive values without throwing an exception.

  • ✔️ PERMITIDO: Cambio del texto de un mensaje de error✔️ ALLOWED: Changing the text of an error message

    Los desarrolladores no deben confiar en el texto de los mensajes de error, que también cambian en función de la referencia cultural del usuario.Developers should not rely on the text of error messages, which also change based on the user's culture.

  • NO PERMITIDO: Inicio de una excepción en cualquier otro caso no enumerado anteriormenteDISALLOWED: Throwing an exception in any other case not listed above

  • NO PERMITIDO: Eliminación de una excepción en cualquier otro caso no enumerado anteriormenteDISALLOWED: Removing an exception in any other case not listed above

AtributosAttributes

  • ✔️ PERMITIDO: Cambio del valor de un atributo que no es observable✔️ ALLOWED: Changing the value of an attribute that is not observable

  • NO PERMITIDO: Cambio del valor de un atributo que es observableDISALLOWED: Changing the value of an attribute that is observable

  • REQUIERE EVALUACIÓN: Eliminación de un atributoREQUIRES JUDGMENT: Removing an attribute

    En la mayoría de los casos, la eliminación de un atributo (como NonSerializedAttribute) es un cambio importante.In most cases, removing an attribute (such as NonSerializedAttribute) is a breaking change.

Compatibilidad con la plataformaPlatform support

  • ✔️ PERMITIDO: Admisión de una operación en una plataforma que antes no era posible✔️ ALLOWED: Supporting an operation on a platform that was previously not supported

  • NO PERMITIDO: No admitir o requerir ahora un Service Pack específico para una operación que antes estaba admitida en una plataformaDISALLOWED: Not supporting or now requiring a specific service pack for an operation that was previously supported on a platform

Cambios de implementación internosInternal implementation changes

  • REQUIERE EVALUACIÓN: Cambio del área expuesta de un tipo internoREQUIRES JUDGMENT: Changing the surface area of an internal type

    Por lo general se permiten estos cambios, aunque interrumpan la reflexión privada.Such changes are generally allowed, although they break private reflection. En algunos casos, cuando las bibliotecas populares de terceros o un gran número de desarrolladores dependen de las API internas, es posible que no se permitan dichos cambios.In some cases, where popular third-party libraries or a large number of developers depend on the internal APIs, such changes may not be allowed.

  • REQUIERE EVALUACIÓN: Cambio de la implementación interna de un miembroREQUIRES JUDGMENT: Changing the internal implementation of a member

    Por lo general se permiten estos cambios, aunque interrumpan la reflexión privada.These changes are generally allowed, although they break private reflection. En algunos casos, cuando el código del cliente depende con frecuencia de una reflexión privada o cuando el cambio introduce efectos secundarios no deseados, estos cambios pueden no estar permitidos.In some cases, where customer code frequently depends on private reflection or where the change introduces unintended side effects, these changes may not be allowed.

  • ✔️ PERMITIDO: Mejora del rendimiento de una operación✔️ ALLOWED: Improving the performance of an operation

    La capacidad de modificar el rendimiento de una operación es esencial, pero tales cambios pueden interrumpir el código que depende de la velocidad actual de una operación.The ability to modify the performance of an operation is essential, but such changes can break code that relies upon the current speed of an operation. Esto es particularmente cierto en el caso del código que depende de la sincronización de las operaciones asincrónicas.This is particularly true of code that depends on the timing of asynchronous operations. El cambio en el rendimiento no debería tener ningún efecto en otro comportamiento de la API en cuestión; de lo contrario, el cambio se considerará importante.The performance change should have no effect on other behavior of the API in question; otherwise, the change will be breaking.

  • ✔️ PERMITIDO: Modificación indirecta (y a menudo de forma adversa) del rendimiento de una operación✔️ ALLOWED: Indirectly (and often adversely) changing the performance of an operation

    Si el cambio en cuestión no está clasificado como importante por algún otro motivo, esto es aceptable.If the change in question is not categorized as breaking for some other reason, this is acceptable. A menudo, es necesario tomar medidas que pueden incluir operaciones adicionales o que agregan nueva funcionalidad.Often, actions need to be taken that may include extra operations or that add new functionality. Esto casi siempre afectará al rendimiento, pero puede ser esencial para que la API en cuestión funcione como se esperaba.This will almost always affect performance but may be essential to make the API in question function as expected.

  • NO PERMITIDO: Cambio de una API sincrónica en asincrónica (y viceversa)DISALLOWED: Changing a synchronous API to asynchronous (and vice versa)

Cambios en el códigoCode changes

  • ✔️ PERMITIDO: Adición de params a un parámetro✔️ ALLOWED: Adding params to a parameter

  • NO PERMITIDO: Cambio de un tipo struct a un tipo class y viceversaDISALLOWED: Changing a struct to a class and vice versa

  • NO PERMITIDO: Adición de la palabra clave checked a un bloque de códigoDISALLOWED: Adding the checked keyword to a code block

    Este cambio puede causar que el código que se ejecutó previamente inicie un OverflowException y es inaceptable.This change may cause code that previously executed to throw an OverflowException and is unacceptable.

  • NO PERMITIDO: Eliminación de params de un parámetroDISALLOWED: Removing params from a parameter

  • NO PERMITIDO: Cambio del orden en el que se desencadenan los eventosDISALLOWED: Changing the order in which events are fired

    Los desarrolladores pueden esperar razonablemente que los eventos se desencadenen en el mismo orden, y el código de desarrollador depende frecuentemente del orden en el que se desencadenen los eventos.Developers can reasonably expect events to fire in the same order, and developer code frequently depends on the order in which events are fired.

  • NO PERMITIDO: Eliminación del inicio de un evento en una acción determinadaDISALLOWED: Removing the raising of an event on a given action

  • NO PERMITIDO: Cambio del número de veces que se llaman los eventos dadosDISALLOWED: Changing the number of times given events are called

  • NO PERMITIDO: Adición de FlagsAttribute a un tipo de enumeraciónDISALLOWED: Adding the FlagsAttribute to an enumeration type