diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 6ebe59ebce701..4f3ae206e79aa 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -74,6 +74,21 @@ "source_path_from_root": "/docs/core/compatibility/core-libraries/7.0/filesystemeventargs-fullpath.md", "redirect_url": "/dotnet/core/compatibility/7.0" }, + { + "source_path_from_root": "/docs/core/compatibility/core-libraries/5.0/binaryformatter-serialization-obsolete.md", + "redirect_url": "/dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/core/compatibility/core-libraries/7.0/binaryformatter-apis-produce-errors.md", + "redirect_url": "/dotnet/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/core/compatibility/core-libraries/7.0/serializationformat-binary.md", + "redirect_url": "/dotnet/core/compatibility/serialization/7.0/serializationformat-binary", + "redirect_document_id": true + }, { "source_path_from_root": "/docs/core/compatibility/extensions/6.0/bind-single-elements-to-array.md", "redirect_url": "/dotnet/core/compatibility/6.0" diff --git a/docs/core/compatibility/5.0.md b/docs/core/compatibility/5.0.md index bbd17dcfe560a..3f2540f3ceee4 100644 --- a/docs/core/compatibility/5.0.md +++ b/docs/core/compatibility/5.0.md @@ -15,7 +15,7 @@ If you're migrating an app to .NET 5, the breaking changes listed here might aff | - | - | - | | [ASP.NET Core apps deserialize quoted numbers](serialization/5.0/jsonserializer-allows-reading-numbers-as-strings.md) | ✔️ | ❌ | | [AzureAD.UI and AzureADB2C.UI APIs obsolete](aspnet-core/5.0/authentication-aad-packages-obsolete.md) | ✔️ | ❌ | -| [BinaryFormatter serialization methods are obsolete](core-libraries/5.0/binaryformatter-serialization-obsolete.md) | ✔️ | ❌ | +| [BinaryFormatter serialization methods are obsolete](serialization/5.0/binaryformatter-serialization-obsolete.md) | ✔️ | ❌ | | [Resource in endpoint routing is HttpContext](aspnet-core/5.0/authorization-resource-in-endpoint-routing.md) | ✔️ | ❌ | | [Microsoft-prefixed Azure integration packages removed](aspnet-core/5.0/azure-integration-packages-removed.md) | ❌ | ✔️ | | [Blazor: Route precedence logic changed in Blazor apps](aspnet-core/5.0/blazor-routing-logic-changed.md) | ✔️ | ❌ | @@ -68,7 +68,7 @@ If you're migrating an app to .NET 5, the breaking changes listed here might aff | Title | Binary compatible | Source compatible | | - | - | - | | [Assembly-related API changes for single-file publishing](core-libraries/5.0/assembly-api-behavior-changes-for-single-file-publish.md) | ❌ | ✔️ | -| [BinaryFormatter serialization methods are obsolete](core-libraries/5.0/binaryformatter-serialization-obsolete.md) | ✔️ | ❌ | +| [BinaryFormatter serialization methods are obsolete](serialization/5.0/binaryformatter-serialization-obsolete.md) | ✔️ | ❌ | | [Code access security APIs are obsolete](core-libraries/5.0/code-access-security-apis-obsolete.md) | ✔️ | ❌ | | [CreateCounterSetInstance throws InvalidOperationException](core-libraries/5.0/createcountersetinstance-throws-invalidoperation.md) | ✔️ | ❌ | | [Default ActivityIdFormat is W3C](core-libraries/5.0/default-activityidformat-changed.md) | ❌ | ✔️ | diff --git a/docs/core/compatibility/7.0.md b/docs/core/compatibility/7.0.md index 09e14ec4f2620..2c8db03859d41 100644 --- a/docs/core/compatibility/7.0.md +++ b/docs/core/compatibility/7.0.md @@ -37,7 +37,7 @@ If you're migrating an app to .NET 7, the breaking changes listed here might aff | - | :-: | :-: | - | | [API obsoletions with default diagnostic ID](core-libraries/7.0/obsolete-apis-with-default-diagnostic.md) | ✔️ | ❌ | Preview 3 | | [API obsoletions with non-default diagnostic IDs](core-libraries/7.0/obsolete-apis-with-custom-diagnostics.md) | ✔️ | ❌ | Preview 1 | -| [BinaryFormatter serialization APIs produce compiler errors](core-libraries/7.0/binaryformatter-apis-produce-errors.md) | ✔️ | ❌ | RC 1 | +| [BinaryFormatter serialization APIs produce compiler errors](serialization/7.0/binaryformatter-apis-produce-errors.md) | ✔️ | ❌ | RC 1 | | [BrotliStream no longer allows undefined CompressionLevel values](core-libraries/7.0/brotlistream-ctor.md) | ❌ | ✔️ | | | [C++/CLI projects in Visual Studio](core-libraries/7.0/cpluspluscli-compiler-version.md) | ✔️ | ❌ | Preview 3 | | [Changes to reflection invoke API exceptions](core-libraries/7.0/reflection-invoke-exceptions.md) | ❌ | ✔️ | Preview 4 | @@ -48,7 +48,7 @@ If you're migrating an app to .NET 7, the breaking changes listed here might aff | [Legacy FileStream strategy removed](core-libraries/7.0/filestream-compat-switch.md) | ❌ | ✔️ | Preview 1 | | [Library support for older frameworks](core-libraries/7.0/old-framework-support.md) | ❌ | ❌ | Preview 1 | | [Maximum precision for numeric format strings](core-libraries/7.0/max-precision-numeric-format-strings.md) | ❌ | ✔️ | RC 1 | -| [SerializationFormat.Binary is obsolete](core-libraries/7.0/serializationformat-binary.md) | ❌ | ❌ | Preview 2 | +| [SerializationFormat.Binary is obsolete](serialization/7.0/serializationformat-binary.md) | ❌ | ❌ | Preview 2 | | [System.Runtime.CompilerServices.Unsafe NuGet package](core-libraries/7.0/unsafe-package.md) | ✔️ | ✔️ | Preview 3 | | [Time fields on symbolic links](core-libraries/7.0/symbolic-link-timestamps.md) | ❌ | ✔️ | Preview 1 | | [Tracking linked cache entries](core-libraries/7.0/memorycache-tracking.md) | ❌ | ✔️ | Preview 1 | diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index 27778379868f7..25053c1fdb2dd 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -2,7 +2,7 @@ title: Breaking changes in .NET 8 titleSuffix: "" description: Navigate to the breaking changes in .NET 8. -ms.date: 01/24/2023 +ms.date: 05/05/2023 no-loc: [Blazor, Razor, Kestrel] --- # Breaking changes in .NET 8 @@ -21,6 +21,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff | ----------------------------------------------------------------------------------------------------- | ------------------- | ---------- | | [Activity operation name when null](core-libraries/8.0/activity-operation-name.md) | Behavioral change | Preview 1 | | [AnonymousPipeServerStream.Dispose behavior](core-libraries/8.0/anonymouspipeserverstream-dispose.md) | Behavioral change | Preview 1 | +| [API obsoletions with custom diagnostic IDs](core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md) | Source incompatible | Preview 1, 4 | | [Backslash mapping in Unix file paths](core-libraries/8.0/file-path-backslash.md) | Behavioral change | Preview 1 | | [FileStream writes when pipe is closed](core-libraries/8.0/filestream-disposed-pipe.md) | Behavioral change | Preview 1 | | [GetFolderPath behavior on Unix](core-libraries/8.0/getfolderpath-unix.md) | Behavioral change | Preview 1 | @@ -64,6 +65,12 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff | ['dotnet pack' uses Release configuration](sdk/8.0/dotnet-pack-config.md) | Behavioral change/Source incompatible | Preview 1 | | ['dotnet publish' uses Release configuration](sdk/8.0/dotnet-publish-config.md) | Behavioral change/Source incompatible | Preview 1 | +## Serialization + +| Title | Type of change | Introduced | +| ------------------------------------------------------------------------------- | ------------------------------------------------ | ---------- | +| [BinaryFormatter disabled for most projects](serialization/8.0/binaryformatter-disabled.md) | Behavioral change | Preview 4 | + ## Windows Forms | Title | Type of change | Introduced | diff --git a/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md b/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md new file mode 100644 index 0000000000000..f3502be418b65 --- /dev/null +++ b/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md @@ -0,0 +1,539 @@ +--- +title: "Breaking change: .NET 8 obsoletions with custom IDs" +titleSuffix: "" +description: Learn about the .NET 8 breaking change in core .NET libraries where some APIs have been marked as obsolete with a custom diagnostic ID. +ms.date: 05/05/2023 +--- +# API obsoletions with non-default diagnostic IDs (.NET 8) + +Some APIs have been marked as obsolete, starting in .NET 8. This breaking change is specific to APIs that have been marked as obsolete *with a custom diagnostic ID*. Suppressing the default obsoletion diagnostic ID, which is [CS0618](../../../../csharp/language-reference/compiler-messages/cs0618.md) for the C# compiler, does not suppress the warnings that the compiler generates when these APIs are used. + +## Change description + +In previous .NET versions, these APIs can be used without any build warning. In .NET 8 and later versions, use of these APIs produces a compile-time warning or error with a custom diagnostic ID. The use of custom diagnostic IDs allows you to suppress the obsoletion warnings individually instead of blanket-suppressing all obsoletion warnings. + +The following table lists the custom diagnostic IDs and their corresponding warning messages for obsoleted APIs. + +| Diagnostic ID | Description | Severity | +| - | - | +| [SYSLIB0048](../../../../fundamentals/syslib-diagnostics/syslib0048.md) | and are obsolete. Use and instead. | Warning | +| [SYSLIB0050](../../../../fundamentals/syslib-diagnostics/syslib0050.md) | Formatter-based serialization is obsolete and should not be used. | Warning | +| [SYSLIB0051](../../../../fundamentals/syslib-diagnostics/syslib0051.md) | APIs that support obsolete formatter-based serialization are obsolete. They should not be called or extended by application code. | Warning | + +## Version introduced + +.NET 8 + +## Type of breaking change + +These obsoletions can affect [source compatibility](../../categories.md#source-compatibility). + +## Recommended action + +- Follow the specific guidance provided for the each diagnostic ID using the URL link provided on the warning. + +- Warnings or errors for these obsoletions can't be suppressed using the standard diagnostic ID for obsolete types or members; use the custom `SYSLIBxxxx` diagnostic ID value instead. + +## Affected APIs + +### SYSLIB0048 + +- +- +- +- + +### SYSLIB0050 + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +### SYSLIB0051 + +The `SYSLIB0051` API obsoletions are organized here by namespace. + +#### Microsoft.CSharp.RuntimeBinder namespace + +- +- + +#### Microsoft.VisualBasic.FileIO namespace + +- +- + +#### System namespace + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +#### System.Collections namespace + +- + +#### System.Collections.Generic namespace + +- +- +- +- +- +- +- +- + +#### System.Collections.Specialized namespace + +- +- +- +- +- + +#### System.ComponentModel namespace + +- +- +- +- +- +- +- +- + +#### System.ComponentModel.Composition namespace + +- +- + +#### System.ComponentModel.Composition.Primitives namespace + +- +- + +#### System.ComponentModel.DataAnnotations namespace + +- + +#### System.ComponentModel.Design namespace + +- + +#### System.Configuration namespace + +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +#### System.Data namespace + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +#### System.Data.Common namespace + +- + +#### System.Data.Odbc namespace + +- + +#### System.Data.OleDb namespace + +- + +#### System.Data.SqlTypes namespace + +- + +#### System.Diagnostics.Eventing.Reader namespace + +- +- +- +- +- +- + +#### System.Diagnostics.Tracing namespace + +- + +#### System.DirectoryServices namespace + +- +- + +#### System.DirectoryServices.AccountManagement namespace + +- +- +- +- +- +- +- +- +- + +#### System.DirectoryServices.ActiveDirectory namespace + +- +- +- +- +- +- +- +- +- +- +- + +#### System.DirectoryServices.Protocols namespace + +- +- +- +- +- +- +- + +#### System.Formats.Asn1 namespace + +- + +#### System.Formats.Cbor namespace + +- + +#### System.Globalization namespace + +- +- + +#### System.IO namespace + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +#### System.Management namespace + +- +- +- +- +- + +#### System.Media namespace + +- + +#### System.Net namespace + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +#### System.Net.Mail namespace + +- +- +- +- +- +- + +#### System.Net.NetworkInformation namespace + +- +- + +#### System.Net.Sockets namespace + +- + +#### System.Reflection namespace + +- +- +- +- +- +- +- +- +- + +#### System.Reflection.Metadata namespace + +- + +#### System.Resources namespace + +- +- + +#### System.Runtime.CompilerServices namespace + +- +- + +#### System.Runtime.InteropServices namespace + +- +- + +#### System.Runtime.Serialization namespace + +- + +#### System.Security namespace + +- +- +- +- + +#### System.Security.AccessControl namespace + +- + +#### System.Security.Authentication namespace + +- +- + +#### System.Security.Claims namespace + +- +- +- + +#### System.Security.Cryptography namespace + +- +- +- +- + +#### System.Security.Policy namespace + +- +- + +#### System.Security.Principal namespace + +- +- + +#### System.Text.Json namespace + +- +- + +#### System.Text.RegularExpressions namespace + +- +- + +#### System.Threading namespace + +- +- +- +- +- +- +- +- +- +- + +#### System.Threading.Channels namespace + +- + +#### System.Threading.Tasks namespace + +- +- + +#### System.Transactions namespace + +- +- +- +- +- + +#### System.Xml namespace + +- +- + +#### System.Xml.Schema namespace + +- +- +- +- +- +- + +#### System.Xml.XPath namespace + +- +- + +#### System.Xml.Xsl namespace + +- +- +- +- + +## See also + +- [API obsoletions with non-default diagnostic IDs (.NET 7)](../7.0/obsolete-apis-with-custom-diagnostics.md) +- [API obsoletions with non-default diagnostic IDs (.NET 6)](../6.0/obsolete-apis-with-custom-diagnostics.md) +- [API obsoletions with non-default diagnostic IDs (.NET 5)](../5.0/obsolete-apis-with-custom-diagnostics.md) +- [Obsolete features in .NET 5+](../../../../fundamentals/syslib-diagnostics/obsoletions-overview.md) diff --git a/docs/core/compatibility/core-libraries/5.0/binaryformatter-serialization-obsolete.md b/docs/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete.md similarity index 98% rename from docs/core/compatibility/core-libraries/5.0/binaryformatter-serialization-obsolete.md rename to docs/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete.md index b7d62e7fd4475..facf9d8cdd83d 100644 --- a/docs/core/compatibility/core-libraries/5.0/binaryformatter-serialization-obsolete.md +++ b/docs/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete.md @@ -87,3 +87,4 @@ For more information about recommended actions, see [Resolving BinaryFormatter o - [SerializationFormat.Binary is obsolete (.NET 7)](../7.0/serializationformat-binary.md) - [BinaryFormatter serialization APIs produce compiler errors (.NET 7)](../7.0/binaryformatter-apis-produce-errors.md) +- [BinaryFormatter disabled across most project types (.NET 8)](../8.0/binaryformatter-disabled.md) diff --git a/docs/core/compatibility/core-libraries/7.0/binaryformatter-apis-produce-errors.md b/docs/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors.md similarity index 97% rename from docs/core/compatibility/core-libraries/7.0/binaryformatter-apis-produce-errors.md rename to docs/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors.md index 91bece63528a7..c5a6d84451bae 100644 --- a/docs/core/compatibility/core-libraries/7.0/binaryformatter-apis-produce-errors.md +++ b/docs/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors.md @@ -90,4 +90,5 @@ The ` and methods now through a at run time across nearly all project types, including console applications. + +## Previous behavior + +In .NET 7, the and methods were marked obsolete and raised an error at compile time. However, if your application suppressed the obsoletion, it could still call the methods and they functioned properly in most project types (excluding ASP.NET, WASM, and MAUI). For example, the APIs functioned correctly in a console app. + +## New behavior + +Starting in .NET 8, the affected methods throw a at run time across all project types except Windows Forms and WPF. The APIs continue to remain obsolete (as error) across all project types, including Windows Forms and WPF. + +## Version introduced + +.NET 8 Preview 4 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This run-time change is the next stage of the [BinaryFormatter obsoletion plan](https://github.com/dotnet/designs/blob/main/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md), in which will eventually be removed from .NET. + +## Recommended action + +**The best course of action is to migrate away from `BinaryFormatter` due to its security and reliability flaws.** + +However, should you need to continue using `BinaryFormatter`, you can set a compatibility switch in your project file to re-enable `BinaryFormatter` functionality. For more information, see the [Recommended action](../7.0/binaryformatter-apis-produce-errors.md#recommended-action) section of the .NET 7 breaking change notification. That compatibility switch continues to be honored in .NET 8. + +## Affected APIs + +- +- + +## See also + +- [BinaryFormatter serialization methods are obsolete (.NET 5)](../5.0/binaryformatter-serialization-obsolete.md) +- [SerializationFormat.Binary is obsolete (.NET 7)](../7.0/serializationformat-binary.md) +- [BinaryFormatter serialization APIs produce compiler errors (.NET 7)](../7.0/binaryformatter-apis-produce-errors.md) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 73057b8ad528a..817543af6f1ae 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -14,6 +14,8 @@ items: href: core-libraries/8.0/activity-operation-name.md - name: AnonymousPipeServerStream.Dispose behavior href: core-libraries/8.0/anonymouspipeserverstream-dispose.md + - name: API obsoletions with custom diagnostic IDs + href: core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md - name: Backslash mapping in Unix file paths href: core-libraries/8.0/file-path-backslash.md - name: FileStream writes when pipe is closed @@ -58,6 +60,10 @@ items: href: sdk/8.0/dotnet-pack-config.md - name: "'dotnet publish' uses Release configuration" href: sdk/8.0/dotnet-publish-config.md + - name: Serialization + items: + - name: BinaryFormatter disabled for most projects + href: serialization/8.0/binaryformatter-disabled.md - name: Windows Forms items: - name: Anchor layout changes @@ -118,8 +124,6 @@ items: href: core-libraries/7.0/obsolete-apis-with-default-diagnostic.md - name: API obsoletions with non-default diagnostic IDs href: core-libraries/7.0/obsolete-apis-with-custom-diagnostics.md - - name: BinaryFormatter serialization APIs produce compiler errors - href: core-libraries/7.0/binaryformatter-apis-produce-errors.md - name: BrotliStream no longer allows undefined CompressionLevel values href: core-libraries/7.0/brotlistream-ctor.md - name: C++/CLI projects in Visual Studio @@ -140,8 +144,6 @@ items: href: core-libraries/7.0/max-precision-numeric-format-strings.md - name: Reflection invoke API exceptions href: core-libraries/7.0/reflection-invoke-exceptions.md - - name: SerializationFormat.Binary is obsolete - href: core-libraries/7.0/serializationformat-binary.md - name: System.Runtime.CompilerServices.Unsafe NuGet package href: core-libraries/7.0/unsafe-package.md - name: Time fields on symbolic links @@ -224,6 +226,10 @@ items: href: sdk/7.0/solution-level-output-no-longer-valid.md - name: Serialization items: + - name: BinaryFormatter serialization APIs produce compiler errors + href: serialization/7.0/binaryformatter-apis-produce-errors.md + - name: SerializationFormat.Binary is obsolete + href: serialization/7.0/serializationformat-binary.md - name: DataContractSerializer retains sign when deserializing -0 href: serialization/7.0/datacontractserializer-negative-sign.md - name: Deserialize Version type with leading or trailing whitespace @@ -475,7 +481,7 @@ items: - name: AzureAD.UI and AzureADB2C.UI APIs obsolete href: aspnet-core/5.0/authentication-aad-packages-obsolete.md - name: BinaryFormatter serialization methods are obsolete - href: core-libraries/5.0/binaryformatter-serialization-obsolete.md + href: serialization/5.0/binaryformatter-serialization-obsolete.md - name: Resource in endpoint routing is HttpContext href: aspnet-core/5.0/authorization-resource-in-endpoint-routing.md - name: Microsoft-prefixed Azure integration packages removed @@ -564,8 +570,6 @@ items: items: - name: Assembly-related API changes for single-file publishing href: core-libraries/5.0/assembly-api-behavior-changes-for-single-file-publish.md - - name: BinaryFormatter serialization methods are obsolete - href: core-libraries/5.0/binaryformatter-serialization-obsolete.md - name: Code access security APIs are obsolete href: core-libraries/5.0/code-access-security-apis-obsolete.md - name: CreateCounterSetInstance throws InvalidOperationException @@ -690,6 +694,8 @@ items: href: core-libraries/5.0/utf-7-code-paths-obsolete.md - name: Serialization items: + - name: BinaryFormatter serialization methods are obsolete + href: serialization/5.0/binaryformatter-serialization-obsolete.md - name: BinaryFormatter.Deserialize rewraps exceptions href: serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md - name: JsonSerializer.Deserialize requires single-character string @@ -831,7 +837,7 @@ items: - name: AzureAD.UI and AzureADB2C.UI APIs obsolete href: aspnet-core/5.0/authentication-aad-packages-obsolete.md - name: BinaryFormatter serialization methods are obsolete - href: core-libraries/5.0/binaryformatter-serialization-obsolete.md + href: serialization/5.0/binaryformatter-serialization-obsolete.md - name: Resource in endpoint routing is HttpContext href: aspnet-core/5.0/authorization-resource-in-endpoint-routing.md - name: Microsoft-prefixed Azure integration packages removed @@ -942,6 +948,8 @@ items: href: core-libraries/8.0/activity-operation-name.md - name: AnonymousPipeServerStream.Dispose behavior href: core-libraries/8.0/anonymouspipeserverstream-dispose.md + - name: API obsoletions with custom diagnostic IDs + href: core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md - name: Backslash mapping in Unix file paths href: core-libraries/8.0/file-path-backslash.md - name: FileStream writes when pipe is closed @@ -958,8 +966,6 @@ items: href: core-libraries/7.0/obsolete-apis-with-default-diagnostic.md - name: API obsoletions with non-default diagnostic IDs href: core-libraries/7.0/obsolete-apis-with-custom-diagnostics.md - - name: BinaryFormatter serialization APIs produce compiler errors - href: core-libraries/7.0/binaryformatter-apis-produce-errors.md - name: BrotliStream no longer allows undefined CompressionLevel values href: core-libraries/7.0/brotlistream-ctor.md - name: C++/CLI projects in Visual Studio @@ -980,8 +986,6 @@ items: href: core-libraries/7.0/max-precision-numeric-format-strings.md - name: Reflection invoke API exceptions href: core-libraries/7.0/reflection-invoke-exceptions.md - - name: SerializationFormat.Binary is obsolete - href: core-libraries/7.0/serializationformat-binary.md - name: System.Runtime.CompilerServices.Unsafe NuGet package href: core-libraries/7.0/unsafe-package.md - name: Time fields on symbolic links @@ -1044,8 +1048,6 @@ items: items: - name: Assembly-related API changes for single-file publishing href: core-libraries/5.0/assembly-api-behavior-changes-for-single-file-publish.md - - name: BinaryFormatter serialization methods are obsolete - href: core-libraries/5.0/binaryformatter-serialization-obsolete.md - name: Code access security APIs are obsolete href: core-libraries/5.0/code-access-security-apis-obsolete.md - name: CreateCounterSetInstance throws InvalidOperationException @@ -1382,8 +1384,16 @@ items: href: core-libraries/5.0/utf-7-code-paths-obsolete.md - name: Serialization items: + - name: .NET 8 + items: + - name: BinaryFormatter disabled for most projects + href: serialization/8.0/binaryformatter-disabled.md - name: .NET 7 items: + - name: BinaryFormatter serialization APIs produce compiler errors + href: serialization/7.0/binaryformatter-apis-produce-errors.md + - name: SerializationFormat.Binary is obsolete + href: serialization/7.0/serializationformat-binary.md - name: DataContractSerializer retains sign when deserializing -0 href: serialization/7.0/datacontractserializer-negative-sign.md - name: Deserialize Version type with leading or trailing whitespace @@ -1410,6 +1420,8 @@ items: href: serialization/6.0/jsonserializer-source-generator-overloads.md - name: .NET 5 items: + - name: BinaryFormatter serialization methods are obsolete + href: serialization/5.0/binaryformatter-serialization-obsolete.md - name: BinaryFormatter.Deserialize rewraps exceptions href: serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md - name: JsonSerializer.Deserialize requires single-character string diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index 24f5a8984132b..1cc169b4c6dbf 100644 --- a/docs/core/compatibility/unsupported-apis.md +++ b/docs/core/compatibility/unsupported-apis.md @@ -2,11 +2,11 @@ title: Unsupported APIs on .NET Core and .NET 5+ titleSuffix: "" description: Learn which .NET APIs always throw an exception on .NET Core and .NET 5 and later versions. -ms.date: 01/24/2023 +ms.date: 05/02/2023 --- # APIs that always throw exceptions on .NET Core and .NET 5+ -The following APIs will always throw an exception on .NET 5 and later versions (including all versions of .NET Core) on all or a subset of platforms. In most cases, the exception that's thrown is . +The following APIs will always throw an exception on .NET (Core) on all or a subset of platforms. In most cases, the exception that's thrown is . This article organizes the affected APIs by namespace. @@ -196,8 +196,12 @@ This article organizes the affected APIs by namespace. | Member | Platforms that throw | | - | - | +| * | All | +| * | All | | | All | +\* .NET 8 and later versions only for all project types except Windows Forms and WPF. + ## System.Security | Member | Platforms that throw | diff --git a/docs/core/deploying/trimming/trimming-options.md b/docs/core/deploying/trimming/trimming-options.md index b6c861f50c049..ccfc6aa53f15b 100644 --- a/docs/core/deploying/trimming/trimming-options.md +++ b/docs/core/deploying/trimming/trimming-options.md @@ -228,7 +228,7 @@ Several feature areas of the framework libraries come with trimmer directives th - `false` - Remove BinaryFormatter serialization support. For more information, see [BinaryFormatter serialization methods are obsolete](../../compatibility/core-libraries/5.0/binaryformatter-serialization-obsolete.md). + Remove BinaryFormatter serialization support. For more information, see [BinaryFormatter serialization methods are obsolete](../../compatibility/serialization/5.0/binaryformatter-serialization-obsolete.md). - `false` diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index 8b4dfbe9de595..a2696f94ebaca 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -2,7 +2,7 @@ title: Obsolete features in .NET 5+ titleSuffix: "" description: Learn about APIs that are marked as obsolete in .NET 5 and later versions that produce SYSLIB compiler warnings. -ms.date: 01/24/2023 +ms.date: 05/05/2023 --- # Obsolete features in .NET 5+ @@ -69,6 +69,8 @@ The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+ | [SYSLIB0046](syslib0046.md) | Warning | The method might corrupt the process and should not be used in production code. | | [SYSLIB0047](syslib0047.md) | Warning | is obsolete. Use `XmlResolver.ThrowingResolver` instead when attempting to forbid XML external entity resolution. | | [SYSLIB0048](syslib0048.md) | Warning | and are obsolete. Use and instead. | +| [SYSLIB0050](syslib0050.md) | Warning | Formatter-based serialization is obsolete and should not be used. | +| [SYSLIB0051](syslib0051.md) | Warning | APIs that support obsolete formatter-based serialization are obsolete. They should not be called or extended by application code. | ## Suppress warnings @@ -112,3 +114,4 @@ To suppress the warnings in a project file: - [API obsoletions with non-default diagnostic IDs (.NET 5)](../../core/compatibility/core-libraries/5.0/obsolete-apis-with-custom-diagnostics.md) - [API obsoletions with non-default diagnostic IDs (.NET 6)](../../core/compatibility/core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md) - [API obsoletions with non-default diagnostic IDs (.NET 7)](../../core/compatibility/core-libraries/7.0/obsolete-apis-with-custom-diagnostics.md) +- [API obsoletions with non-default diagnostic IDs (.NET 8)](../../core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0011.md b/docs/fundamentals/syslib-diagnostics/syslib0011.md index b56dc48dd5315..ac9dbb6a618a4 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0011.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0011.md @@ -1,11 +1,11 @@ --- title: SYSLIB0011 warning description: Learn about the obsoletions that generate compile-time warning SYSLIB0011. -ms.date: 10/20/2020 +ms.date: 05/08/2023 --- # SYSLIB0011: BinaryFormatter serialization is obsolete -Due to [security vulnerabilities](../../standard/serialization/binaryformatter-security-guide.md#binaryformatter-security-vulnerabilities) in , the following APIs are marked as obsolete, starting in .NET 5. Using them in code generates warning `SYSLIB0011` at compile time. +Due to [security vulnerabilities](../../standard/serialization/binaryformatter-security-guide.md#binaryformatter-security-vulnerabilities) in , the following APIs were marked as obsolete in .NET 5. Using them in code generates warning or error `SYSLIB0011` at compile time. - - @@ -15,15 +15,19 @@ Due to [security vulnerabilities](../../standard/serialization/binaryformatter-s - - -## Workarounds +Starting in .NET 8, and throw a at run time on most project types. In addition, the following APIs are marked obsolete *as error*: + +- +- +- -Consider using or instead of . +## Workarounds -For more information about recommended actions, see [Resolving BinaryFormatter obsoletion and disablement errors](../../standard/serialization/binaryformatter-security-guide.md). +If you're using , you should migrate away from it due to its security and reliability flaws. For more information, see [Deserialization risks in use of BinaryFormatter and related types](../../standard/serialization/binaryformatter-security-guide.md) and [Preferred alternatives](../../standard/serialization/binaryformatter-security-guide.md#preferred-alternatives). ## Suppress a warning -If you must use the obsolete APIs, you can suppress the warning in code or in your project file. +If you must use the obsolete APIs, you can suppress the warning/error in code or in your project file. To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. @@ -54,4 +58,6 @@ For more information, see [Suppress warnings](obsoletions-overview.md#suppress-w ## See also - [Resolving BinaryFormatter obsoletion and disablement errors](../../standard/serialization/binaryformatter-security-guide.md) -- [BinaryFormatter serialization methods are obsolete and prohibited in ASP.NET apps](../../core/compatibility/core-libraries/5.0/binaryformatter-serialization-obsolete.md) +- [BinaryFormatter serialization methods are obsolete and prohibited in ASP.NET apps (.NET 5)](../../core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete.md) +- [BinaryFormatter serialization APIs produce compiler errors (.NET 7)](../../core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors.md) +- [BinaryFormatter disabled across most project types (.NET 8)](../../core/compatibility/serialization/8.0/binaryformatter-disabled.md) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0038.md b/docs/fundamentals/syslib-diagnostics/syslib0038.md index 4834279ddc8f0..76d59548b3df6 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0038.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0038.md @@ -45,4 +45,4 @@ For more information, see [Suppress warnings](obsoletions-overview.md#suppress-w ## See also -- [SerializationFormat.Binary is obsolete](../../core/compatibility/core-libraries/7.0/serializationformat-binary.md) +- [SerializationFormat.Binary is obsolete](../../core/compatibility/serialization/7.0/serializationformat-binary.md) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0050.md b/docs/fundamentals/syslib-diagnostics/syslib0050.md new file mode 100644 index 0000000000000..f47e9568c0315 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0050.md @@ -0,0 +1,88 @@ +--- +title: SYSLIB0050 warning - Formatter-based serialization is obsolete +description: Learn about the obsoletion of formatter-based serialization APIs that generates compile-time warning SYSLIB0050. +ms.date: 05/11/2023 +--- +# SYSLIB0050: Formatter-based serialization is obsolete + +The following APIs are obsolete, starting in .NET 8. Calling them in code generates warning `SYSLIB0050` at compile time. + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +## Workaround + +- If you were using , use instead. + + If you cross-compile for .NET Framework and modern .NET, you can use an `#if` statement to selectively call the appropriate API, as shown in the following snippet. + + ```csharp + Type typeToInstantiate; + #if NET5_0_OR_GREATER + object obj = System.Runtime.CompilerServices.RuntimeHelpers.GetUninitializedObject(typeToInstantiate); + #else + object obj = System.Runtime.Serialization.FormatterServices.GetUninitializedObject(typeToInstantiate); + #endif + ``` + +- If you're writing a serialization library, we strongly recommend against serialization libraries that support the legacy serialization infrastructure (`[Serializable]` and `ISerializable`). Modern serialization libraries should have policy based on a type's public APIs rather than its private implementation details. If you base a serializer on these implementation details and strongly tie it to `ISerializable` and other mechanisms that encourage embedding type names within the serialized payload, it can lead to the problems described in [Deserialization risks in use of BinaryFormatter and related types](../../standard/serialization/binaryformatter-security-guide.md). + + If your serialization library must remain compatible with the legacy serialization infrastructure, you can easily [suppress](#suppress-a-warning) the legacy serialization API obsoletions. + +## Suppress a warning + +If you must use the obsolete APIs, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0050 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0050 +``` + +To suppress all the `SYSLIB0050` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0050 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). + +## See also + +- [SYSLIB0051: Legacy serialization support APIs are obsolete](syslib0051.md) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0051.md b/docs/fundamentals/syslib-diagnostics/syslib0051.md new file mode 100644 index 0000000000000..e51ec1de5512b --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0051.md @@ -0,0 +1,139 @@ +--- +title: SYSLIB0051 warning - Legacy serialization support APIs are obsolete +description: Learn about the obsoletion of APIs that support formatter-based serialization that generates compile-time warning SYSLIB0051. +ms.date: 05/11/2023 +--- +# SYSLIB0051: Legacy serialization support APIs are obsolete + +The following kinds of APIs are obsolete, starting in .NET 8. Calling them in code generates warning `SYSLIB0051` at compile time. + +- All public or protected serialization constructors that follow the pattern `.ctor(SerializationInfo, StreamingContext)`. An example of such a constructor is . +- All implicit implementations of the method, for example, . +- All implicit implementations of the method, for example, . + +For a complete list of affected APIs, see [Obsolete APIs - SYSLIB0051](../../core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md#syslib0051). + +## Workaround + +- If you created a custom type derived from , consider whether you really need it to be serializable. It's likely that you don't need it to be serializable, as exception serialization is primarily intended to support remoting, and support for remoting was dropped in .NET Core 1.0. + + If your custom exception type is defined like the one shown in the following code snippet, simply remove the `[Serializable]` attribute, the serialization constructor, and the method override. + + ```csharp + [Serializable] // Remove this attribute. + public class MyException : Exception + { + public MyException() { } + public MyException(string message) : base(message) { } + public MyException(string message, Exception inner) : base(message, inner) { } + + // Remove this constructor. + protected MyException(SerializationInfo info, StreamingContext context) + : base(info, context) + { + // ... + } + + // Remove this method. + public override void GetObjectData(SerializationInfo info, StreamingContext context) + { + // ... + + base.GetObjectData(info, context); + } + } + ``` + + There might be cases where you can't remove these APIs from your custom exception type, for example, if you produce a library constrained by API compatibility requirements. In this case, the recommendation is to obsolete your own serialization constructor and `GetObjectData` methods using the `SYSLIB0051` diagnostic code, as shown in the following code. Since ideally nobody outside the serialization infrastructure itself should be calling these APIs, obsoletion should only impact other types that subclass your custom exception type. It should not virally impact anybody catching, constructing, or otherwise using your custom exception type. + + ```csharp + [Serializable] + public class MyException : Exception + { + public MyException() { } + public MyException(string message) : base(message) { } + public MyException(string message, Exception inner) : base(message, inner) { } + + [Obsolete(DiagnosticId = "SYSLIB0051")] // Add this attribute to the serialization ctor. + protected MyException(SerializationInfo info, StreamingContext context) + : base(info, context) + { + // ... + } + + [Obsolete(DiagnosticId = "SYSLIB0051")] // Add this attribute to GetObjectData. + public override void GetObjectData(SerializationInfo info, StreamingContext context) + { + // ... + + base.GetObjectData(info, context); + } + } + ``` + + If you cross-target for .NET Framework and .NET 8+, you can use an `#if` statement to apply the obsoletion conditionally. This is the same strategy that the .NET team uses within the .NET libraries code base when cross-targeting runtimes. + + ```csharp + [Serializable] + public class MyException : Exception + { + // ... + + #if NET8_0_OR_GREATER + [Obsolete(DiagnosticId = "SYSLIB0051")] // add this attribute to the serialization ctor + #endif + protected MyException(SerializationInfo info, StreamingContext context) + : base(info, context) + { + // ... + } + + #if NET8_0_OR_GREATER + [Obsolete(DiagnosticId = "SYSLIB0051")] // add this attribute to GetObjectData + #endif + public override void GetObjectData(SerializationInfo info, StreamingContext context) + { + // ... + + base.GetObjectData(info, context); + } + } + +- If you've declared a type that subclasses a .NET type that's attributed with `[Serializable]` and you're getting `SYSLIB0051` warnings, follow the guidance for custom exception types in the previous bullet point. + +> [!TIP] +> If your `[Serializable]` custom type doesn't subclass a .NET type, you won't see `SYSLIB0051` warnings. However, we recommend against annotating your type in this manner, as modern serialization libraries like `System.Text.Json` don't require them. Consider removing the `[Serializable]` attribute and the `ISerializable` interface. Instead, rely on your serialization library to access objects of the type through its public properties rather than its private fields. + +## Suppress a warning + +If you must use the obsolete APIs, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0051 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0051 +``` + +To suppress all the `SYSLIB0051` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0051 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). + +## See also + +- [SYSLIB0050: Formatter-based serialization is obsolete](syslib0050.md) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index f9b5c964f0b14..b9c058acfa6c3 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1452,6 +1452,10 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0047.md - name: SYSLIB0048 href: ../../fundamentals/syslib-diagnostics/syslib0048.md + - name: SYSLIB0050 + href: ../../fundamentals/syslib-diagnostics/syslib0050.md + - name: SYSLIB0051 + href: ../../fundamentals/syslib-diagnostics/syslib0051.md - name: Source-generated code items: - name: Overview