From 0322d5d9c66a44f0ad0372b9cbd08d563dfd78e0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 1 May 2023 19:43:40 -0700 Subject: [PATCH 01/16] BinaryFormatter breaking change for .NET 8 --- .openpublishing.redirection.core.json | 10 +++++ docs/core/compatibility/5.0.md | 4 +- docs/core/compatibility/7.0.md | 2 +- docs/core/compatibility/8.0.md | 6 +++ .../binaryformatter-serialization-obsolete.md | 1 + .../binaryformatter-apis-produce-errors.md | 3 +- .../7.0/serializationformat-binary.md | 0 .../8.0/binaryformatter-disabled.md | 45 +++++++++++++++++++ docs/core/compatibility/toc.yml | 16 ++++--- .../deploying/trimming/trimming-options.md | 2 +- .../syslib-diagnostics/syslib0011.md | 8 ++-- 11 files changed, 83 insertions(+), 14 deletions(-) rename docs/core/compatibility/{core-libraries => serialization}/5.0/binaryformatter-serialization-obsolete.md (98%) rename docs/core/compatibility/{core-libraries => serialization}/7.0/binaryformatter-apis-produce-errors.md (97%) rename docs/core/compatibility/{core-libraries => serialization}/7.0/serializationformat-binary.md (100%) create mode 100644 docs/core/compatibility/serialization/8.0/binaryformatter-disabled.md diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 6ebe59ebce701..973881bea9004 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -74,6 +74,16 @@ "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/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..8bbb78f544276 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 | diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index 27778379868f7..363cde162d59f 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -64,6 +64,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/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..1c31946bf3be5 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -58,6 +58,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 @@ -119,7 +123,7 @@ items: - 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 + href: /dotnet/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors - name: BrotliStream no longer allows undefined CompressionLevel values href: core-libraries/7.0/brotlistream-ctor.md - name: C++/CLI projects in Visual Studio @@ -475,7 +479,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: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete - 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 @@ -565,7 +569,7 @@ 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 + href: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete - name: Code access security APIs are obsolete href: core-libraries/5.0/code-access-security-apis-obsolete.md - name: CreateCounterSetInstance throws InvalidOperationException @@ -831,7 +835,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: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete - 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 @@ -959,7 +963,7 @@ items: - 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 + href: /dotnet/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors - name: BrotliStream no longer allows undefined CompressionLevel values href: core-libraries/7.0/brotlistream-ctor.md - name: C++/CLI projects in Visual Studio @@ -1045,7 +1049,7 @@ 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 + href: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete - name: Code access security APIs are obsolete href: core-libraries/5.0/code-access-security-apis-obsolete.md - name: CreateCounterSetInstance throws InvalidOperationException 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/syslib0011.md b/docs/fundamentals/syslib-diagnostics/syslib0011.md index b56dc48dd5315..ff511f21c9014 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0011.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0011.md @@ -5,7 +5,7 @@ ms.date: 10/20/2020 --- # 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 are marked as obsolete, starting in .NET 5. Using them in code generates warning or error `SYSLIB0011` at compile time. - - @@ -23,7 +23,7 @@ For more information about recommended actions, see [Resolving BinaryFormatter o ## 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 +54,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) From 33843c6a2cc12ebcf2b2eb9cffa2d9856ab7c35e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 1 May 2023 19:57:03 -0700 Subject: [PATCH 02/16] fix up toc --- docs/core/compatibility/toc.yml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 1c31946bf3be5..750e44ed44c59 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -122,8 +122,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: /dotnet/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors - name: BrotliStream no longer allows undefined CompressionLevel values href: core-libraries/7.0/brotlistream-ctor.md - name: C++/CLI projects in Visual Studio @@ -228,6 +226,8 @@ 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 - name: DataContractSerializer retains sign when deserializing -0 href: serialization/7.0/datacontractserializer-negative-sign.md - name: Deserialize Version type with leading or trailing whitespace @@ -479,7 +479,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: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete + href: serialization/5.0/binaryformatter-serialization-obsolete - 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 @@ -568,8 +568,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: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete - name: Code access security APIs are obsolete href: core-libraries/5.0/code-access-security-apis-obsolete.md - name: CreateCounterSetInstance throws InvalidOperationException @@ -694,6 +692,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 - name: BinaryFormatter.Deserialize rewraps exceptions href: serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md - name: JsonSerializer.Deserialize requires single-character string @@ -835,7 +835,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: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete + href: serialization/5.0/binaryformatter-serialization-obsolete - 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 @@ -962,8 +962,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: /dotnet/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors - name: BrotliStream no longer allows undefined CompressionLevel values href: core-libraries/7.0/brotlistream-ctor.md - name: C++/CLI projects in Visual Studio @@ -1048,8 +1046,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: /dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete - name: Code access security APIs are obsolete href: core-libraries/5.0/code-access-security-apis-obsolete.md - name: CreateCounterSetInstance throws InvalidOperationException @@ -1388,6 +1384,8 @@ items: items: - name: .NET 7 items: + - name: BinaryFormatter serialization APIs produce compiler errors + href: serialization/7.0/binaryformatter-apis-produce-errors - name: DataContractSerializer retains sign when deserializing -0 href: serialization/7.0/datacontractserializer-negative-sign.md - name: Deserialize Version type with leading or trailing whitespace @@ -1414,6 +1412,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 - name: BinaryFormatter.Deserialize rewraps exceptions href: serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md - name: JsonSerializer.Deserialize requires single-character string From 1cd6e4021e1d939996c0830721d5dd6541faf7a4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 1 May 2023 20:02:35 -0700 Subject: [PATCH 03/16] add missing redirect --- .openpublishing.redirection.core.json | 5 +++++ docs/core/compatibility/7.0.md | 2 +- docs/core/compatibility/toc.yml | 8 ++++---- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 973881bea9004..4f3ae206e79aa 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -84,6 +84,11 @@ "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/7.0.md b/docs/core/compatibility/7.0.md index 8bbb78f544276..2c8db03859d41 100644 --- a/docs/core/compatibility/7.0.md +++ b/docs/core/compatibility/7.0.md @@ -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/toc.yml b/docs/core/compatibility/toc.yml index 750e44ed44c59..4e4601836fb13 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -142,8 +142,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 @@ -228,6 +226,8 @@ items: items: - name: BinaryFormatter serialization APIs produce compiler errors href: serialization/7.0/binaryformatter-apis-produce-errors + - name: SerializationFormat.Binary is obsolete + href: serialization/7.0/serializationformat-binary - name: DataContractSerializer retains sign when deserializing -0 href: serialization/7.0/datacontractserializer-negative-sign.md - name: Deserialize Version type with leading or trailing whitespace @@ -982,8 +982,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 @@ -1386,6 +1384,8 @@ items: items: - name: BinaryFormatter serialization APIs produce compiler errors href: serialization/7.0/binaryformatter-apis-produce-errors + - name: SerializationFormat.Binary is obsolete + href: serialization/7.0/serializationformat-binary - name: DataContractSerializer retains sign when deserializing -0 href: serialization/7.0/datacontractserializer-negative-sign.md - name: Deserialize Version type with leading or trailing whitespace From d8c5a9fa25bfe1a74076123e041109dfafe6813e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 1 May 2023 20:09:36 -0700 Subject: [PATCH 04/16] fix link --- docs/fundamentals/syslib-diagnostics/syslib0038.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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) From bb8fb83add6e1578c2cbfe225939db907291cbbc Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 1 May 2023 20:28:14 -0700 Subject: [PATCH 05/16] add .md extensions --- docs/core/compatibility/toc.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 4e4601836fb13..27e3a4db89a49 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -225,9 +225,9 @@ items: - name: Serialization items: - name: BinaryFormatter serialization APIs produce compiler errors - href: serialization/7.0/binaryformatter-apis-produce-errors + href: serialization/7.0/binaryformatter-apis-produce-errors.md - name: SerializationFormat.Binary is obsolete - href: serialization/7.0/serializationformat-binary + 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 @@ -479,7 +479,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: serialization/5.0/binaryformatter-serialization-obsolete + 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 @@ -693,7 +693,7 @@ items: - name: Serialization items: - name: BinaryFormatter serialization methods are obsolete - href: serialization/5.0/binaryformatter-serialization-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 @@ -835,7 +835,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: serialization/5.0/binaryformatter-serialization-obsolete + 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 @@ -1383,9 +1383,9 @@ items: - name: .NET 7 items: - name: BinaryFormatter serialization APIs produce compiler errors - href: serialization/7.0/binaryformatter-apis-produce-errors + href: serialization/7.0/binaryformatter-apis-produce-errors.md - name: SerializationFormat.Binary is obsolete - href: serialization/7.0/serializationformat-binary + 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 @@ -1413,7 +1413,7 @@ items: - name: .NET 5 items: - name: BinaryFormatter serialization methods are obsolete - href: serialization/5.0/binaryformatter-serialization-obsolete + href: serialization/5.0/binaryformatter-serialization-.md - name: BinaryFormatter.Deserialize rewraps exceptions href: serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md - name: JsonSerializer.Deserialize requires single-character string From 82a440adf3c26c95c74c2de938da52fdf54345fb Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 1 May 2023 20:34:58 -0700 Subject: [PATCH 06/16] fix another one --- docs/core/compatibility/toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 27e3a4db89a49..f3c6be9bc6073 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -1413,7 +1413,7 @@ items: - name: .NET 5 items: - name: BinaryFormatter serialization methods are obsolete - href: serialization/5.0/binaryformatter-serialization-.md + 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 From ab165756250e0476f9be608d333a6638bad65bdc Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 2 May 2023 12:47:32 -0700 Subject: [PATCH 07/16] add APIs to unsupported APIs doc --- docs/core/compatibility/unsupported-apis.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index 24f5a8984132b..5ca0d6ab7cf43 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 | From cc49cabb0a2b8be27703822ea7c3859a74e56304 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 2 May 2023 12:54:03 -0700 Subject: [PATCH 08/16] fix note --- docs/core/compatibility/unsupported-apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index 5ca0d6ab7cf43..1cc169b4c6dbf 100644 --- a/docs/core/compatibility/unsupported-apis.md +++ b/docs/core/compatibility/unsupported-apis.md @@ -200,7 +200,7 @@ This article organizes the affected APIs by namespace. | * | All | | | All | -> - .NET 8 and later versions only for all project types except Windows Forms and WPF. +\* .NET 8 and later versions only for all project types except Windows Forms and WPF. ## System.Security From 35ca473d0f1f3ae0cc36e1ef7f37c85b2fa8547e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 2 May 2023 13:11:47 -0700 Subject: [PATCH 09/16] one more thing --- docs/fundamentals/syslib-diagnostics/syslib0011.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0011.md b/docs/fundamentals/syslib-diagnostics/syslib0011.md index ff511f21c9014..e9e2f49ae1bed 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0011.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0011.md @@ -15,6 +15,8 @@ Due to [security vulnerabilities](../../standard/serialization/binaryformatter-s - - +Starting in .NET 8, and throw a at run time on most project types. + ## Workarounds Consider using or instead of . From a5055d1bde139bef123aa19bb45b46108b50a0be Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 8 May 2023 21:41:59 -0700 Subject: [PATCH 10/16] add syslib0050 and syslib0051 and update syslib0011 --- docs/core/compatibility/8.0.md | 3 +- .../obsolete-apis-with-custom-diagnostics.md | 88 +++++ docs/core/compatibility/toc.yml | 4 + .../obsoletions-overview.md | 5 +- .../syslib-diagnostics/syslib0011.md | 14 +- .../syslib-diagnostics/syslib0050.md | 178 +++++++++ .../syslib-diagnostics/syslib0051.md | 354 ++++++++++++++++++ docs/navigate/tools-diagnostics/toc.yml | 4 + 8 files changed, 642 insertions(+), 8 deletions(-) create mode 100644 docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md create mode 100644 docs/fundamentals/syslib-diagnostics/syslib0050.md create mode 100644 docs/fundamentals/syslib-diagnostics/syslib0051.md diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index 363cde162d59f..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 | 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..9d57eaa0c9c6b --- /dev/null +++ b/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md @@ -0,0 +1,88 @@ +--- +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 + +- 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 [SYSLIB0051: Legacy serialization support APIs are obsolete](../../../../fundamentals/syslib-diagnostics/syslib0051.md). + +## 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/toc.yml b/docs/core/compatibility/toc.yml index f3c6be9bc6073..159fa8fb46352 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 @@ -946,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 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 e9e2f49ae1bed..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 or error `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,13 +15,15 @@ Due to [security vulnerabilities](../../standard/serialization/binaryformatter-s - - -Starting in .NET 8, and throw a at run time on most project types. +Starting in .NET 8, and throw a at run time on most project types. In addition, the following APIs are marked obsolete *as error*: -## Workarounds +- +- +- -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 diff --git a/docs/fundamentals/syslib-diagnostics/syslib0050.md b/docs/fundamentals/syslib-diagnostics/syslib0050.md new file mode 100644 index 0000000000000..c2f0b57248796 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0050.md @@ -0,0 +1,178 @@ +--- +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/05/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 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'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. + + + $(NoWarn);SYSLIB0050 + + +## 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..8d71e31723c58 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0051.md @@ -0,0 +1,354 @@ +--- +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/05/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)`. +- All implicit implementations of the method. +- All implicit implementations of the method. + +The complete list of affected APIs is: + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +## Workaround + +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 for SYSLIB0050](syslib0050.md#custom-exceptions). + +> [!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 From cbacbc4a7aebddbac71f5bb8fa0a392e5a7c103b Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 8 May 2023 21:56:41 -0700 Subject: [PATCH 11/16] fix errors --- docs/core/compatibility/toc.yml | 4 ++ .../syslib-diagnostics/syslib0050.md | 4 -- .../syslib-diagnostics/syslib0051.md | 41 ++++++++----------- 3 files changed, 22 insertions(+), 27 deletions(-) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 159fa8fb46352..817543af6f1ae 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -1384,6 +1384,10 @@ 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 diff --git a/docs/fundamentals/syslib-diagnostics/syslib0050.md b/docs/fundamentals/syslib-diagnostics/syslib0050.md index c2f0b57248796..84d2a55711663 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0050.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0050.md @@ -139,10 +139,6 @@ The following APIs are obsolete, starting in .NET 8. Calling them in code genera If your serialization library must remain compatible with the legacy serialization infrastructure, you can easily [suppress](#suppress-a-warning) the legacy serialization API obsoletions. - - $(NoWarn);SYSLIB0050 - - ## Suppress a warning If you must use the obsolete APIs, you can suppress the warning in code or in your project file. diff --git a/docs/fundamentals/syslib-diagnostics/syslib0051.md b/docs/fundamentals/syslib-diagnostics/syslib0051.md index 8d71e31723c58..ffa129b3d9f35 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0051.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0051.md @@ -83,10 +83,10 @@ The complete list of affected APIs is: - - - -- -- +- +- - -- +- - - - @@ -124,10 +124,10 @@ The complete list of affected APIs is: - - - -- +- - - -- +- - - - @@ -197,9 +197,6 @@ The complete list of affected APIs is: - - - -- -- -- - - - @@ -226,11 +223,9 @@ The complete list of affected APIs is: - - - -- -- - -- -- +- +- - - - @@ -299,22 +294,22 @@ The complete list of affected APIs is: - - - -- -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- +- - - ## Workaround -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 for SYSLIB0050](syslib0050.md#custom-exceptions). +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 for SYSLIB0050](syslib0050.md#custom-exception). > [!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. From 1d8741770791aa01f58a11d22665dd8385aafbea Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 9 May 2023 08:05:30 -0700 Subject: [PATCH 12/16] fix xref --- docs/fundamentals/syslib-diagnostics/syslib0051.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0051.md b/docs/fundamentals/syslib-diagnostics/syslib0051.md index ffa129b3d9f35..d926d43e13b0d 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0051.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0051.md @@ -84,7 +84,7 @@ The complete list of affected APIs is: - - - -- +- - - - From 90f932bef24ddb5c90ab2986e408600a8bde7a0d Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 9 May 2023 12:29:43 -0700 Subject: [PATCH 13/16] update api list for syslib0051 --- .../obsolete-apis-with-custom-diagnostics.md | 516 +++++++++++++++++- .../syslib-diagnostics/syslib0051.md | 302 +--------- 2 files changed, 516 insertions(+), 302 deletions(-) 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 index 9d57eaa0c9c6b..88bf762829dfb 100644 --- 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 @@ -74,11 +74,519 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c ### SYSLIB0051 -- 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, . +Use the following index to see `SYSLIB0051` API obsoletions by namespace: -For a complete list of affected APIs, see [SYSLIB0051: Legacy serialization support APIs are obsolete](../../../../fundamentals/syslib-diagnostics/syslib0051.md). +- [Microsoft.CSharp.RuntimeBinder namespace](#microsoftcsharpruntimebinder-namespace) +- [Microsoft.VisualBasic.FileIO namespace](#microsoftvisualbasicfileio-namespace) +- [System namespace](#system-namespace) +- [System.Collections namespace](#systemcollections-namespace) +- [System.Collections.Generic namespace](#systemcollectionsgeneric-namespace) +- [System.Collections.Specialized namespace](#systemcollectionsspecialized-namespace) +- [System.ComponentModel namespace](#systemcomponentmodel-namespace) +- [System.ComponentModel.Composition namespace](#systemcomponentmodelcomposition-namespace) +- [System.ComponentModel.Composition.Primitives namespace](#systemcomponentmodelcompositionprimitives-namespace) +- [System.ComponentModel.DataAnnotations namespace](#systemcomponentmodeldataannotations-namespace) +- [System.ComponentModel.Design namespace](#systemcomponentmodeldesign-namespace) +- [System.Configuration namespace](#systemconfiguration-namespace) +- [System.Data namespace](#systemdata-namespace) +- [System.Data.Common namespace](#systemdatacommon-namespace) +- [System.Data.Odbc namespace](#systemdataodbc-namespace) +- [System.Data.OleDb namespace](#systemdataoledb-namespace) +- [System.Data.SqlTypes namespace](#systemdatasqltypes-namespace) +- [System.Diagnostics.Eventing.Reader namespace](#systemdiagnosticseventingreader-namespace) +- [System.Diagnostics.Tracing namespace](#systemdiagnosticstracing-namespace) +- [System.DirectoryServices namespace](#systemdirectoryservices-namespace) +- [System.DirectoryServices.AccountManagement namespace](#systemdirectoryservicesaccountmanagement-namespace) +- [System.DirectoryServices.ActiveDirectory namespace](#systemdirectoryservicesactivedirectory-namespace) +- [System.DirectoryServices.Protocols namespace](#systemdirectoryservicesprotocols-namespace) +- [System.Formats.Asn1 namespace](#systemformatsasn1-namespace) +- [System.Formats.Cbor namespace](#systemformatscbor-namespace) +- [System.Globalization namespace](#systemglobalization-namespace) +- [System.IO namespace](#systemio-namespace) +- [System.Management namespace](#systemmanagement-namespace) +- [System.Media namespace](#systemmedia-namespace) +- [System.Net namespace](#systemnet-namespace) +- [System.Net.Mail namespace](#systemnetmail-namespace) +- [System.Net.NetworkInformation namespace](#systemnetnetworkinformation-namespace) +- [System.Net.Sockets namespace](#systemnetsockets-namespace) +- [System.Reflection namespace](#systemreflection-namespace) +- [System.Reflection.Metadata namespace](#systemreflectionmetadata-namespace) +- [System.Resources namespace](#systemresources-namespace) +- [System.Runtime.CompilerServices namespace](#systemruntimecompilerservices-namespace) +- [System.Runtime.InteropServices namespace](#systemruntimeinteropservices-namespace) +- [System.Runtime.Serialization namespace](#systemruntimeserialization-namespace) +- [System.Security namespace](#systemsecurity-namespace) +- [System.Security.AccessControl namespace](#systemsecurityaccesscontrol-namespace) +- [System.Security.Authentication namespace](#systemsecurityauthentication-namespace) +- [System.Security.Claims namespace](#systemsecurityclaims-namespace) +- [System.Security.Cryptography namespace](#systemsecuritycryptography-namespace) +- [System.Security.Policy namespace](#systemsecuritypolicy-namespace) +- [System.Security.Principal namespace](#systemsecurityprincipal-namespace) +- [System.Text.Json namespace](#systemtextjson-namespace) +- [System.Text.RegularExpressions namespace](#systemtextregularexpressions-namespace) +- [System.Threading namespace](#systemthreading-namespace) +- [System.Threading.Channels namespace](#systemthreadingchannels-namespace) +- [System.Threading.Tasks namespace](#systemthreadingtasks-namespace) +- [System.Transactions namespace](#systemtransactions-namespace) +- [System.Xml namespace](#systemxml-namespace) +- [System.Xml.Schema namespace](#systemxmlschema-namespace) +- [System.Xml.XPath namespace](#systemxmlxpath-namespace) +- [System.Xml.Xsl namespace](#systemxmlxsl-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 diff --git a/docs/fundamentals/syslib-diagnostics/syslib0051.md b/docs/fundamentals/syslib-diagnostics/syslib0051.md index d926d43e13b0d..3b6e7fc4a8356 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0051.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0051.md @@ -7,305 +7,11 @@ ms.date: 05/05/2023 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)`. -- All implicit implementations of the method. -- All implicit implementations of the method. +- 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, . -The complete list of affected APIs is: - -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +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 From 5d9f02fb1607e5609f1ba27f7089dc145ba4ff09 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 11 May 2023 08:35:47 -0700 Subject: [PATCH 14/16] move workaround from 50 to 51 --- .../syslib-diagnostics/syslib0050.md | 88 +------------------ .../syslib-diagnostics/syslib0051.md | 88 ++++++++++++++++++- 2 files changed, 87 insertions(+), 89 deletions(-) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0050.md b/docs/fundamentals/syslib-diagnostics/syslib0050.md index 84d2a55711663..f47e9568c0315 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0050.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0050.md @@ -1,7 +1,7 @@ --- 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/05/2023 +ms.date: 05/11/2023 --- # SYSLIB0050: Formatter-based serialization is obsolete @@ -49,92 +49,6 @@ The following APIs are obsolete, starting in .NET 8. Calling them in code genera #endif ``` - - -- 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'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. diff --git a/docs/fundamentals/syslib-diagnostics/syslib0051.md b/docs/fundamentals/syslib-diagnostics/syslib0051.md index 3b6e7fc4a8356..e51ec1de5512b 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0051.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0051.md @@ -1,7 +1,7 @@ --- 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/05/2023 +ms.date: 05/11/2023 --- # SYSLIB0051: Legacy serialization support APIs are obsolete @@ -15,7 +15,91 @@ For a complete list of affected APIs, see [Obsolete APIs - SYSLIB0051](../../cor ## Workaround -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 for SYSLIB0050](syslib0050.md#custom-exception). +- 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. From dc5e2cfbc9d99770d9c41e83a4885ebbe4bd678a Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 11 May 2023 08:38:58 -0700 Subject: [PATCH 15/16] clarify which overloads are affected --- .../serialization/8.0/binaryformatter-disabled.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/serialization/8.0/binaryformatter-disabled.md b/docs/core/compatibility/serialization/8.0/binaryformatter-disabled.md index 60e37505ef951..3561b322370a5 100644 --- a/docs/core/compatibility/serialization/8.0/binaryformatter-disabled.md +++ b/docs/core/compatibility/serialization/8.0/binaryformatter-disabled.md @@ -5,11 +5,11 @@ ms.date: 05/01/2023 --- # BinaryFormatter disabled across most project types -The and methods now through a at run time across nearly all project types, including console applications. +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. +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 From c9d542896181192f7e18da22945a9e725bbc2305 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 11 May 2023 15:51:33 -0700 Subject: [PATCH 16/16] remove index --- .../obsolete-apis-with-custom-diagnostics.md | 59 +------------------ 1 file changed, 1 insertion(+), 58 deletions(-) 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 index 88bf762829dfb..f3502be418b65 100644 --- 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 @@ -74,64 +74,7 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c ### SYSLIB0051 -Use the following index to see `SYSLIB0051` API obsoletions by namespace: - -- [Microsoft.CSharp.RuntimeBinder namespace](#microsoftcsharpruntimebinder-namespace) -- [Microsoft.VisualBasic.FileIO namespace](#microsoftvisualbasicfileio-namespace) -- [System namespace](#system-namespace) -- [System.Collections namespace](#systemcollections-namespace) -- [System.Collections.Generic namespace](#systemcollectionsgeneric-namespace) -- [System.Collections.Specialized namespace](#systemcollectionsspecialized-namespace) -- [System.ComponentModel namespace](#systemcomponentmodel-namespace) -- [System.ComponentModel.Composition namespace](#systemcomponentmodelcomposition-namespace) -- [System.ComponentModel.Composition.Primitives namespace](#systemcomponentmodelcompositionprimitives-namespace) -- [System.ComponentModel.DataAnnotations namespace](#systemcomponentmodeldataannotations-namespace) -- [System.ComponentModel.Design namespace](#systemcomponentmodeldesign-namespace) -- [System.Configuration namespace](#systemconfiguration-namespace) -- [System.Data namespace](#systemdata-namespace) -- [System.Data.Common namespace](#systemdatacommon-namespace) -- [System.Data.Odbc namespace](#systemdataodbc-namespace) -- [System.Data.OleDb namespace](#systemdataoledb-namespace) -- [System.Data.SqlTypes namespace](#systemdatasqltypes-namespace) -- [System.Diagnostics.Eventing.Reader namespace](#systemdiagnosticseventingreader-namespace) -- [System.Diagnostics.Tracing namespace](#systemdiagnosticstracing-namespace) -- [System.DirectoryServices namespace](#systemdirectoryservices-namespace) -- [System.DirectoryServices.AccountManagement namespace](#systemdirectoryservicesaccountmanagement-namespace) -- [System.DirectoryServices.ActiveDirectory namespace](#systemdirectoryservicesactivedirectory-namespace) -- [System.DirectoryServices.Protocols namespace](#systemdirectoryservicesprotocols-namespace) -- [System.Formats.Asn1 namespace](#systemformatsasn1-namespace) -- [System.Formats.Cbor namespace](#systemformatscbor-namespace) -- [System.Globalization namespace](#systemglobalization-namespace) -- [System.IO namespace](#systemio-namespace) -- [System.Management namespace](#systemmanagement-namespace) -- [System.Media namespace](#systemmedia-namespace) -- [System.Net namespace](#systemnet-namespace) -- [System.Net.Mail namespace](#systemnetmail-namespace) -- [System.Net.NetworkInformation namespace](#systemnetnetworkinformation-namespace) -- [System.Net.Sockets namespace](#systemnetsockets-namespace) -- [System.Reflection namespace](#systemreflection-namespace) -- [System.Reflection.Metadata namespace](#systemreflectionmetadata-namespace) -- [System.Resources namespace](#systemresources-namespace) -- [System.Runtime.CompilerServices namespace](#systemruntimecompilerservices-namespace) -- [System.Runtime.InteropServices namespace](#systemruntimeinteropservices-namespace) -- [System.Runtime.Serialization namespace](#systemruntimeserialization-namespace) -- [System.Security namespace](#systemsecurity-namespace) -- [System.Security.AccessControl namespace](#systemsecurityaccesscontrol-namespace) -- [System.Security.Authentication namespace](#systemsecurityauthentication-namespace) -- [System.Security.Claims namespace](#systemsecurityclaims-namespace) -- [System.Security.Cryptography namespace](#systemsecuritycryptography-namespace) -- [System.Security.Policy namespace](#systemsecuritypolicy-namespace) -- [System.Security.Principal namespace](#systemsecurityprincipal-namespace) -- [System.Text.Json namespace](#systemtextjson-namespace) -- [System.Text.RegularExpressions namespace](#systemtextregularexpressions-namespace) -- [System.Threading namespace](#systemthreading-namespace) -- [System.Threading.Channels namespace](#systemthreadingchannels-namespace) -- [System.Threading.Tasks namespace](#systemthreadingtasks-namespace) -- [System.Transactions namespace](#systemtransactions-namespace) -- [System.Xml namespace](#systemxml-namespace) -- [System.Xml.Schema namespace](#systemxmlschema-namespace) -- [System.Xml.XPath namespace](#systemxmlxpath-namespace) -- [System.Xml.Xsl namespace](#systemxmlxsl-namespace) +The `SYSLIB0051` API obsoletions are organized here by namespace. #### Microsoft.CSharp.RuntimeBinder namespace