Reorganize breaking changes TOC (#33111)
This commit is contained in:
Genevieve Warren
GitHub
Родитель
db612372a2
Коммит
5d85fca444
|
|
@ -82,6 +82,11 @@
|
|||
"source_path_from_root": "/docs/core/compatibility/framework-core.md",
|
||||
"redirect_url": "/dotnet/core/compatibility/fx-core"
|
||||
},
|
||||
{
|
||||
"source_path_from_root": "/docs/core/compatibility/index.md",
|
||||
"redirect_url": "/dotnet/core/compatibility/library-change-rules",
|
||||
"redirect_document_id": true
|
||||
},
|
||||
{
|
||||
"source_path_from_root": "/docs/core/compatibility/interop.md",
|
||||
"redirect_url": "/dotnet/core/compatibility/interop/5.0/built-in-support-for-winrt-removed"
|
||||
|
|
|
|||
|
|
@ -98,7 +98,7 @@ items:
|
|||
items:
|
||||
- name: Breaking changes
|
||||
tocHref: /dotnet/core/compatibility/
|
||||
topicHref: /dotnet/core/compatibility/index
|
||||
topicHref: /dotnet/core/compatibility/breaking-changes
|
||||
- name: .NET Framework
|
||||
tocHref: /dotnet/framework/
|
||||
topicHref: /dotnet/framework/index
|
||||
|
|
|
|||
|
|
@ -1,13 +1,15 @@
|
|||
---
|
||||
title: Breaking changes reference overview
|
||||
title: .NET breaking changes reference
|
||||
description: Learn how to navigate the .NET breaking changes reference.
|
||||
ms.date: 11/16/2020
|
||||
ms.date: 12/22/2022
|
||||
ms.topic: conceptual
|
||||
---
|
||||
# Breaking changes reference overview
|
||||
# Breaking changes in .NET
|
||||
|
||||
Use this reference section to find breaking changes that might apply to you if you're upgrading your app to a newer version of .NET. You can navigate the table of contents either by .NET version or by technology area.
|
||||
|
||||
If you're looking for breaking changes from .NET Framework to .NET (Core), see [Breaking changes for migration from .NET Framework to .NET Core](fx-core.md).
|
||||
|
||||
## GitHub issues and announcements
|
||||
|
||||
You can also view individual issues that detail the breaking changes introduced in .NET in the following GitHub repositories:
|
||||
|
|
@ -19,3 +21,4 @@ You can also view individual issues that detail the breaking changes introduced
|
|||
## See also
|
||||
|
||||
- [Migrate from .NET Framework to .NET Core](../porting/index.md)
|
||||
- [Breaking changes for migration from .NET Framework to .NET Core](fx-core.md)
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ ms.topic: conceptual
|
|||
---
|
||||
# How code changes can affect compatibility
|
||||
|
||||
*Compatibility* refers to the ability to compile or execute code on a version of a .NET implementation other than the one with which the code was originally developed. A [particular change](index.md) can affect compatibility in six different ways:
|
||||
*Compatibility* refers to the ability to compile or execute code on a version of a .NET implementation other than the one with which the code was originally developed. A particular change can affect compatibility in six different ways:
|
||||
|
||||
- [Behavioral change](#behavioral-change)
|
||||
- [Binary compatibility](#binary-compatibility)
|
||||
|
|
@ -46,7 +46,3 @@ Forward compatibility refers to the ability of an existing consumer of an API to
|
|||
Maintaining forward compatibility virtually precludes any changes or additions from version to version, since those changes prevent a consumer that targets a later version from running under an earlier version. Developers expect that a consumer that relies on a newer API may not function correctly against the older API.
|
||||
|
||||
Maintaining forward compatibility is not a goal of .NET Core.
|
||||
|
||||
## See also
|
||||
|
||||
- [Evaluate breaking changes in .NET Core](index.md)
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
title: Types of breaking changes
|
||||
title: .NET API changes that affect compatibility
|
||||
description: Learn how .NET attempts to maintain compatibility for developers across .NET versions, and what kind of change is considered a breaking change.
|
||||
ms.date: 05/12/2021
|
||||
ms.topic: conceptual
|
||||
---
|
||||
# Changes that affect compatibility
|
||||
# Change rules for compatibility
|
||||
|
||||
Throughout its history, .NET has attempted to maintain a high level of compatibility from version to version and across implementations of .NET. 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:
|
||||
|
||||
|
|
@ -14,14 +14,14 @@ Throughout its history, .NET has attempted to maintain a high level of compatibi
|
|||
|
||||
Along with compatibility across .NET implementations, developers expect a high level of compatibility across versions of a given implementation of .NET. In particular, code written for an earlier version of .NET Core should run seamlessly on .NET 5 or a later version. 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.
|
||||
|
||||
This article outlines changes that affect compatibility and the way in which the .NET team evaluates each type of change. 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](https://github.com/dotnet/runtime).
|
||||
This article outlines changes that affect compatibility and the way in which the .NET team evaluates each type of change. 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.
|
||||
|
||||
The following sections describe the categories of changes made to .NET APIs and their impact on application compatibility. Changes are either allowed ✔️, disallowed ❌, or require judgment and an evaluation of how predictable, obvious, and consistent the previous behavior was ❓.
|
||||
The following sections describe the categories of changes made to .NET APIs and their impact on application compatibility. Changes are either allowed (✔️), disallowed (❌), or require judgment and an evaluation of how predictable, obvious, and consistent the previous behavior was (❓).
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> - 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.
|
||||
> - For information about the compatibility categories, for example, forward and backwards compatibility, see [Compatibility](categories.md).
|
||||
> - For information about the compatibility categories, for example, forward and backwards compatibility, see [How code changes can affect compatibility](categories.md).
|
||||
|
||||
## Modifications to the public contract
|
||||
|
||||
|
|
@ -331,4 +331,6 @@ Changes in this category modify the public surface area of a type. Most of the c
|
|||
|
||||
## See also
|
||||
|
||||
- [Breaking changes in .NET](../compatibility/breaking-changes.md)
|
||||
- [Library design guidelines - breaking changes](../../standard/library-guidance/breaking-changes.md)
|
||||
- [.NET breaking change rules](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md)
|
||||
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
|
|
@ -3,7 +3,7 @@ title: Breaking changes can affect porting your app
|
|||
description: Breaking changes can occur when porting your code from .NET framework to .NET and between versions of .NET. This article describes categories of breaking changes, ways a change can affect compatibility and how to find breaking changes.
|
||||
author: StephenBonikowsky
|
||||
ms.author: stebon
|
||||
ms.date: 06/14/2021
|
||||
ms.date: 12/22/2022
|
||||
---
|
||||
# Breaking changes may occur when porting code
|
||||
|
||||
|
|
@ -13,23 +13,23 @@ Microsoft strives to maintain a high level of compatibility between .NET version
|
|||
|
||||
Before upgrading major versions, check the breaking changes documentation for changes that might affect you.
|
||||
|
||||
## Categories of breaking changes
|
||||
## Changes that affect compatibility
|
||||
|
||||
There are several types of breaking changes...
|
||||
There are several types of changes that library authors can make that affect compatibility, including:
|
||||
|
||||
- modifications to the public contract
|
||||
- behavioral changes
|
||||
- Modifications to the public contract
|
||||
- Behavioral changes
|
||||
- Platform support
|
||||
- Internal implementation changes
|
||||
- Code changes
|
||||
|
||||
For more information about what is allowed or disallowed, see [Changes that affect compatibility](../compatibility/index.md)
|
||||
For more information about what kind of changes are allowed or disallowed, see [Change rules for compatibility](../compatibility/library-change-rules.md).
|
||||
|
||||
## Types of compatibility
|
||||
|
||||
Compatibility refers to the ability to compile or run code on a .NET implementation other than the one with which the code was originally developed.
|
||||
|
||||
There are six different ways a change can affect compatibility...
|
||||
There are six different ways a change can affect compatibility:
|
||||
|
||||
- Behavioral changes
|
||||
- Binary compatibility
|
||||
|
|
@ -38,10 +38,8 @@ There are six different ways a change can affect compatibility...
|
|||
- Backwards compatibility
|
||||
- Forward compatibility
|
||||
|
||||
For more information, see [How code changes can affect compatibility](../compatibility/categories.md)
|
||||
For more information, see [How code changes can affect compatibility](../compatibility/categories.md).
|
||||
|
||||
## Find breaking changes
|
||||
|
||||
Changes that affect compatibility are documented and should be reviewed before porting from .NET Framework to .NET or when upgrading to a newer version of .NET.
|
||||
|
||||
For more information, see [Breaking changes reference overview](../compatibility/breaking-changes.md)
|
||||
Changes that affect compatibility are documented. Review these changes before you port your code from .NET Framework to .NET or upgrade it to a newer version of .NET. For a list of these breaking changes, see [Breaking changes for migration from .NET Framework to .NET Core](../compatibility/fx-core.md).
|
||||
|
|
|
|||
|
|
@ -1797,6 +1797,8 @@ items:
|
|||
href: ../core/versions/index.md
|
||||
- name: .NET version selection
|
||||
href: ../core/versions/selection.md
|
||||
- name: Compatibility
|
||||
href: ../core/compatibility/breaking-changes.md
|
||||
- name: Configure .NET Runtime
|
||||
items:
|
||||
- name: Settings
|
||||
|
|
@ -3221,9 +3223,17 @@ items:
|
|||
- name: Telemetry
|
||||
href: ../core/porting/upgrade-assistant-telemetry.md
|
||||
- name: Breaking changes
|
||||
displayName: app compatibility
|
||||
href: ../core/porting/breaking-changes.md
|
||||
- name: Pre-Migration
|
||||
items:
|
||||
- name: Overview
|
||||
displayName: app compatibility
|
||||
href: ../core/porting/breaking-changes.md
|
||||
- name: Breaking changes
|
||||
href: ../core/compatibility/fx-core.md
|
||||
- name: Unavailable technologies
|
||||
href: ../core/porting/net-framework-tech-unavailable.md
|
||||
- name: APIs that always throw
|
||||
href: ../core/compatibility/unsupported-apis.md
|
||||
- name: Pre-migration
|
||||
items:
|
||||
- name: Assess the portability of your project
|
||||
items:
|
||||
|
|
@ -3245,11 +3255,11 @@ items:
|
|||
href: ../core/porting/porting-approaches.md
|
||||
- name: Project structure
|
||||
href: ../core/porting/project-structure.md
|
||||
- name: Application Porting Guides
|
||||
- name: Application porting guides
|
||||
items:
|
||||
- name: Windows Forms
|
||||
href: /dotnet/desktop/winforms/migration/?view=netdesktop-6.0&preserve-view=false
|
||||
- name: Windows Presentation Foundation
|
||||
href: /dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-6.0&preserve-view=false
|
||||
- name: Port C++/CLI projects
|
||||
- name: C++/CLI projects
|
||||
href: ../core/porting/cpp-cli.md
|
||||
|
|
|
|||
|
|
@ -133,7 +133,7 @@ conceptualContent:
|
|||
- url: core/docker/build-container.md
|
||||
itemType: tutorial
|
||||
text: Containerize .NET apps with Docker
|
||||
- url: core/compatibility/index.md
|
||||
- url: core/compatibility/breaking-changes.md
|
||||
itemType: concept
|
||||
text: .NET breaking changes
|
||||
- url: /dotnet/desktop/wpf/get-started/create-app-visual-studio?view=netdesktop-6.0&preserve-view=true
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ For example, ASP.NET Core MVC has the concept of a [compatibility version](/aspn
|
|||
|
||||
✔️ CONSIDER leaving new features off by default, if they affect existing users, and let developers opt in to the feature with a setting.
|
||||
|
||||
For more information about behavior breaking changes in .NET APIs, see [.NET behavioral changes compatibility](../../core/compatibility/index.md#behavioral-changes).
|
||||
For more information about behavior breaking changes in .NET APIs, see [.NET behavioral changes compatibility](../../core/compatibility/library-change-rules.md#behavioral-changes).
|
||||
|
||||
### Binary breaking change
|
||||
|
||||
|
|
@ -92,13 +92,12 @@ public class Document
|
|||
|
||||
> Removing APIs is a binary breaking change. Considering keeping obsolete types and methods if maintaining them is low cost and doesn't add lot of technical debt to your library. Not removing types and methods can help avoid the worst-case scenarios mentioned above.
|
||||
|
||||
For more information about what .NET API changes break binary compatibility, see [.NET public contract compatibility](../../core/compatibility/index.md#modifications-to-the-public-contract).
|
||||
For more information about what .NET API changes break binary compatibility, see [.NET public contract compatibility](../../core/compatibility/library-change-rules.md#modifications-to-the-public-contract).
|
||||
|
||||
## See also
|
||||
|
||||
- [Version and update considerations for C# developers](../../csharp/whats-new/version-update-considerations.md)
|
||||
- [A definitive guide to API-breaking changes in .NET](https://stackoverflow.com/questions/1456785/a-definitive-guide-to-api-breaking-changes-in-net)
|
||||
- [.NET breaking change rules](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md)
|
||||
- [Change rules for compatibility](../../core/compatibility/library-change-rules.md)
|
||||
|
||||
>[!div class="step-by-step"]
|
||||
>[Previous](versioning.md)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче