Ä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.

Dieser Artikel beschreibt die Kategorien von Kompatibilitätsänderungen (oder Breaking Changes) und die Art und Weise, wie das .NET-Team Änderungen in jeder dieser Kategorien bewertet.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. Zu verstehen, wie das .NET-Team mit möglichen Breaking Changes umgeht, ist besonders hilfreich für Entwickler, die Pull Requests im GitHub-Repository dotnet/runtime öffnen, das das Verhalten bestehender APIs ändert.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.

Hinweis

Eine Definition von Kompatibilitätskategorien, wie z.B. Binärkompatibilität und Abwärtskompatibilität, finden Sie unter Breaking Change-Kategorien.For a definition of compatibility categories, such as binary compatibility and backward compatibility, see Breaking change categories.

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 describes the categories of changes made to .NET Core APIs and their impact on application compatibility. Das Symbol ✔️ gibt an, dass eine bestimmte Art von Änderung zulässig ist. ❌ gibt an, dass sie nicht zulässig ist, und ❓ zeigt an, dass eine Änderung möglicherweise zulässig ist.The ✔️ icon indicates that a particular kind of change is allowed, ❌ indicates that it is disallowed, and ❓ indicates a change that may or may not be allowed. Bei Änderungen in dieser letzten Kategorie muss beurteilt und bewertet werden, wie vorhersehbar, offensichtlich und konsistent das bisherige Verhalten war.Changes in this last category require judgement 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 Core-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 Core libraries are evaluated, library developers can also use these criteria to evaluate changes to their libraries that target multiple .NET implementations and versions.

