From f67219876771f0f4f0f66963cc263d1453360ef1 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Fri, 6 May 2022 11:31:43 -0500 Subject: [PATCH 1/7] add docs for MSBuild breaking change around serialization of certain custom types --- docs/core/compatibility/7.0.md | 3 +- .../sdk/7.0/custom-serialization.md | 32 +++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 docs/core/compatibility/sdk/7.0/custom-serialization.md diff --git a/docs/core/compatibility/7.0.md b/docs/core/compatibility/7.0.md index 90713ef94ba11..cbdee353e12a0 100644 --- a/docs/core/compatibility/7.0.md +++ b/docs/core/compatibility/7.0.md @@ -47,11 +47,12 @@ If you're migrating an app to .NET 7, the breaking changes listed here might aff | [AllowRenegotiation default is false](networking/7.0/allowrenegotiation-default.md) | ❌ | ❌ | Preview 3 | | [Custom ping payloads on Linux](networking/7.0/ping-custom-payload-linux.md) | ❌ | ✔️ | Preview 2 | -## SDK +## SDK and MSBuild | Title | Binary compatible | Source compatible | Introduced | | - | :-: | :-: | - | | [Version requirements for .NET 7 SDK](sdk/7.0/vs-msbuild-version.md) | ✔️ | ✔️ | 7.0.100 | +| [MSBuild serialization of custom types in .NET 7](sdk/7.0/custom-serialization.md) | ❌ | ❌ | 7.0.100 | ## Serialization diff --git a/docs/core/compatibility/sdk/7.0/custom-serialization.md b/docs/core/compatibility/sdk/7.0/custom-serialization.md new file mode 100644 index 0000000000000..f0fef40ab85ed --- /dev/null +++ b/docs/core/compatibility/sdk/7.0/custom-serialization.md @@ -0,0 +1,32 @@ +--- +title: "Breaking change: Serialization of custom types in .NET 7" +description: Learn about a breaking change in MSBuild for .NET 7 where serialization using BinaryFormatter of certain user-defined types is removed. +author: baronfel +ms.date: 05/06/2022 +--- + +# BinaryFormatter serialization of custom BuildEventArgs and ITaskItems removed for .NET 7 + +MSBuild in .NET 7 doesn't support serialization of custom BuildEventArgs and ITaskItems via the BinaryFormatter serializer. + +## Version Introduced + +MSBuild 17.4 (.NET SDK 7.0.100) + +## Old Behavior + +MSBuild used BinaryFormatter via the `TranslateDotNet` method to translate custom BuildEventArgs and ITaskItems that users could define in their own Tasks. + +## New Behavior + +MSBuild will no longer support this mechanism, so code that used `TranslateDotNet` will fail to compile. + +## Reason for change + +BinaryFormatter was [obsoleted in .NET 5](https://github.com/dotnet/designs/blob/main/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md). Per this plan, all first-party dotnet org code bases must migrate away from its use by .NET 7. This change specifically impacts user-exposed functionality of MSBuild, which is why this breaking change notice is separate from the original deprecation notice. + +## Recommended action + +* Engage with the MSBuild team on [this GitHub discussion](https://github.com/dotnet/msbuild/discussions/7582) about your specific use cases and how you can migrate away from the `TranslateDotNet` mechanism. + +* Update your Tasks to use a different serialization mechanism. From 013d96fb0d76cfa94e45273a460c21f47419d557 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Fri, 6 May 2022 15:12:55 -0500 Subject: [PATCH 2/7] Apply uncontroversial suggestions from code review Co-authored-by: Rainer Sigwald Co-authored-by: Forgind --- docs/core/compatibility/sdk/7.0/custom-serialization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/sdk/7.0/custom-serialization.md b/docs/core/compatibility/sdk/7.0/custom-serialization.md index f0fef40ab85ed..93d847a26f3c6 100644 --- a/docs/core/compatibility/sdk/7.0/custom-serialization.md +++ b/docs/core/compatibility/sdk/7.0/custom-serialization.md @@ -7,7 +7,7 @@ ms.date: 05/06/2022 # BinaryFormatter serialization of custom BuildEventArgs and ITaskItems removed for .NET 7 -MSBuild in .NET 7 doesn't support serialization of custom BuildEventArgs and ITaskItems via the BinaryFormatter serializer. +MSBuild in .NET 7 doesn't support serialization of custom `BuildEventArgs`- and `ITaskItem`-derived types via the BinaryFormatter serializer. ## Version Introduced @@ -23,10 +23,10 @@ MSBuild will no longer support this mechanism, so code that used `TranslateDotNe ## Reason for change -BinaryFormatter was [obsoleted in .NET 5](https://github.com/dotnet/designs/blob/main/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md). Per this plan, all first-party dotnet org code bases must migrate away from its use by .NET 7. This change specifically impacts user-exposed functionality of MSBuild, which is why this breaking change notice is separate from the original deprecation notice. +BinaryFormatter was [made obsolete in .NET 5](https://github.com/dotnet/designs/blob/main/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md). Per this plan, all first-party code in the dotnet org must migrate away from its use by .NET 7. This change impacts user-exposed functionality of MSBuild. ## Recommended action * Engage with the MSBuild team on [this GitHub discussion](https://github.com/dotnet/msbuild/discussions/7582) about your specific use cases and how you can migrate away from the `TranslateDotNet` mechanism. -* Update your Tasks to use a different serialization mechanism. +* Avoid returning custom derived types from tasks or when logging. From a79f00e5eb21c0df0404ac601a37d5d9e366cec4 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Fri, 6 May 2022 16:11:59 -0500 Subject: [PATCH 3/7] add TOC sections --- docs/core/compatibility/toc.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index d47aecf4d2088..c86c065a527d0 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -61,10 +61,12 @@ items: href: networking/7.0/allowrenegotiation-default.md - name: Custom ping payloads on Linux href: networking/7.0/ping-custom-payload-linux.md - - name: SDK + - name: SDK and MSBuild items: - name: Version requirements for .NET 7 SDK href: sdk/7.0/vs-msbuild-version.md + - name: Serialization of custom types in .NET 7 + href: sdk/7.0/custom-serialization.md - name: Serialization items: - name: Deserialize Version type with leading or trailing whitespace @@ -965,6 +967,8 @@ items: items: - name: Version requirements for .NET 7 SDK href: sdk/7.0/vs-msbuild-version.md + - name: Serialization of custom types in .NET 7 + href: sdk/7.0/custom-serialization.md - name: .NET 6 items: - name: -p option for `dotnet run` is deprecated From e3e5936228fcfc2524fea7df1e1d174a7a0e563a Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Fri, 6 May 2022 16:12:50 -0500 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/sdk/7.0/custom-serialization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/compatibility/sdk/7.0/custom-serialization.md b/docs/core/compatibility/sdk/7.0/custom-serialization.md index 93d847a26f3c6..13eff40e8078b 100644 --- a/docs/core/compatibility/sdk/7.0/custom-serialization.md +++ b/docs/core/compatibility/sdk/7.0/custom-serialization.md @@ -7,13 +7,13 @@ ms.date: 05/06/2022 # BinaryFormatter serialization of custom BuildEventArgs and ITaskItems removed for .NET 7 -MSBuild in .NET 7 doesn't support serialization of custom `BuildEventArgs`- and `ITaskItem`-derived types via the BinaryFormatter serializer. +MSBuild in .NET 7 doesn't support serialization of custom `BuildEventArgs`-derived and `ITaskItem`-derived types via the `BinaryFormatter` serializer. -## Version Introduced +## Version introduced MSBuild 17.4 (.NET SDK 7.0.100) -## Old Behavior +## Old behavior MSBuild used BinaryFormatter via the `TranslateDotNet` method to translate custom BuildEventArgs and ITaskItems that users could define in their own Tasks. @@ -23,7 +23,7 @@ MSBuild will no longer support this mechanism, so code that used `TranslateDotNe ## Reason for change -BinaryFormatter was [made obsolete in .NET 5](https://github.com/dotnet/designs/blob/main/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md). Per this plan, all first-party code in the dotnet org must migrate away from its use by .NET 7. This change impacts user-exposed functionality of MSBuild. +BinaryFormatter was [made obsolete in .NET 5](https://github.com/dotnet/designs/blob/main/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md). Per this plan, all first-party code in the dotnet GitHub organization must migrate away from its use by .NET 7. This change impacts user-exposed functionality of MSBuild. ## Recommended action From 7f20574d2c3edcdc28f8804013e55b84b6d84f3c Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Fri, 6 May 2022 16:25:21 -0500 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/sdk/7.0/custom-serialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/sdk/7.0/custom-serialization.md b/docs/core/compatibility/sdk/7.0/custom-serialization.md index 13eff40e8078b..cbe48dec7a744 100644 --- a/docs/core/compatibility/sdk/7.0/custom-serialization.md +++ b/docs/core/compatibility/sdk/7.0/custom-serialization.md @@ -17,7 +17,7 @@ MSBuild 17.4 (.NET SDK 7.0.100) MSBuild used BinaryFormatter via the `TranslateDotNet` method to translate custom BuildEventArgs and ITaskItems that users could define in their own Tasks. -## New Behavior +## New behavior MSBuild will no longer support this mechanism, so code that used `TranslateDotNet` will fail to compile. From 5fd434c872c9204059a082c6d85de07185c4e68d Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Mon, 9 May 2022 09:44:31 -0500 Subject: [PATCH 6/7] Update custom-serialization.md --- docs/core/compatibility/sdk/7.0/custom-serialization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/sdk/7.0/custom-serialization.md b/docs/core/compatibility/sdk/7.0/custom-serialization.md index cbe48dec7a744..9d32fa4cfe08e 100644 --- a/docs/core/compatibility/sdk/7.0/custom-serialization.md +++ b/docs/core/compatibility/sdk/7.0/custom-serialization.md @@ -15,11 +15,11 @@ MSBuild 17.4 (.NET SDK 7.0.100) ## Old behavior -MSBuild used BinaryFormatter via the `TranslateDotNet` method to translate custom BuildEventArgs and ITaskItems that users could define in their own Tasks. +MSBuild used BinaryFormatter to preserve custom types that derived from BuildEventArgs and ITaskItem across certain boundaries, most notably when running in a multi-process environment. ## New behavior -MSBuild will no longer support this mechanism, so code that used `TranslateDotNet` will fail to compile. +MSBuild will no longer support this mechanism, so code that used custom types derived from BuildEventArgs and ITaskItem directly may fail unexpectedly. ## Reason for change From f29329cacf5d904641916cfc4dd417151ca3558a Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Mon, 9 May 2022 13:17:39 -0500 Subject: [PATCH 7/7] Update custom-serialization.md --- docs/core/compatibility/sdk/7.0/custom-serialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/sdk/7.0/custom-serialization.md b/docs/core/compatibility/sdk/7.0/custom-serialization.md index 9d32fa4cfe08e..52390cc8c62c3 100644 --- a/docs/core/compatibility/sdk/7.0/custom-serialization.md +++ b/docs/core/compatibility/sdk/7.0/custom-serialization.md @@ -19,7 +19,7 @@ MSBuild used BinaryFormatter to preserve custom types that derived from BuildEve ## New behavior -MSBuild will no longer support this mechanism, so code that used custom types derived from BuildEventArgs and ITaskItem directly may fail unexpectedly. +MSBuild will no longer support this mechanism, so code that used custom types derived from BuildEventArgs and ITaskItem may fail. ## Reason for change