Zmiany wpływające na zgodnośćChanges that affect compatibility

W całej historii środowisko .NET podjęło próbę utrzymania wysokiego poziomu zgodności z wersji do wersji i między implementacjami programu .NET.Throughout its history, .NET has attempted to maintain a high level of compatibility from version to version and across implementations of .NET. Chociaż programy .NET 5 (i .NET Core) i nowsze wersje można traktować jako nową technologię w porównaniu do .NET Framework, dwa główne czynniki ograniczają możliwość, że ta implementacja programu .NET będzie rozbieżna od .NET Framework:Although .NET 5 (and .NET Core) and later versions can be considered as a new technology compared to .NET Framework, two major factors limit the ability of this implementation of .NET to diverge from .NET Framework:

  • Duża liczba deweloperów pierwotnie opracowała lub kontynuowała opracowywanie .NET Framework aplikacji.A large number of developers either originally developed or continue to develop .NET Framework applications. Oczekują one spójnego zachowania w implementacjach platformy .NET.They expect consistent behavior across .NET implementations.

  • .NET Standard projekty biblioteki umożliwiają deweloperom tworzenie bibliotek przeznaczonych dla wspólnych interfejsów API współużytkowanych przez programy .NET Framework i .NET 5 (oraz .NET Core) i nowszych..NET Standard library projects allow developers to create libraries that target common APIs shared by .NET Framework and .NET 5 (and .NET Core) and later versions. Deweloperzy oczekują, że biblioteka używana w aplikacji .NET 5 powinna zachowywać się identycznie z tą samą biblioteką używaną w aplikacji .NET Framework.Developers expect that a library used in a .NET 5 application should behave identically to the same library used in a .NET Framework application.

Wraz ze zgodnością w ramach implementacji platformy .NET deweloperzy oczekują wysokiego poziomu zgodności między wersjami danej implementacji platformy .NET.Along with compatibility across .NET implementations, developers expect a high level of compatibility across versions of a given implementation of .NET. W szczególności kod zapisany dla starszej wersji programu .NET Core powinien działać bezproblemowo w programie .NET 5 lub jego nowszej wersji.In particular, code written for an earlier version of .NET Core should run seamlessly on .NET 5 or a later version. W rzeczywistości wielu deweloperów oczekuje, że nowe interfejsy API znajdujące się w nowo wydanej wersji platformy .NET powinny również być zgodne z wersjami wstępnymi, w których zostały wprowadzone te interfejsy API.In fact, many developers expect that the new APIs found in newly released versions of .NET should also be compatible with the pre-release versions in which those APIs were introduced.

W tym artykule opisano zmiany, które mają wpływ na zgodność i sposób, w jaki zespół .NET oceni każdy typ zmiany.This article outlines changes that affect compatibility and the way in which the .NET team evaluates each type of change. Zrozumienie, w jaki sposób zespół platformy .NET poddaje potencjalne istotne zmiany, jest szczególnie przydatny dla deweloperów, którzy otwierają żądania ściągnięcia, które modyfikują zachowanie istniejących interfejsów API platformy .NET.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.

W poniższych sekcjach opisano kategorie zmian wprowadzonych w interfejsach API platformy .NET i ich wpływ na zgodność aplikacji.The following sections describe the categories of changes made to .NET APIs and their impact on application compatibility. Zmiany są dozwolone ✔️, niedozwolone ❌ lub wymagają orzeczenia oraz oceny, jak przewidywalne, oczywiste i spójne poprzednie zachowanie zostało ❓.Changes are either allowed ✔️, disallowed ❌, or require judgment and an evaluation of how predictable, obvious, and consistent the previous behavior was ❓.

Uwaga

  • Oprócz obsługi programu jako wskazówki dotyczącej oceny zmian w bibliotekach .NET, deweloperzy biblioteki mogą również używać tych kryteriów do oceny zmian w bibliotekach przeznaczonych dla wielu implementacji i wersji platformy .NET.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.
  • Aby uzyskać informacje dotyczące kategorii zgodności, na przykład zgodność z przekazywaniem dalej i wstecz, zobacz zgodność.For information about the compatibility categories, for example, forward and backwards compatibility, see Compatibility.

