Änderungen, die sich auf die Kompatibilität auswirkenChanges that affect compatibility

Im Laufe seines Bestehens hat .NET versucht, ein hohes Maß an Kompatibilität von Version zu Version und zwischen den verschiedenen Varianten von.NET aufrechtzuerhalten.Throughout its history, .NET has attempted to maintain a high level of compatibility from version to version and across flavors of .NET. Dies gilt auch für .NET Core.This continues to be true for .NET Core. Obwohl .NET Core als eine von .NET Framework unabhängige neue Technologie betrachtet werden kann, schränken zwei wesentliche Faktoren die Möglichkeit von .NET Core ein, von .NET Framework abzuweichen: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:

  • Eine große Anzahl von Entwicklern hat entweder ursprünglich .NET Framework-Anwendungen entwickelt oder entwickelt diese weiterhin.A large number of developers either originally developed or continue to develop .NET Framework applications. Sie erwarten ein konsistentes Verhalten in .NET-Implementierungen.They expect consistent behavior across .NET implementations.

  • .NET Standard-Bibliotheksprojekte ermöglichen es Entwicklern, Bibliotheken zu erstellen, die auf gemeinsame APIs ausgerichtet sind, die von .NET Core und.NET Framework gemeinsam genutzt werden..NET Standard library projects allow developers to create libraries that target common APIs shared by .NET Core and .NET Framework. Entwickler erwarten, dass sich eine in einer .NET Core-Anwendung verwendete Bibliothek genauso verhält, wie dieselbe Bibliothek, die in einer .NET Framework-Anwendung verwendet wird.Developers expect that a library used in a .NET Core application should behave identically to the same library used in a .NET Framework application.

Neben der Kompatibilität zwischen .NET-Implementierungen erwarten Entwickler ein hohes Maß an Kompatibilität zwischen .NET Core-Versionen.Along with compatibility across .NET implementations, developers expect a high level of compatibility across .NET Core versions. Insbesondere sollte Code, der für eine frühere Version von .NET Core geschrieben wurde, problemlos auf einer späteren Version von .NET Core ausgeführt werden können.In particular, code written for an earlier version of .NET Core should run seamlessly on a later version of .NET Core. Tatsächlich erwarten viele Entwickler, dass die neuen APIs in den neu veröffentlichten Versionen von .NET Core auch mit den Vorabversionen kompatibel sein sollten, in denen diese APIs eingeführt wurden.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.

In diesem Artikel werden die Änderungen beschrieben, die die Kompatibilität sowie die Art und Weise beeinflussen, wie das .NET-Team die einzelnen Änderungstypen auswertet.This article outlines changes that affect compatibility and the way in which the .NET team evaluates each type of change. Zu verstehen, wie das .NET-Team mit möglichen Breaking Changes umgeht, ist besonders hilfreich für Entwickler, die Pull Requests öffnen, die das Verhalten bestehender .NET-APIs ändern.Understanding how the .NET team approaches possible breaking changes is particularly helpful for developers who open pull requests that modify the behavior of existing .NET APIs.

In den folgenden Abschnitten werden die Kategorien der Änderungen an den .NET Core-APIs und deren Auswirkungen auf die Anwendungskompatibilität beschrieben.The following sections describe the categories of changes made to .NET Core APIs and their impact on application compatibility. Änderungen sind zulässig ✔️, nicht zulässig ❌, oder es muss beurteilt und bewertet werden, wie vorhersehbar, offensichtlich und konsistent das bisherige Verhalten war ❓.Changes are either allowed ✔️, disallowed ❌, or require judgment and an evaluation of how predictable, obvious, and consistent the previous behavior was ❓.

Hinweis

  • Bibliotheksentwickler können diese Kriterien nicht nur als Leitfaden für die Bewertung von Änderungen an .NET-Bibliotheken verwenden, sondern auch für die Bewertung von Änderungen an ihren Bibliotheken, die auf mehrere .NET-Implementierungen und -Versionen ausgerichtet sind.In addition to serving as a guide to how changes to .NET libraries are evaluated, library developers can also use these criteria to evaluate changes to their libraries that target multiple .NET implementations and versions.
  • Weitere Informationen zu Kompatibilitätskategorien, zum Beispiel zur Aufwärts- und Abwärtskompatibilität, finden Sie unter Kompatibilität.For information about the compatibility categories, for example, forward and backwards compatibility, see Compatibility.

Änderungen am öffentlichen VertragModifications to the public contract