Ä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

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

  • ❓ Hinzufügen einer neuen Schnittstellenimplementierung zu einem Typ❓ 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.

  • ❓ Einführen einer neuen Basisklasse❓ Introducing a new base class

    Ein Typ kann in eine 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 an 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.

  • ✔️ Verschieben eines Typs von einer Assembly zu einer anderen✔️ Moving a type from one assembly to another

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

  • ✔️ Ändern des Typs struct in einen Typreadonly struct✔️ Changing a struct type to a readonly struct type

    Beachten Sie, dass ein readonly struct-Typ nicht in einen struct-Typ geändert werden darf.Note that changing a readonly struct type to a struct type is not allowed.

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

  • ✔️ Erweitern der Sichtbarkeit eines Typs✔️ Expanding the visibility of a type

  • ❌ Ändern des Namespace oder des Namens eines Typs❌ Changing the namespace or name of a type

  • ❌ Umbenennen oder Entfernen eines öffentlichen Typs❌ 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.

  • ❌ Ändern des einer Enumeration zugrunde liegenden Typs❌ 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.

  • ❌ Versiegeln eines bisher nicht versiegelten Typs❌ Sealing a type that was previously unsealed

  • ❌ Hinzufügen einer Schnittstelle zur Menge der Basistypen einer Schnittstelle❌ 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.

  • ❓ Entfernen eine Klasse aus der Menge von Basisklassen oder einer Schnittstelle aus der Menge der implementierten Schnittstellen❓ 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.

  • ❌Ändern eines readonly struct-Typs in einen struct-Typ❌ Changing a readonly struct type to a struct type

    Beachten Sie, dass ein struct-Typ nicht in einen readonly struct-Typ geändert werden darf.Note that the change of a struct type to a readonly struct type is allowed.

  • ❌Ändern eines struct-Typs in einen ref struct-Typ (und umgekehrt)❌ Changing a struct type to a ref struct type, and vice versa

  • ❌ Reduzieren der Sichtbarkeit eines Typs❌ 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

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

  • ✔️ 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✔️ 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.

  • ✔️ 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✔️ Restricting the visibility of a protected member when the type has no accessible (public or protected) constructors, or the type is sealed

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

  • ✔️ Hinzufügen oder Entfernen einer Außerkraftsetzung✔️ Adding or removing an override

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

  • ✔️ Hinzufügen eines Konstruktors zu einer Klasse, gemeinsam mit einem Konstruktor (ohne Parameter), wenn die Klasse zuvor keine Konstruktoren hatte✔️ 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.

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

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

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

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

  • ❓ Hinzufügen eines neuen Instanzenfelds zu einem Typ❓ Adding a new instance field to a type

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

  • ❌ Umbenennen oder Entfernen eines öffentlichen Members oder Parameters❌ 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.

    Beachten Sie, dass dazu auch das Entfernen oder Umbenennen eines Getters oder Setters aus einer Eigenschaft sowie das Umbenennen oder Entfernen von Enumerationsmembern gehört.Note that this includes removing or renaming a getter or setter from a property, as well as renaming or removing enumeration members.

  • ❌ Hinzufügen eines Members zu einer Schnittstelle❌ Adding a member to an interface

  • ❌ Ändern des Werts eine öffentlichen Konstanten oder des Enumerationsmember❌ Changing the value of a public constant or enumeration member

  • ❌ Ändern des Typs einer Eigenschaft, eines Felds, Parameters oder Rückgabewerts❌ Changing the type of a property, field, parameter, or return value

  • ❌ Hinzufügen, Entfernen oder Ändern der Reihenfolge von Parametern❌ Adding, removing, or changing the order of parameters

  • ❌ Hinzufügen oder Entfernen der Schlüsselwörter in, out oder ref zu oder aus einem Parameter❌ Adding or removing the in, out , or ref keyword from a parameter

  • ❌ Umbenennen eines Parameters (einschließlich der Änderung der Groß-/Kleinbuchschreibung)❌ Renaming a parameter (including changing its case)

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

  • ❌ Wechseln von einem ref- zu einem ref readonly-Rückgabewert❌ Changing from a ref return value to a ref readonly return value

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

  • ❌ Hinzufügen oder Entfernen von abstract zu oder aus einem Member❌ Adding or removing abstract from a member

  • ❌ Entfernen des Schlüsselworts virtual aus einem Member❌ 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.

  • ❌ Hinzufügen des Schlüsselworts virtual zu einem Member❌ Adding the virtual keyword to a member

  • ❌ Umwandeln eines virtuellen Members in einen abstrakten Member❌ 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.

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

  • ❌ Hinzufügen oder Entfernen des Schlüsselworts static zu oder aus einem Member❌ Adding or removing the static keyword from a member

  • ❌ Hinzufügen einer Überladung, die eine vorhandene Überladung ausschließt und ein anderes Verhalten definiert❌ 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.

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

  • ❌ Hinzufügen von readonly zu einem Feld❌️ Adding readonly to a field

  • ❌ Reduzieren der Sichtbarkeit eines Members❌ Reducing the visibility of a member

    Dazu gehört das Reduzieren der Sichtbarkeit eines geschützten Members, wenn zugängliche (öffentliche oder geschützte) 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.

    Beachten Sie, dass die Sichtbarkeit eines Members erhöht werden darf.Note that increasing the visibility of a member is allowed.

  • ❌ Ändern des Typs eines Members❌ 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.

  • ❌ Hinzufügen eines Felds zu einer Struktur, die bisher keinen Status hatte❌ 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.

  • ❌ Auslösen eines vorhandenen Ereignisses, das bisher noch nicht ausgelöst wurde❌ Firing an existing event when it was never fired before

VerhaltensänderungBehavioral changes