Modyfikacje kontraktu publicznegoModifications to the public contract

Zmiany w tej kategorii modyfikują publiczną powierzchnię typu.Changes in this category modify the public surface area of a type. Większość zmian w tej kategorii jest niedozwolona, ponieważ naruszają zgodność z poprzednimi wersjami (zdolność aplikacji, która została opracowana przy użyciu poprzedniej wersji interfejsu API do wykonania bez ponownej kompilacji w nowszej wersji).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).

TypyTypes

  • ✔️ dozwolone: usuwanie implementacji interfejsu z typu, gdy interfejs jest już zaimplementowany przez typ podstawowy✔️ ALLOWED: Removing an interface implementation from a type when the interface is already implemented by a base type

  • Wymaga orzeczenia: Dodawanie nowej implementacji interfejsu do typuREQUIRES JUDGMENT: Adding a new interface implementation to a type

    Jest to akceptowalna zmiana, ponieważ nie ma negatywnego wpływu na istniejących klientów.This is an acceptable change because it does not adversely affect existing clients. Wszelkie zmiany w typie muszą działać w granicach akceptowalnych zmian zdefiniowanych w tym miejscu dla nowej implementacji, która pozostanie akceptowalna.Any changes to the type must work within the boundaries of acceptable changes defined here for the new implementation to remain acceptable. Należy zachować szczególną ostrożność przy dodawaniu interfejsów, które bezpośrednio wpływają na zdolność projektanta lub serializatorów do generowania kodu lub danych, których nie można użyć na poziomie niskiego poziomu.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. Przykładem jest ISerializable interfejs.An example is the ISerializable interface.

  • Wymaga orzeczenia: wprowadzenie nowej klasy bazowejREQUIRES JUDGMENT: Introducing a new base class

    Typ może być wprowadzany do hierarchii między dwoma istniejącymi typami, jeśli nie wprowadza żadnych nowych abstrakcyjnych elementów członkowskich lub zmiany semantyki lub zachowania istniejących typów.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. Na przykład w .NET Framework 2,0, DbConnection Klasa stał się nową klasą bazową dla SqlConnection , która wcześniej była bezpośrednio pochodną 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.

  • ✔️ dozwolone: przeniesienie typu z jednego zestawu do innego✔️ ALLOWED: Moving a type from one assembly to another

    Stary zestaw musi być oznaczony jako TypeForwardedToAttribute wskazujący nowy zestaw.The old assembly must be marked with the TypeForwardedToAttribute that points to the new assembly.

  • ✔️ dozwolone: zmiana typu struktury na readonly struct Typ✔️ ALLOWED: Changing a struct type to a readonly struct type

    Zmiana readonly struct typu na struct Typ jest niedozwolona.Changing a readonly struct type to a struct type is not allowed.

  • ✔️ dozwolone: dodanie zapieczętowanego lub abstrakcyjnego słowa kluczowego do typu w przypadku braku dostępnych (publicznych lub chronionych) konstruktorów✔️ ALLOWED: Adding the sealed or abstract keyword to a type when there are no accessible (public or protected) constructors

  • ✔️ dozwolone: rozszerzanie widoczności typu✔️ ALLOWED: Expanding the visibility of a type

  • Niedozwolone: zmiana przestrzeni nazw lub nazwy typuDISALLOWED: Changing the namespace or name of a type

  • Niedozwolone: zmiana nazwy lub usunięcie typu publicznegoDISALLOWED: Renaming or removing a public type

    Spowoduje to przerwanie całego kodu, który używa nazwy lub usuniętego typu.This breaks all code that uses the renamed or removed type.

  • Niedozwolone: zmiana typu podstawowego wyliczeniaDISALLOWED: Changing the underlying type of an enumeration

    Jest to niezależna od czasu kompilowania i zachowania zmiana, a także zmiana podziału binarnego, która może sprawiać, że argumenty atrybutów nie są przewidziane do przeanalizowania.This is a compile-time and behavioral breaking change as well as a binary breaking change that can make attribute arguments unparsable.

  • Niedozwolone: opieczętowanie typu, który był wcześniej niezapieczętowanyDISALLOWED: Sealing a type that was previously unsealed

  • Niedozwolone: Dodawanie interfejsu do zestawu typów podstawowych interfejsuDISALLOWED: Adding an interface to the set of base types of an interface

    Jeśli interfejs implementuje interfejs, który wcześniej nie został zaimplementowany, wszystkie typy, które implementują oryginalną wersję interfejsu, są uszkodzone.If an interface implements an interface that it previously did not implement, all types that implemented the original version of the interface are broken.

  • Wymaga orzeczenia: usunięcie klasy z zestawu klas bazowych lub interfejsu z zestawu zaimplementowanych interfejsówREQUIRES JUDGMENT: Removing a class from the set of base classes or an interface from the set of implemented interfaces

    Istnieje jeden wyjątek dla reguły usuwania interfejsu: można dodać implementację interfejsu, która pochodzi od usuniętego interfejsu.There is one exception to the rule for interface removal: you can add the implementation of an interface that derives from the removed interface. Można na przykład usunąć, IDisposable czy typ lub interfejs implementuje teraz IComponent , który implementuje IDisposable .For example, you can remove IDisposable if the type or interface now implements IComponent, which implements IDisposable.

  • Niedozwolone: zmiana readonly struct typu na typ strukturyDISALLOWED: Changing a readonly struct type to a struct type

    structMożna jednak zmienić typ na readonly struct Typ.The change of a struct type to a readonly struct type is allowed, however.

  • Niedozwolone: zmiana typu struktury na ref struct Typ i odwrotnieDISALLOWED: Changing a struct type to a ref struct type, and vice versa

  • Niedozwolone: zmniejszanie widoczności typuDISALLOWED: Reducing the visibility of a type

    Jednak zwiększenie widoczności typu jest dozwolone.However, increasing the visibility of a type is allowed.