Änderungen in dieser Kategorie modifizieren die öffentliche Oberfläche eines Typs.Changes in this category modify the public surface area of a type. Die meisten Änderungen in dieser Kategorie sind unzulässig, da sie die Abwärtskompatibilität verletzen (die Fähigkeit einer Anwendung, die mit einer früheren Version einer API entwickelt wurde, ohne Neukompilierung auf einer späteren Version ausgeführt zu werden).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).

TypenTypes

  • ✔️ ZULÄSSIG: Entfernen einer Schnittstellenimplementierung aus einem Typ, wenn die Schnittstelle bereits durch einen Basistyp implementiert ist✔️ ALLOWED: Removing an interface implementation from a type when the interface is already implemented by a base type

  • ERFORDERT BEURTEILUNG: Hinzufügen einer neuen Schnittstellenimplementierung zu einem TypREQUIRES JUDGMENT: Adding a new interface implementation to a type

    Dies ist eine zulässige Änderung, da sie bestehende Clients nicht beeinträchtigt.This is an acceptable change because it does not adversely affect existing clients. Jede Änderung des Typs muss innerhalb der hier definierten Grenzen für zulässige Änderungen erfolgen, damit die neue Implementierung weiterhin zulässig ist.Any changes to the type must work within the boundaries of acceptable changes defined here for the new implementation to remain acceptable. Extreme Vorsicht ist geboten, wenn Schnittstellen hinzugefügt werden, die die Fähigkeit eines Designers oder Serialisierungsmoduls direkt beeinflussen, Code oder Daten zu generieren, die nicht auf unteren Ebenen verwendet werden können.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. Ein Beispiel ist die ISerializable-Schnittstelle.An example is the ISerializable interface.

  • ERFORDERT BEURTEILUNG: Einführen einer neuen BasisklasseREQUIRES JUDGMENT: Introducing a new base class

    Ein Typ kann in einer Hierarchie zwischen zwei bestehenden Typen eingefügt werden, wenn er keinen neuen abstract-Member einführt oder die Semantik oder das Verhalten bestehender Typen ändert.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. So wurde beispielsweise in .NET Framework 2.0 die Klasse DbConnection zu einer neuen Basisklasse für SqlConnection, die zuvor direkt von Component abgeleitet wurde.For example, in .NET Framework 2.0, the DbConnection class became a new base class for SqlConnection, which had previously derived directly from Component.

  • ✔️ ZULÄSSIG: Verschieben eines Typs von einer Assembly zu einer anderen✔️ ALLOWED: Moving a type from one assembly to another

    Die alte Assembly muss mit dem TypeForwardedToAttribute markiert werden muss, das auf die neue Assembly verweist.The old assembly must be marked with the TypeForwardedToAttribute that points to the new assembly.

  • ✔️ ZULÄSSIG: Ändern des Typs struct in einen Typ readonly struct✔️ ALLOWED: Changing a struct type to a readonly struct type

    Ein readonly struct-Typ darf nicht in einen struct-Typ geändert werden.Changing a readonly struct type to a struct type is not allowed.

  • ✔️ ZULÄSSIG: Hinzufügen des Schlüsselworts sealed oder abstract zu einem Typ, wenn keine zugänglichen (öffentlichen oder geschützten) Konstruktoren vorhanden sind✔️ ALLOWED: Adding the sealed or abstract keyword to a type when there are no accessible (public or protected) constructors

  • ✔️ ZULÄSSIG: Erweitern der Sichtbarkeit eines Typs✔️ ALLOWED: Expanding the visibility of a type

  • NICHT ZULÄSSIG: Ändern des Namespace oder des Namens eines TypsDISALLOWED: Changing the namespace or name of a type

  • NICHT ZULÄSSIG: Umbenennen oder Entfernen eines öffentlichen TypsDISALLOWED: Renaming or removing a public type

    Dies unterbricht sämtlichen Code, der den umbenannten oder entfernten Typen verwendet.This breaks all code that uses the renamed or removed type.

  • NICHT ZULÄSSIG: Ändern des einer Enumeration zugrunde liegenden TypsDISALLOWED: Changing the underlying type of an enumeration

    Dies ist ein Breaking Change der Kompilierzeit und des Verhaltens und darüber hinaus ein binärer Breaking Change, durch die die Analyse der Attributargumente unterbunden werden könnte.This is a compile-time and behavioral breaking change as well as a binary breaking change that can make attribute arguments unparsable.

  • NICHT ZULÄSSIG: Versiegeln eines bisher nicht versiegelten TypsDISALLOWED: Sealing a type that was previously unsealed

  • NICHT ZULÄSSIG: Hinzufügen einer Schnittstelle zur Menge der Basistypen einer SchnittstelleDISALLOWED: Adding an interface to the set of base types of an interface

    Wenn ein Schnittstelle eine Schnittstelle implementiert, die sie zuvor nicht implementiert hat, werden alle Typen, die die ursprüngliche Version der Schnittstelle implementiert haben, beschädigt.If an interface implements an interface that it previously did not implement, all types that implemented the original version of the interface are broken.

  • ERFORDERT BEURTEILUNG: Entfernen eine Klasse aus der Menge der Basisklassen oder einer Schnittstelle aus der Menge der implementierten SchnittstellenREQUIRES JUDGMENT: Removing a class from the set of base classes or an interface from the set of implemented interfaces

    Es gibt eine Ausnahme von der Regel zur Entfernung von Schnittstellen: Sie können die Implementierung einer Schnittstelle hinzufügen, die aus der entfernten Schnittstelle abgeleitet ist.There is one exception to the rule for interface removal: you can add the implementation of an interface that derives from the removed interface. Sie können beispielsweise IDisposable entfernen, wenn der Typ oder die Schnittstelle nun IComponent implementiert, wodurch IDisposable implementiert wird.For example, you can remove IDisposable if the type or interface now implements IComponent, which implements IDisposable.

  • NICHT ZULÄSSIG: Ändern eines readonly struct-Typs in einen struct-TypDISALLOWED: Changing a readonly struct type to a struct type

    Ein struct-Typ darf nicht in einen readonly struct-Typ geändert werden.The change of a struct type to a readonly struct type is allowed, however.

  • NICHT ZULÄSSIG: Ändern eines struct-Typs in einen ref struct-Typ (und umgekehrt)DISALLOWED: Changing a struct type to a ref struct type, and vice versa

  • NICHT ZULÄSSIG: Reduzieren der Sichtbarkeit eines TypsDISALLOWED: Reducing the visibility of a type

    Die Sichtbarkeit eines Typs darf jedoch erhöht werden.However, increasing the visibility of a type is allowed.