AssemblysAssemblies

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

  • ❌ Ändern des Namens einer Assembly❌ Changing the name of an assembly

  • ❌ Ändern des öffentlichen Schlüssels einer Assembly❌ Changing the public key of an assembly

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

  • ✔️ Ändern des Wertes einer Eigenschaft, eines Feldes, eines Rückgabewertes oder eines out-Parameters in einen stärker abgeleiteten Typ✔️ 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.)

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

    Beachten Sie, dass der Bereich der Werte, die an die Methode übergeben werden können oder vom Member zurückgegeben werden, erweitert werden kann, der Parameter- oder der Membertyp jedoch nicht.Note that 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.

  • ❌ Erweitern des Bereichs der zulässigen Werte für eine Eigenschaft oder einen Parameter, wenn der Member virtuell ist❌ 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.

  • ❌ Verkleinern des Bereichs der zulässigen Werte für eine Eigenschaft oder einen Parameter❌ Decreasing the range of accepted values for a property or parameter

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

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

  • ❌ Ändern des Standardwerts einer Eigenschaft, eines Felds oder eines Parameters❌ Changing the default value of a property, field, or parameter

  • ❌ Ändern der Genauigkeit eines numerischen Rückgabewerts❌ Changing the precision of a numeric return value

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

AusnahmenExceptions

  • ✔️ Auslösen einer Ausnahme, die stärker abgeleitet ist als eine vorhandene✔️ 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.

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

  • ✔️ Auslösen einer Ausnahme, die als nicht behebbar gilt✔️ 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:

  • ✔️ Auslösen einer neuen Ausnahme in einem neuen Codepfad✔️ 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 which is executed with new parameter values or state, and that can't be executed by existing code that targets the previous version.

  • ✔️ Entfernen eine Ausnahme aus, um ein stabileres Verhalten oder neue Szenarien zu ermöglichen✔️ 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.

  • ✔️ Ändern des Textes einer Fehlermeldung✔️ 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.

  • ❌ Auslösen einer Ausnahme in allen anderen Fällen, die oben nicht aufgeführt sind❌ Throwing an exception in any other case not listed above

  • ❌ Entfernen einer Ausnahme in allen anderen Fällen, die oben nicht aufgeführt sind❌ Removing an exception in any other case not listed above

AttributeAttributes

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

  • ❌ Ändern des Werts eines Attributs, das überwachbar ist❌ Changing the value of an attribute that is observable

  • ❓ Entfernen eines Attributs❓ 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

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

  • ❌ Keine Unterstützung oder das Erfordern eines bestimmten Service Packs für einen Vorgang, der zuvor auf einer Plattform unterstützt wurde❌ 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

  • ❓ Ändern der Oberfläche eines internen Typs❓ 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.

  • ❓Ändern der internen Implementierung eines Members❓ 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.

  • ✔️ Verbessern der Leistung eines Vorgangs✔️ 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. Beachten Sie, dass die Leistungsänderung keinen Einfluss auf das andere Verhalten der betreffenden API haben sollte; andernfalls ist diese Änderung ein Breaking Change.Note that the performance change should have no effect on other behavior of the API in question; otherwise, the change will be breaking.

  • ✔️ Indirektes (und häufig negatives) Ändern der Leistung eines Vorgangs✔️ 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.

  • ❌ Ändern einer synchronen API in eine asynchrone API (und umgekehrt)❌ Changing a synchronous API to asynchronous (and vice versa)

CodeänderungenCode changes

  • ✔️ Hinzufügen von params zu einem Parameter✔️ Adding params to a parameter

  • ❌ Ändern einer Struktur in eine Klasse und umgekehrt❌ Changing a struct to a class and vice versa

  • ❌ Hinzufügen des Schlüsselworts checked zu einem Codeblock❌ 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.

  • ❌ Entfernen von params aus einem Parameter❌ Removing params from a parameter

  • ❌ Ändern der Reihenfolge, in der Ereignisse ausgelöst werden❌ 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.

  • ❌ Entfernen das Auftretens eines Ereignisses für eine bestimmte Aktion❌ Removing the raising of an event on a given action

  • ❌ Ändern, wie oft bestimmte Ereignisse aufgerufen werden❌ Changing the number of times given events are called

  • ❌ Hinzufügen von FlagsAttribute zu einem Enumerationstyp❌ Adding the FlagsAttribute to an enumeration type