Elementy członkowskieMembers

  • ✔️ dozwolone: rozszerzanie widoczności elementu członkowskiego, który nie jest wirtualny✔️ ALLOWED: Expanding the visibility of a member that is not virtual

  • ✔️ dozwolone: Dodawanie abstrakcyjnej składowej do typu publicznego, który nie ma dostępnych (publicznych lub chronionych) konstruktorów lub typ jest zapieczętowany✔️ ALLOWED: Adding an abstract member to a public type that has no accessible (public or protected) constructors, or the type is sealed

    Jednak dodanie abstrakcyjnej składowej do typu, który ma dostępne (publiczne lub chronione) konstruktorów, i nie sealed jest dozwolone.However, adding an abstract member to a type that has accessible (public or protected) constructors and is not sealed is not allowed.

  • ✔️ dozwolone: ograniczanie widoczności chronionego elementu członkowskiego, gdy typ nie ma dostępnych (publicznych lub chronionych) konstruktorów lub typ jest zapieczętowany✔️ ALLOWED: Restricting the visibility of a protected member when the type has no accessible (public or protected) constructors, or the type is sealed

  • ✔️ dozwolone: przeniesienie elementu członkowskiego do klasy wyższej w hierarchii niż typ, z którego został usunięty✔️ ALLOWED: Moving a member into a class higher in the hierarchy than the type from which it was removed

  • ✔️ dozwolone: Dodawanie lub usuwanie przesłonięcia✔️ ALLOWED: Adding or removing an override

    Wprowadzenie przesłonięcia może spowodować, że poprzedni odbiorcy pominięcia przesłonięcia podczas wywoływania podstawy.Introducing an override might cause previous consumers to skip over the override when calling base.

  • ✔️ dozwolone: Dodawanie konstruktora do klasy wraz z konstruktorem bez parametrów, jeśli Klasa nie miała wcześniej konstruktorów✔️ ALLOWED: Adding a constructor to a class, along with a parameterless constructor if the class previously had no constructors

    Jednak dodanie konstruktora do klasy, która wcześniej nie miała konstruktorów bez dodawania konstruktora bezparametrowego, nie jest dozwolone.However, adding a constructor to a class that previously had no constructors without adding the parameterless constructor is not allowed.

  • ✔️ dozwolone: zmiana składowej z abstrakcyjnej na wirtualną✔️ ALLOWED: Changing a member from abstract to virtual

  • ✔️ dozwolone: zmiana między a a ref readonly ref wartością zwracaną (z wyjątkiem metod wirtualnych lub interfejsów)✔️ ALLOWED: Changing from a ref readonly to a ref return value (except for virtual methods or interfaces)

  • ✔️ dozwolone: usuwanie elementu ReadOnly z pola, chyba że typ statyczny pola jest modyfikowalnym typem wartości✔️ ALLOWED: Removing readonly from a field, unless the static type of the field is a mutable value type

  • ✔️ dozwolone: wywoływanie nowego zdarzenia, które nie zostało wcześniej zdefiniowane✔️ ALLOWED: Calling a new event that wasn't previously defined

  • Wymaga orzeczenia: dodanie nowego pola wystąpienia do typuREQUIRES JUDGMENT: Adding a new instance field to a type

    Ta zmiana wpływa na serializację.This change impacts serialization.

  • Niedozwolone: zmiana nazwy lub usunięcie publicznego elementu członkowskiego lub parametruDISALLOWED: Renaming or removing a public member or parameter

    Spowoduje to przerwanie całego kodu, który używa nazwy lub usuniętego elementu członkowskiego lub parametru.This breaks all code that uses the renamed or removed member, or parameter.

    Obejmuje to usunięcie lub zmianę nazwy metody pobierającej lub setter z właściwości, a także zmianę nazwy lub usunięcie elementów członkowskich wyliczenia.This includes removing or renaming a getter or setter from a property, as well as renaming or removing enumeration members.

  • Niedozwolone: Dodawanie elementu członkowskiego do interfejsuDISALLOWED: Adding a member to an interface

  • Niedozwolone: zmiana wartości stałej publicznej lub elementu członkowskiego wyliczeniaDISALLOWED: Changing the value of a public constant or enumeration member

  • Niedozwolone: zmiana typu właściwości, pola, parametru lub wartości zwracanejDISALLOWED: Changing the type of a property, field, parameter, or return value

  • Niedozwolone: Dodawanie, usuwanie lub zmiana kolejności parametrówDISALLOWED: Adding, removing, or changing the order of parameters

  • Niedozwolone: Dodawanie lub usuwanie słowa kluczowego in, out lub ref z parametruDISALLOWED: Adding or removing the in, out , or ref keyword from a parameter

  • Niedozwolone: zmiana nazwy parametru (w tym zmiana jego wielkości liter)DISALLOWED: Renaming a parameter (including changing its case)

    Jest to uważane za rozdzielenie z dwóch powodów:This is considered breaking for two reasons:

  • Niedozwolone: zmiana ref wartości zwracanej na ref readonly wartość zwracanąDISALLOWED: Changing from a ref return value to a ref readonly return value

  • ❌️Niedozwolone: zmiana z ref readonly na ref wartość zwracaną w wirtualnej metodzie lub interfejsie❌️ DISALLOWED: Changing from a ref readonly to a ref return value on a virtual method or interface

  • Niedozwolone: Dodawanie lub usuwanie abstrakcyjne z elementu członkowskiegoDISALLOWED: Adding or removing abstract from a member

  • Niedozwolone: Usuwanie wirtualnego słowa kluczowego z elementu członkowskiegoDISALLOWED: Removing the virtual keyword from a member

    Chociaż często nie jest to istotna zmiana, ponieważ kompilator języka C# zamierza emitować instrukcje języka pośredniego (IL) elementu callvirt do wywoływania metod niewirtualnych ( callvirt wykonuje sprawdzanie wartości null, podczas gdy normalne wywołanie nie jest), to zachowanie nie jest zmienne z kilku powodów: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# nie jest jedynym językiem, który jest obiektem docelowym platformy .NET.C# is not the only language that .NET targets.

    • Kompilator języka C# coraz bardziej próbuje zoptymalizować callvirt do normalnego wywołania, gdy metoda docelowa nie jest wirtualna i prawdopodobnie nie ma wartości null (na przykład do uzyskania dostępu do metody za pomocą operatora propagacji?. null).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).

    Zastosowanie metody wirtualnej oznacza, że kod konsumenta często kończy wywoływanie go niepraktycznie.Making a method virtual means that the consumer code would often end up calling it non-virtually.

  • Niedozwolone: Dodawanie wirtualnego słowa kluczowego do elementu członkowskiegoDISALLOWED: Adding the virtual keyword to a member

  • Niedozwolone: wykonywanie abstrakcyjnej składowej wirtualnegoDISALLOWED: Making a virtual member abstract

    Wirtualny element członkowski zawiera implementację metody, która może zostać zastąpiona przez klasę pochodną.A virtual member provides a method implementation that can be overridden by a derived class. Abstrakcyjny element członkowski nie zawiera implementacji i musi zostać zastąpiony.An abstract member provides no implementation and must be overridden.

  • Niedozwolone: Dodawanie abstrakcyjnej składowej do typu publicznego, który ma dostępne (publiczne lub chronione) konstruktory, które nie jest zapieczętowaneDISALLOWED: Adding an abstract member to a public type that has accessible (public or protected) constructors and that is not sealed

  • Niedozwolone: Dodawanie lub usuwanie statycznego słowa kluczowego z elementu członkowskiegoDISALLOWED: Adding or removing the static keyword from a member

  • Niedozwolone: Dodawanie przeciążenia, które wyklucza istniejące Przeciążenie i definiuje inne zachowanieDISALLOWED: Adding an overload that precludes an existing overload and defines a different behavior

    Spowoduje to przerwanie istniejących klientów, które zostały powiązane z poprzednim przeciążeniem.This breaks existing clients that were bound to the previous overload. Na przykład jeśli klasa ma jedną wersję metody, która akceptuje UInt32 , istniejący Klient pomyślnie powiąże się z tym przeciążeniem podczas przekazywania Int32 wartości.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. Jeśli jednak zostanie dodane Przeciążenie, które akceptuje Int32 , podczas ponownej kompilacji lub użycia późnego wiązania, kompilator tworzy teraz powiązanie z nowym przeciążeniem.However, if you add an overload that accepts an Int32, when recompiling or using late-binding, the compiler now binds to the new overload. W przypadku innych wyników zachowania jest to istotna zmiana.If different behavior results, this is a breaking change.

  • Niedozwolone: Dodawanie konstruktora do klasy, która wcześniej nie miała konstruktora bez dodawania konstruktora bezparametrowegoDISALLOWED: Adding a constructor to a class that previously had no constructor without adding the parameterless constructor

  • ❌️Niedozwolone: Dodawanie elementu ReadOnly do pola❌️ DISALLOWED: Adding readonly to a field

  • Niedozwolone: zmniejszanie widoczności elementu członkowskiegoDISALLOWED: Reducing the visibility of a member

    Obejmuje to zmniejszenie widoczności chronionego elementu członkowskiego, gdy są dostępne ( public lub protected ) konstruktory, a typ nie jest zapieczętowany.This includes reducing the visibility of a protected member when there are accessible (public or protected) constructors and the type is not sealed. Jeśli tak się nie dzieje, zmniejszenie widoczności chronionego elementu członkowskiego jest dozwolone.If this is not the case, reducing the visibility of a protected member is allowed.

    Zwiększenie widoczności elementu członkowskiego jest dozwolone.Increasing the visibility of a member is allowed.

  • Niedozwolone: zmiana typu elementu członkowskiegoDISALLOWED: Changing the type of a member

    Nie można zmodyfikować wartości zwracanej przez metodę lub typ właściwości lub pola.The return value of a method or the type of a property or field cannot be modified. Na przykład sygnatura metody zwracającej wartość Object nie może zostać zmieniona w celu zwrócenia String lub odwrotnie.For example, the signature of a method that returns an Object cannot be changed to return a String, or vice versa.

  • Niedozwolone: Dodawanie pola do struktury, która wcześniej nie miała stanuDISALLOWED: Adding a field to a struct that previously had no state

    Określone reguły przypisywania umożliwiają użycie niezainicjowanych zmiennych, tak długo, jak typ zmiennej jest strukturą bezstanową.Definite assignment rules allow the use of uninitialized variables so long as the variable type is a stateless struct. Jeśli struktura jest stanowa, kod może kończyć się zainicjowanymi danymi.If the struct is made stateful, code could end up with uninitialized data. Może to być zarówno uszkodzenie źródła, jak i uszkodzenie binarne.This is both potentially a source breaking and a binary breaking change.

  • Niedozwolone: wyzwalanie istniejącego zdarzenia, gdy nigdy nie zostało wyzwoloneDISALLOWED: Firing an existing event when it was never fired before