MemberMembers

  • ✔️ ZULÄSSIG: Erweitern der Sichtbarkeit eines nicht virtuellen Members✔️ ALLOWED: Expanding the visibility of a member that is not virtual

  • ✔️ ZULÄSSIG: Hinzufügen eines abstrakten Members zu einem öffentlichen Typ, der keine zugänglichen (öffentlichen oder geschützten) Konstruktoren hat, oder wenn der Typ versiegelt ist✔️ ALLOWED: Adding an abstract member to a public type that has no accessible (public or protected) constructors, or the type is sealed

    Das Hinzufügen eines abstrakten-Members zu einem Typ mit zugänglichen (öffentlichen oder geschützten) Konstruktoren, der nicht sealed ist, ist zulässig.However, adding an abstract member to a type that has accessible (public or protected) constructors and is not sealed is not allowed.

  • ✔️ ZULÄSSIG: Einschränken der Sichtbarkeit eines geschützten Members, wenn der Typ keine zugänglichen (öffentlichen oder geschützten) Konstruktoren hat, oder wenn der Typ versiegelt ist✔️ ALLOWED: Restricting the visibility of a protected member when the type has no accessible (public or protected) constructors, or the type is sealed

  • ✔️ ZULÄSSIG: Verschieben eines Members in eine Klasse, die in der Hierarchie höher liegt als der Typ, aus dem er entfernt wurde✔️ ALLOWED: Moving a member into a class higher in the hierarchy than the type from which it was removed

  • ✔️ ZULÄSSIG: Hinzufügen oder Entfernen einer Außerkraftsetzung✔️ ALLOWED: Adding or removing an override

    Die Einführung einer Außerkraftsetzung kann dazu führen, dass vorherige Consumer beim Aufrufen von base die Außerkraftsetzung überspringen.Introducing an override might cause previous consumers to skip over the override when calling base.

  • ✔️ ZULÄSSIG: Hinzufügen eines Konstruktors zu einer Klasse, gemeinsam mit einem Konstruktor (ohne Parameter), wenn die Klasse zuvor keine Konstruktoren hatte✔️ ALLOWED: Adding a constructor to a class, along with a parameterless constructor if the class previously had no constructors

    Das Hinzufügen eines Konstruktors zu einer Klasse, die bisher keine Konstruktoren hatte, ohne den parameterlosen Konstruktor hinzuzufügen, ist jedoch nicht zulässig.However, adding a constructor to a class that previously had no constructors without adding the parameterless constructor is not allowed.

  • ✔️ ZULÄSSIG: Ändern eines Members von abstrakt zu virtuell✔️ ALLOWED: Changing a member from abstract to virtual

  • ✔️ ZULÄSSIG: Wechseln von einem ref readonly- zu einem ref-Rückgabewert (mit Ausnahme von virtuellen Methoden oder Schnittstellen)✔️ ALLOWED: Changing from a ref readonly to a ref return value (except for virtual methods or interfaces)

  • ✔️ ZULÄSSIG: Entfernen von readonly aus einem Feld, es sei denn, der statische Typ des Felds ist ein veränderlicher Werttyp✔️ ALLOWED: Removing readonly from a field, unless the static type of the field is a mutable value type

  • ✔️ ZULÄSSIG: Aufrufen eines bisher noch nicht definierten neuen Ereignisses✔️ ALLOWED: Calling a new event that wasn't previously defined

  • ERFORDERT BEURTEILUNG: Hinzufügen eines neuen Instanzenfelds zu einem TypREQUIRES JUDGMENT: Adding a new instance field to a type

    Diese Änderung wirkt sich auf die Serialisierung aus.This change impacts serialization.

  • NICHT ZULÄSSIG: Umbenennen oder Entfernen eines öffentlichen Members oder ParametersDISALLOWED: Renaming or removing a public member or parameter

    Dies unterbricht sämtlichen Code, der den umbenannten oder entfernten Member oder Parameter verwendet.This breaks all code that uses the renamed or removed member, or parameter.

    Dazu gehört auch das Entfernen oder Umbenennen eines Getters oder Setters aus einer Eigenschaft sowie das Umbenennen oder Entfernen von Enumerationsmembern.This includes removing or renaming a getter or setter from a property, as well as renaming or removing enumeration members.

  • NICHT ZULÄSSIG: Hinzufügen eines Members zu einer SchnittstelleDISALLOWED: Adding a member to an interface

  • NICHT ZULÄSSIG: Ändern des Werts einer öffentlichen Konstante oder des EnumerationsmembersDISALLOWED: Changing the value of a public constant or enumeration member

  • NICHT ZULÄSSIG: Ändern des Typs einer Eigenschaft, eines Felds, eines Parameters oder eines RückgabewertsDISALLOWED: Changing the type of a property, field, parameter, or return value

  • NICHT ZULÄSSIG: Hinzufügen, Entfernen oder Ändern der Reihenfolge von ParameternDISALLOWED: Adding, removing, or changing the order of parameters

  • NICHT ZULÄSSIG: Hinzufügen oder Entfernen der Schlüsselwörter in, out oder ref zu oder aus einem ParameterDISALLOWED: Adding or removing the in, out , or ref keyword from a parameter

  • NICHT ZULÄSSIG: Umbenennen eines Parameters (einschließlich der Änderung der Groß-/Kleinbuchschreibung)DISALLOWED: Renaming a parameter (including changing its case)

    Dies gilt aus zwei Gründen als Unterbrechung:This is considered breaking for two reasons:

  • NICHT ZULÄSSIG: Wechseln von einem ref- zu einem ref readonly-RückgabewertDISALLOWED: Changing from a ref return value to a ref readonly return value

  • ❌️ NICHT ZULÄSSIG: Wechseln von einem ref readonly- zu einem ref-Rückgabewert bei einer virtuellen Methode oder Schnittstelle❌️ DISALLOWED: Changing from a ref readonly to a ref return value on a virtual method or interface

  • NICHT ZULÄSSIG: Hinzufügen oder Entfernen von abstract zu oder aus einem MemberDISALLOWED: Adding or removing abstract from a member

  • NICHT ZULÄSSIG: Entfernen des Schlüsselworts virtual aus einem MemberDISALLOWED: Removing the virtual keyword from a member

    Obwohl dies oft keinen Breaking Change darstellt, da der C#-Compiler dazu tendiert, zum Aufrufen nicht virtueller Methoden Intermediate Language (IL)-Anweisungen callvirt auszugeben (callvirt führt eine Prüfung auf NULL durch, was bei einem normalen Aufruf nicht der Fall ist), ist dieses Verhalten aus verschiedenen Gründe nicht unveränderlich: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# ist nicht die einzige Sprache, auf die .NET ausgerichtet ist.C# is not the only language that .NET targets.

    • Der C#-Compiler versucht zunehmend, callvirt für einen normalen Aufruf zu optimieren, wenn die Zielmethode nicht virtuell und wahrscheinlich nicht Null ist (z.B. eine Methode, auf die über den NULL-bedingten Operator „?“ zugegriffen wird).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).

    Aus einer Methode eine virtuelle Methode zu machen bedeutet, dass der Consumercode sie oft nicht virtuell aufruft.Making a method virtual means that the consumer code would often end up calling it non-virtually.

  • NICHT ZULÄSSIG: Hinzufügen des Schlüsselworts virtual zu einem MemberDISALLOWED: Adding the virtual keyword to a member

  • NICHT ZULÄSSIG: Umwandeln eines virtuellen Members in einen abstrakten MemberDISALLOWED: Making a virtual member abstract

    Ein virtueller Member stellt eine Methodenimplementierung bereit, die von einer abgeleiteten Klasse außer Kraft gesetzt werden kann.A virtual member provides a method implementation that can be overridden by a derived class. Ein abstrakter Member stellt keine Implementierung bereit und muss außer Kraft gesetzt werden.An abstract member provides no implementation and must be overridden.

  • NICHT ZULÄSSIG: Hinzufügen eines abstrakten-Members zu einem öffentlichen Typ mit zugänglichen (öffentlichen oder geschützten) Konstruktoren, der nicht versiegelt istDISALLOWED: Adding an abstract member to a public type that has accessible (public or protected) constructors and that is not sealed

  • NICHT ZULÄSSIG: Hinzufügen oder Entfernen des Schlüsselworts static zu oder aus einem MemberDISALLOWED: Adding or removing the static keyword from a member

  • NICHT ZULÄSSIG: Hinzufügen einer Überladung, die eine vorhandene Überladung ausschließt und ein anderes Verhalten definiertDISALLOWED: Adding an overload that precludes an existing overload and defines a different behavior

    Dies unterbricht vorhandene Clients, die an die vorherige Überladung gebunden waren.This breaks existing clients that were bound to the previous overload. Wenn eine Klasse beispielsweise eine einzelne Version einer Methode hat, die UInt32 akzeptiert, wird ein vorhandener Consumer erfolgreich an diese Überladung gebunden, wenn ein Int32-Wert übergeben wird.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. Wenn Sie jedoch eine Überladung hinzufügen, die Int32 akzeptiert, bindet sich der Compiler beim Neukompilieren oder beim Verwenden der späten Bindung an die neue Überladung.However, if you add an overload that accepts an Int32, when recompiling or using late-binding, the compiler now binds to the new overload. Wenn dies ein anderes Verhalten zur Folge hat, ist dies ein Breaking Change.If different behavior results, this is a breaking change.

  • NICHT ZULÄSSIG: Hinzufügen eines Konstruktors zu einer Klasse, die bisher keine Konstruktoren hatte, ohne den parameterlosen Konstruktor hinzuzufügenDISALLOWED: Adding a constructor to a class that previously had no constructor without adding the parameterless constructor

  • ❌️ NICHT ZULÄSSIG: Hinzufügen von readonly zu einem Feld❌️ DISALLOWED: Adding readonly to a field

  • NICHT ZULÄSSIG: Reduzieren der Sichtbarkeit eines MembersDISALLOWED: Reducing the visibility of a member

    Dazu gehört das Reduzieren der Sichtbarkeit eines geschützten Members, wenn zugängliche (public oder protected) Konstruktoren vorhanden sind und der Typ nicht versiegelt ist.This includes reducing the visibility of a protected member when there are accessible (public or protected) constructors and the type is not sealed. Wenn dies nicht der Fall ist, ist das Reduzieren der Sichtbarkeit eines geschützten Members zulässig.If this is not the case, reducing the visibility of a protected member is allowed.

    Die Sichtbarkeit eines Members darf erhöht werden.Increasing the visibility of a member is allowed.

  • NICHT ZULÄSSIG: Ändern des Typs eines MembersDISALLOWED: Changing the type of a member

    Der Rückgabewert einer Methode oder der Typ einer Eigenschaft oder eines Feldes kann nicht geändert werden.The return value of a method or the type of a property or field cannot be modified. So kann beispielsweise die Signatur einer Methode, die ein Object zurückgibt, nicht geändert werden, um ein String zurückzugeben, oder umgekehrt.For example, the signature of a method that returns an Object cannot be changed to return a String, or vice versa.

  • NICHT ZULÄSSIG: Hinzufügen eines Felds zu einer Struktur, die bisher keinen Status hatteDISALLOWED: Adding a field to a struct that previously had no state

    Definitive Zuweisungsregeln erlauben die Verwendung von nicht initialisierten Variablen, sofern der Variablentyp eine zustandslose Struktur ist.Definite assignment rules allow the use of uninitialized variables so long as the variable type is a stateless struct. Wenn die Struktur zustandsbehaftet gemacht wird, könnte der Code nicht initialisierte Daten erhalten.If the struct is made stateful, code could end up with uninitialized data. Dies ist möglicherweise sowohl ein Quell-Breaking Change als auch ein binärer Breaking Change.This is both potentially a source breaking and a binary breaking change.

  • NICHT ZULÄSSIG: Auslösen eines vorhandenen Ereignisses, das bisher noch nicht ausgelöst wurdeDISALLOWED: Firing an existing event when it was never fired before