Zmiany behawioralneBehavioral changes

ZestawyAssemblies

  • ✔️ dozwolone: Tworzenie zestawu przenośnego, gdy te same platformy są nadal obsługiwane✔️ ALLOWED: Making an assembly portable when the same platforms are still supported

  • Niedozwolone: zmiana nazwy zestawuDISALLOWED: Changing the name of an assembly

  • Niedozwolone: Zmiana klucza publicznego zestawuDISALLOWED: Changing the public key of an assembly

Właściwości, pola, parametry i wartości zwracaneProperties, fields, parameters, and return values

  • ✔️ dozwolone: zmiana wartości właściwości, pola, wartości zwracanej lub parametru out na bardziej pochodny typ✔️ ALLOWED: Changing the value of a property, field, return value, or out parameter to a more derived type

    Na przykład Metoda zwracająca typ Object może zwracać String wystąpienie.For example, a method that returns a type of Object can return a String instance. Nie można jednak zmienić sygnatury metody.)(However, the method signature cannot change.)

  • ✔️ dozwolone: zwiększenie zakresu akceptowanych wartości właściwości lub parametru, jeśli element członkowski nie jest wirtualny✔️ ALLOWED: Increasing the range of accepted values for a property or parameter if the member is not virtual

    W czasie, gdy zakres wartości, które mogą być przesyłane do metody lub są zwracane przez element członkowski, można rozwinąć, parametr lub typ elementu członkowskiego nie mogą.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. Na przykład, podczas gdy wartości przekazaną do metody można rozszerzyć od 0-124 do 0-255, typ parametru nie może zmienić z Byte na 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.

  • Niedozwolone: zwiększenie zakresu akceptowanych wartości właściwości lub parametru, jeśli element członkowski jest wirtualnyDISALLOWED: Increasing the range of accepted values for a property or parameter if the member is virtual

    Ta zmiana powoduje przerwanie istniejących przesłoniętych elementów członkowskich, które nie będą działać poprawnie dla rozszerzonego zakresu wartości.This change breaks existing overridden members, which will not function correctly for the extended range of values.

  • Niedozwolone: zmniejszanie zakresu akceptowanych wartości dla właściwości lub parametruDISALLOWED: Decreasing the range of accepted values for a property or parameter

  • Niedozwolone: zwiększenie zakresu zwracanych wartości dla właściwości, pola, wartości zwracanej lub parametru outDISALLOWED: Increasing the range of returned values for a property, field, return value, or out parameter

  • Niedozwolone: zmiana zwracanych wartości właściwości, pola, wartości zwracanej metody lub parametru outDISALLOWED: Changing the returned values for a property, field, method return value, or out parameter

  • Niedozwolone: zmiana wartości domyślnej właściwości, pola lub parametruDISALLOWED: Changing the default value of a property, field, or parameter

  • Niedozwolone: zmiana dokładności liczbowej wartości zwracanejDISALLOWED: Changing the precision of a numeric return value

  • Wymaga orzeczenia: zmiana analizy danych wejściowych i zgłaszanie nowych wyjątków (nawet jeśli nie określono zachowania analizy w dokumentacjiREQUIRES JUDGMENT: A change in the parsing of input and throwing new exceptions (even if parsing behavior is not specified in the documentation

WyjątkiExceptions

  • ✔️ dozwolone: Zgłaszanie bardziej pochodnego wyjątku niż istniejący wyjątek✔️ ALLOWED: Throwing a more derived exception than an existing exception

    Ponieważ nowy wyjątek jest podklasą istniejącego wyjątku, poprzedni kod obsługi wyjątków nadal obsłużył wyjątek.Because the new exception is a subclass of an existing exception, previous exception handling code continues to handle the exception. Na przykład w .NET Framework 4, metody tworzenia i pobierania kultur zaczęły zgłosić zamiast elementu CultureNotFoundException ArgumentException , jeśli nie można znaleźć kultury.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. Ponieważ CultureNotFoundException pochodzi od ArgumentException , jest to akceptowalna zmiana.Because CultureNotFoundException derives from ArgumentException, this is an acceptable change.

  • ✔️ dozwolone: Zgłaszanie bardziej szczegółowego wyjątku NotSupportedException niż NotImplementedException , NullReferenceException ,✔️ ALLOWED: Throwing a more specific exception than NotSupportedException, NotImplementedException, NullReferenceException

  • ✔️ dozwolone: Zgłaszanie wyjątku, który jest uznawany za niemożliwy do odzyskania✔️ ALLOWED: Throwing an exception that is considered unrecoverable

    Niemożliwy do odzyskania wyjątki nie powinny być przechwytywane, ale powinny być obsługiwane przez obsługę catch-all o wysokim poziomie.Unrecoverable exceptions should not be caught but instead should be handled by a high-level catch-all handler. W związku z tym użytkownicy nie powinny mieć kodu, który przechwytuje te jawne wyjątki.Therefore, users are not expected to have code that catches these explicit exceptions. Nieodwracalne wyjątki są następujące:The unrecoverable exceptions are:

  • ✔️ dozwolone: Zgłaszanie nowego wyjątku w nowej ścieżce kodu✔️ ALLOWED: Throwing a new exception in a new code path

    Wyjątek musi dotyczyć tylko nowej ścieżki kodu, która jest wykonywana z nowymi wartościami parametrów lub stanem, ale nie może zostać wykonana przez istniejący kod, który jest przeznaczony dla poprzedniej wersji.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.

  • ✔️ dozwolone: usuwanie wyjątku, aby umożliwić bardziej niezawodne zachowanie lub nowe scenariusze✔️ ALLOWED: Removing an exception to enable more robust behavior or new scenarios

    Na przykład metoda, Divide która wcześniej obsługiwała tylko wartości dodatnie i zgłosiła ArgumentOutOfRangeException w przeciwnym razie, może zostać zmieniona, aby obsługiwała wartości ujemne i dodatnie bez zgłaszania wyjątku.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.

  • ✔️ dozwolone: Zmiana tekstu komunikatu o błędzie✔️ ALLOWED: Changing the text of an error message

    Deweloperzy nie powinni polegać na tekście komunikatów o błędach, które również zmieniają się w zależności od kultury użytkownika.Developers should not rely on the text of error messages, which also change based on the user's culture.

  • Niedozwolone: Zgłaszanie wyjątku w innym przypadku niewymienionym powyżejDISALLOWED: Throwing an exception in any other case not listed above

  • Niedozwolone: usuwanie wyjątku w innym przypadku niewymienionym powyżejDISALLOWED: Removing an exception in any other case not listed above

AtrybutyAttributes

  • ✔️ dozwolone: zmiana wartości atrybutu, który nie jest zauważalny✔️ ALLOWED: Changing the value of an attribute that is not observable

  • Niedozwolone: zmiana wartości atrybutu, który jest zauważalnyDISALLOWED: Changing the value of an attribute that is observable

  • Wymaga orzeczenia: usuwanie atrybutuREQUIRES JUDGMENT: Removing an attribute

    W większości przypadków usunięcie atrybutu (na przykład NonSerializedAttribute ) jest istotną zmianą.In most cases, removing an attribute (such as NonSerializedAttribute) is a breaking change.

Obsługa platformPlatform support

  • ✔️ dozwolone: obsługa operacji na platformie, która była wcześniej nieobsługiwana✔️ ALLOWED: Supporting an operation on a platform that was previously not supported

  • Niedozwolone: nie obsługujące lub teraz wymagającej określonego dodatku Service Pack dla operacji, która była wcześniej obsługiwana na platformieDISALLOWED: Not supporting or now requiring a specific service pack for an operation that was previously supported on a platform

Wewnętrzne zmiany implementacjiInternal implementation changes

  • Wymaga orzeczenia: zmiana obszaru powierzchni typu wewnętrznegoREQUIRES JUDGMENT: Changing the surface area of an internal type

    Takie zmiany są zwykle dozwolone, chociaż przerywają odbicie prywatne.Such changes are generally allowed, although they break private reflection. W niektórych przypadkach, gdy popularne biblioteki innych firm lub duża liczba deweloperów zależą od wewnętrznych interfejsów API, takie zmiany mogą nie być dozwolone.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.

  • Wymaga orzeczenia: zmiana wewnętrznej implementacji elementu członkowskiegoREQUIRES JUDGMENT: Changing the internal implementation of a member

    Te zmiany są ogólnie dozwolone, chociaż przerywają odbicie prywatne.These changes are generally allowed, although they break private reflection. W niektórych przypadkach, gdzie kod klienta często zależy od odbicia prywatnego lub gdzie zmiana wprowadza niezamierzone efekty uboczne, te zmiany mogą być niedozwolone.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.

  • ✔️ dozwolone: poprawa wydajności operacji✔️ ALLOWED: Improving the performance of an operation

    Możliwość modyfikowania wydajności operacji jest istotna, ale takie zmiany mogą spowodować przerwanie kodu, który opiera się na bieżącej szybkości operacji.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. Jest to szczególnie prawdziwe w przypadku kodu, który zależy od chronometrażu operacji asynchronicznych.This is particularly true of code that depends on the timing of asynchronous operations. Zmiana wydajności nie powinna mieć wpływu na inne zachowanie interfejsu API. w przeciwnym razie zmiana zostanie przerwana.The performance change should have no effect on other behavior of the API in question; otherwise, the change will be breaking.

  • ✔️ dozwolone: pośrednio (i często niekorzystnie) zmiana wydajności operacji✔️ ALLOWED: Indirectly (and often adversely) changing the performance of an operation

    Jeśli dana zmiana nie zostanie skategoryzowana z innego powodu, jest to dopuszczalne.If the change in question is not categorized as breaking for some other reason, this is acceptable. Często należy podjąć działania, które mogą obejmować dodatkowe operacje lub dodając nowe funkcje.Often, actions need to be taken that may include extra operations or that add new functionality. Prawie zawsze ma to wpływ na wydajność, ale może być konieczne, aby interfejs API działał w oczekiwany sposób.This will almost always affect performance but may be essential to make the API in question function as expected.

  • Niedozwolone: zmiana synchronicznego interfejsu API na asynchroniczny (i odwrotnie)DISALLOWED: Changing a synchronous API to asynchronous (and vice versa)

Zmiany koduCode changes

  • ✔️ dozwolone: Dodawanie parametrów do parametru✔️ ALLOWED: Adding params to a parameter

  • Niedozwolone: zmiana struktury na klasę i odwrotnieDISALLOWED: Changing a struct to a class and vice versa

  • Niedozwolone: Dodawanie słowa kluczowego Checked do bloku koduDISALLOWED: Adding the checked keyword to a code block

    Ta zmiana może spowodować, że kod, który został wcześniej wykonany w celu wygenerowania OverflowException i jest nieakceptowalny.This change may cause code that previously executed to throw an OverflowException and is unacceptable.

  • Niedozwolone: Usuwanie parametrów z parametruDISALLOWED: Removing params from a parameter

  • Niedozwolone: zmiana kolejności, w której są uruchamiane zdarzeniaDISALLOWED: Changing the order in which events are fired

    Deweloperzy mogą w rozsądny sposób oczekiwać, że wyzwalają zdarzenia w tej samej kolejności, a kod dewelopera często zależy od kolejności, w jakiej są uruchamiane zdarzenia.Developers can reasonably expect events to fire in the same order, and developer code frequently depends on the order in which events are fired.

  • Niedozwolone: usuwanie podniesienia poziomu zdarzenia do danej akcjiDISALLOWED: Removing the raising of an event on a given action

  • Niedozwolone: zmiana liczby wywoływanych zdarzeńDISALLOWED: Changing the number of times given events are called

  • Niedozwolone: Dodawanie FlagsAttribute do typu wyliczeniaDISALLOWED: Adding the FlagsAttribute to an enumeration type