VerhaltensänderungBehavioral changes

AssemblysAssemblies

  • ✔️ ZULÄSSIG: Übertragbarmachen einer Assembly, wenn dieselben Plattformen weiterhin unterstützt werden✔️ ALLOWED: Making an assembly portable when the same platforms are still supported

  • NICHT ZULÄSSIG: Ändern des Namens einer AssemblyDISALLOWED: Changing the name of an assembly

  • NICHT ZULÄSSIG: Ändern des öffentlichen Schlüssels einer AssemblyDISALLOWED: Changing the public key of an assembly

Eigenschaften, Felder, Parameter und RückgabewerteProperties, fields, parameters, and return values

  • ✔️ ZULÄSSIG: Ändern des Werts einer Eigenschaft, eines Felds, eines Rückgabewerts oder eines out-Parameters in einen stärker abgeleiteten Typ✔️ ALLOWED: Changing the value of a property, field, return value, or out parameter to a more derived type

    Beispielsweise kann eine Methode, die einen Typ von Object zurückgibt, eine String-Instanz zurückgeben.For example, a method that returns a type of Object can return a String instance. (Allerdings kann nicht die Signatur der Methode nicht geändert werden.)(However, the method signature cannot change.)

  • ✔️ ZULÄSSIG: Erhöhen des Bereichs der zulässigen Werte für eine Eigenschaft oder einen Parameter, wenn der Member nicht virtuell ist✔️ ALLOWED: Increasing the range of accepted values for a property or parameter if the member is not virtual

    Der Bereich der Werte, die an die Methode übergeben werden können oder vom Member zurückgegeben werden, kann erweitert werden, der Parameter- oder der Membertyp jedoch nicht.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. Beispielsweise können die an eine Methode übergebenen Werte von 0-124 auf 0-255 erweitert werden, der Parametertyp kann jedoch nicht von Byte in Int32 geändert werden.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.

  • NICHT ZULÄSSIG: Erweitern des Bereichs der zulässigen Werte für eine Eigenschaft oder einen Parameter, wenn der Member virtuell istDISALLOWED: Increasing the range of accepted values for a property or parameter if the member is virtual

    Diese Änderung unterbricht bestehende, außer Kraft gesetzte Member, die für den erweiterten Wertebereich dann nicht korrekt funktionieren.This change breaks existing overridden members, which will not function correctly for the extended range of values.

  • NICHT ZULÄSSIG: Verkleinern des Bereichs der zulässigen Werte für eine Eigenschaft oder einen ParameterDISALLOWED: Decreasing the range of accepted values for a property or parameter

  • NICHT ZULÄSSIG: Erweitern des Bereichs der zurückgegebenen Werte für eine Eigenschaft, ein Feld, einen Rückgabewert oder den out-ParameterDISALLOWED: Increasing the range of returned values for a property, field, return value, or out parameter

  • NICHT ZULÄSSIG: Ändern der zurückgegebenen Werte für eine Eigenschaft, ein Feld, einen Rückgabewert einer Methode oder den out-ParameterDISALLOWED: Changing the returned values for a property, field, method return value, or out parameter

  • NICHT ZULÄSSIG: Ändern des Standardwerts einer Eigenschaft, eines Felds oder eines ParametersDISALLOWED: Changing the default value of a property, field, or parameter

  • NICHT ZULÄSSIG: Ändern der Genauigkeit eines numerischen RückgabewertsDISALLOWED: Changing the precision of a numeric return value

  • ERFORDERT BEURTEILUNG: Eine Änderung im Analysieren von Eingaben und das Auslösen neuer Ausnahmen (auch wenn das Analyseverhalten nicht in der Dokumentation angegeben ist)REQUIRES JUDGMENT: A change in the parsing of input and throwing new exceptions (even if parsing behavior is not specified in the documentation

AusnahmenExceptions

  • ✔️ ZULÄSSIG: Auslösen einer Ausnahme, die stärker abgeleitet ist als eine vorhandene✔️ ALLOWED: Throwing a more derived exception than an existing exception

    Da die neue Ausnahme eine Unterklasse einer vorhandenen Ausnahme ist, wird der bisherige Code zur Ausnahmebehandlung die Ausnahme weiterhin behandeln.Because the new exception is a subclass of an existing exception, previous exception handling code continues to handle the exception. In .NET Framework 4 wurden bei der Kulturerstellung und bei Abrufmethoden eine CultureNotFoundException anstelle einer ArgumentException ausgelöst, wenn die Kultur nicht gefunden werden konnte.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. Da sich CultureNotFoundException aus ArgumentException ableitet, ist dies eine zulässige Änderung.Because CultureNotFoundException derives from ArgumentException, this is an acceptable change.

  • ✔️ ZULÄSSIG: Auslösen einer spezifischeren Ausnahme als NotSupportedException, NotImplementedException, NullReferenceException✔️ ALLOWED: Throwing a more specific exception than NotSupportedException, NotImplementedException, NullReferenceException

  • ✔️ ZULÄSSIG: Auslösen einer Ausnahme, die als nicht behebbar gilt✔️ ALLOWED: Throwing an exception that is considered unrecoverable

    Nicht behebbare Ausnahmen sollten nicht abgefangen werden, sondern von einem übergeordneten Catch-All-Handler behandelt werden.Unrecoverable exceptions should not be caught but instead should be handled by a high-level catch-all handler. Daher wird nicht erwartet, dass Benutzer über Code verfügen, der diese expliziten Ausnahmen abfängt.Therefore, users are not expected to have code that catches these explicit exceptions. Nicht behebbare Ausnahmen sind:The unrecoverable exceptions are:

  • ✔️ ZULÄSSIG: Auslösen einer neuen Ausnahme in einem neuen Codepfad✔️ ALLOWED: Throwing a new exception in a new code path

    Die Ausnahme darf nur für einen neuen Codepfad gelten, der mit neuen Parameterwerten oder einen neuen Zustand ausgeführt wird, und der nicht mit vorhandenem Code ausgeführt werden kann, der auf die vorherige Version abzielt.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.

  • ✔️ ZULÄSSIG: Entfernen eine Ausnahme, um ein stabileres Verhalten oder neue Szenarios zu ermöglichen✔️ ALLOWED: Removing an exception to enable more robust behavior or new scenarios

    So kann beispielsweise eine Divide-Methode, die bisher nur positive Werte behandelt und andernfalls ein ArgumentOutOfRangeException ausgelöst hat, so geändert werden, dass sowohl negative als auch positive Werte unterstützt werden, ohne eine Ausnahme auszulösen.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.

  • ✔️ ZULÄSSIG: Ändern des Texts einer Fehlermeldung✔️ ALLOWED: Changing the text of an error message

    Entwickler sollten sich nicht auf den Text von Fehlermeldungen verlassen, die sich auch aufgrund der Kultur des Benutzers ändern.Developers should not rely on the text of error messages, which also change based on the user's culture.

  • NICHT ZULÄSSIG: Auslösen einer Ausnahme in allen Fällen, die oben nicht aufgeführt sindDISALLOWED: Throwing an exception in any other case not listed above

  • NICHT ZULÄSSIG: Entfernen einer Ausnahme in allen Fällen, die oben nicht aufgeführt sindDISALLOWED: Removing an exception in any other case not listed above

AttributeAttributes

  • ✔️ ZULÄSSIG: Ändern des Werts eines Attributs, das nicht überwachbar ist✔️ ALLOWED: Changing the value of an attribute that is not observable

  • NICHT ZULÄSSIG: Ändern des Werts eines Attributs, das überwachbar istDISALLOWED: Changing the value of an attribute that is observable

  • ERFORDERT BEURTEILUNG: Entfernen eines AttributsREQUIRES JUDGMENT: Removing an attribute

    In den meisten Fällen ist das Entfernen eines Attributs (wie NonSerializedAttribute) ein Breaking Change.In most cases, removing an attribute (such as NonSerializedAttribute) is a breaking change.

PlattformunterstützungPlatform support

  • ✔️ ZULÄSSIG: Unterstützen eines Vorgangs auf einer Plattform, der bisher nicht unterstützt wurde✔️ ALLOWED: Supporting an operation on a platform that was previously not supported

  • NICHT ZULÄSSIG: Keine Unterstützung oder das Erfordern eines bestimmten Service Packs für einen Vorgang, der zuvor auf einer Plattform unterstützt wurdeDISALLOWED: Not supporting or now requiring a specific service pack for an operation that was previously supported on a platform

Änderungen an der internen ImplementierungInternal implementation changes

  • ERFORDERT BEURTEILUNG: Ändern der Oberfläche eines internen TypsREQUIRES JUDGMENT: Changing the surface area of an internal type

    Derartige Änderungen sind im Allgemeinen zulässig, auch wenn sie die private Reflektion unterbrechen.Such changes are generally allowed, although they break private reflection. In einigen Fällen, in denen beliebte Bibliotheken von Drittanbietern oder eine große Anzahl von Entwicklern von den internen APIs abhängen, sind solche Änderungen möglicherweise nicht zulässig.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.

  • ERFORDERT BEURTEILUNG: Ändern der internen Implementierung eines MembersREQUIRES JUDGMENT: Changing the internal implementation of a member

    Diese Änderungen sind im Allgemeinen zulässig, auch wenn sie die private Reflektion unterbrechen.These changes are generally allowed, although they break private reflection. In einigen Fällen, in denen der Kundencode häufig von privater Reflexion abhängt, oder in denen die Änderung unbeabsichtigte Nebenwirkungen mit sich bringt, sind diese Änderungen möglicherweise nicht zulässig.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.

  • ✔️ ZULÄSSIG: Verbessern der Leistung eines Vorgangs✔️ ALLOWED: Improving the performance of an operation

    Die Möglichkeit, die Leistung eines Vorgangs zu ändern, ist unerlässlich, aber solche Änderungen können Code unterbrechen, der von der aktuellen Geschwindigkeit eines Vorgangs abhängt.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. Dies gilt insbesondere für Code, der vom Zeitpunkt des asynchronen Vorgangs abhängt.This is particularly true of code that depends on the timing of asynchronous operations. Die Leistungsänderung sollte keinen Einfluss auf das andere Verhalten der betreffenden API haben; andernfalls ist diese Änderung ein Breaking Change.The performance change should have no effect on other behavior of the API in question; otherwise, the change will be breaking.

  • ✔️ ZULÄSSIG: Indirektes (und häufig negatives) Ändern der Leistung eines Vorgangs✔️ ALLOWED: Indirectly (and often adversely) changing the performance of an operation

    Wenn die betreffende Änderung aus einem sonstigen Grund nicht als Breaking Change eingestuft wird, ist dies zulässig.If the change in question is not categorized as breaking for some other reason, this is acceptable. Häufig müssen Maßnahmen ergriffen werden, die zusätzliche Vorgänge beinhalten können oder neue Funktionen hinzufügen.Often, actions need to be taken that may include extra operations or that add new functionality. Dies hat fast immer Auswirkungen auf die Leistung, kann aber unerlässlich sein, damit die betreffende API wie erwartet funktioniert.This will almost always affect performance but may be essential to make the API in question function as expected.

  • NICHT ZULÄSSIG: Ändern einer synchronen API in eine asynchrone API (und umgekehrt)DISALLOWED: Changing a synchronous API to asynchronous (and vice versa)

CodeänderungenCode changes

  • ✔️ ZULÄSSIG: Hinzufügen von params zu einem Parameter✔️ ALLOWED: Adding params to a parameter

  • NICHT ZULÄSSIG: Ändern einer Struktur in eine Klasse und umgekehrtDISALLOWED: Changing a struct to a class and vice versa

  • NICHT ZULÄSSIG: Hinzufügen des Schlüsselworts checked zu einem CodeblockDISALLOWED: Adding the checked keyword to a code block

    Diese Änderung kann dazu führen, dass Code, der zuvor so ausgeführt wurde, eine OverflowException ausgelöst. Dies ist nicht zulässig.This change may cause code that previously executed to throw an OverflowException and is unacceptable.

  • NICHT ZULÄSSIG: Entfernen von params aus einem ParameterDISALLOWED: Removing params from a parameter

  • NICHT ZULÄSSIG: Ändern der Reihenfolge, in der Ereignisse ausgelöst werdenDISALLOWED: Changing the order in which events are fired

    Entwickler können vernünftigerweise erwarten, dass Ereignisse in der gleichen Reihenfolge ausgelöst werden, und Entwicklercode hängt häufig von der Reihenfolge ab, in der Ereignisse ausgelöst werden.Developers can reasonably expect events to fire in the same order, and developer code frequently depends on the order in which events are fired.

  • NICHT ZULÄSSIG: Entfernen des Auftretens eines Ereignisses für eine bestimmte AktionDISALLOWED: Removing the raising of an event on a given action

  • NICHT ZULÄSSIG: Ändern, wie oft bestimmte Ereignisse aufgerufen werdenDISALLOWED: Changing the number of times given events are called

  • NICHT ZULÄSSIG: Hinzufügen von FlagsAttribute zu einem EnumerationstypDISALLOWED: Adding the FlagsAttribute to an enumeration type