diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 58b9bb52cdf9d..5da70222b9009 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -82,12 +82,12 @@ { "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 + "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 + "redirect_document_id": true }, { "source_path_from_root": "/docs/core/compatibility/extensions/6.0/bind-single-elements-to-array.md", @@ -143,6 +143,10 @@ "source_path_from_root": "/docs/core/compatibility/sdk/6.0/implicit-namespaces-rc1.md", "redirect_url": "/dotnet/core/compatibility/6.0" }, + { + "source_path_from_root": "/docs/core/compatibility/sdk/8.0/tool-rollforward.md", + "redirect_url": "/dotnet/core/compatibility/8.0" + }, { "source_path_from_root": "/docs/core/compatibility/serialization.md", "redirect_url": "/dotnet/core/compatibility/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions" diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index 72a66290a2cfa..1d33abebe9202 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -111,16 +111,18 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff | Title | Type of change | Introduced | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------- | -| [.NET tool roll-forward behavior](sdk/8.0/tool-rollforward.md) | Behavioral change | Preview 5 | | [CLI console output uses UTF-8](sdk/8.0/console-encoding.md) | Behavioral change/Source and binary incompatible | Preview 1 | | [Console encoding not UTF-8 after completion](sdk/8.0/console-encoding-fix.md) | Behavioral change/Binary incompatible | Preview 3 | | [Containers default to use the 'latest' tag](sdk/8.0/default-image-tag.md) | Behavioral change | Preview 6 | | ['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 | +| [MSBuild custom derived build events deprecated](sdk/8.0/custombuildeventargs.md) | Behavioral change | RC 1 | | [MSBuild respects DOTNET_CLI_UI_LANGUAGE](sdk/8.0/msbuild-language.md) | Behavioral change | Preview 5 | | [Runtime-specific apps not self-contained](sdk/8.0/runtimespecific-app-default.md) | Source/binary incompatible | Preview 5 | | ['dotnet restore' produces security vulnerability warnings](sdk/8.0/dotnet-restore-audit.md) | Behavioral change | Preview 4 | +| [SDK uses a smaller RID graph](sdk/8.0/rid-graph.md) | Behavioral change/Source incompatible | RC 1 | | [Trimming may not be used with .NET Standard or .NET Framework](sdk/8.0/trimming-unsupported-targetframework.md) | Behavioral change | RC 1 | +| [Version requirements for .NET 8 SDK](sdk/8.0/version-requirements.md) | | RC 1 | ## Serialization diff --git a/docs/core/compatibility/deployment/8.0/rid-asset-list.md b/docs/core/compatibility/deployment/8.0/rid-asset-list.md index 9a8e6fd19d03b..228a4f9a6cbcc 100644 --- a/docs/core/compatibility/deployment/8.0/rid-asset-list.md +++ b/docs/core/compatibility/deployment/8.0/rid-asset-list.md @@ -5,7 +5,7 @@ ms.date: 06/07/2023 --- # Host determines RID-specific assets -When running an application with [RID](../../../rid-catalog.md)-specific assets, the host determines which assets are relevant for the platform on which it's running. This applies to both the application itself and the resolution logic used by . +When running an application with [runtime identifier (RID)](../../../rid-catalog.md) specific assets, the host determines what assets are relevant for the platform on which it's running. This applies to both the application itself and the resolution logic used by . Previously, the host tried to compute the RID at run time and then read the RID graph to determine which RID-specific assets matched or were compatible with the computed RID. Now, the default behavior doesn't compute the RID or use the RID graph. Instead, the host relies on a known list of RIDs based on how the runtime itself was built. @@ -74,3 +74,7 @@ If you need to revert to the previous behavior, set the backwards compatibility ## Affected APIs - + +## See also + +- [.NET SDK uses a smaller RID graph](../../sdk/8.0/rid-graph.md) diff --git a/docs/core/compatibility/sdk/8.0/custombuildeventargs.md b/docs/core/compatibility/sdk/8.0/custombuildeventargs.md new file mode 100644 index 0000000000000..f67246cfdaddb --- /dev/null +++ b/docs/core/compatibility/sdk/8.0/custombuildeventargs.md @@ -0,0 +1,47 @@ +--- +title: "Breaking change: MSBuild custom derived build events deprecated" +description: Learn about the breaking change in MSBuild where custom derived build events have been deprecated. +ms.date: 09/05/2023 +--- +# MSBuild custom derived build events deprecated + +Custom derived build events of any subclass of by any build extensibility (mainly custom tasks) have been deprecated. + +## Previous behavior + +Previously, you could derive from any subclass of and use those types freely in custom tasks and other build extensibility points. + +## New behavior + +Starting in .NET 8, a build error is issued if your code uses any type derived from and you build using the .NET 8 version of MSBuild, that is, from the command line: + +> Usage of unsecure BinaryFormatter during serialization of custom event type 'MyCustomBuildEventArgs'. This will be deprecated soon. Please use Extended*EventArgs instead. More info: + +If you build from Visual Studio, there is no change in behavior unless you opt in by setting the `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable to 1 (available in Visual Studio version 17.8 and later). + +## Version introduced + +.NET 8 RC 1 + +## Type of change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + + serialization is obsolete in .NET 8 and later versions. Any use of throws an exception at run time. Since MSBuild custom derived build events use , your build would crash if you use these events in your build. The new build error provides a more graceful failure. + +## Recommended action + +Use one of the following newly introduced, built-in events for extensibility instead of your custom derived build event: + +- `Microsoft.Build.Framework.ExtendedCustomBuildEventArgs` +- `Microsoft.Build.Framework.ExtendedBuildErrorEventArgs` +- `Microsoft.Build.Framework.ExtendedBuildMessageEventArgs` +- `Microsoft.Build.Framework.ExtendedBuildWarningEventArgs` + +Alternatively, you can temporarily disable the check by explicitly setting the environment variable `MSBUILDCUSTOMBUILDEVENTWARNING` to something other than 1. + +## Affected APIs + +- diff --git a/docs/core/compatibility/sdk/8.0/rid-graph.md b/docs/core/compatibility/sdk/8.0/rid-graph.md new file mode 100644 index 0000000000000..f9f9aabd00cc2 --- /dev/null +++ b/docs/core/compatibility/sdk/8.0/rid-graph.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: .NET SDK uses a smaller RID graph" +description: Learn about a breaking change in the .NET 8 SDK where the SDK uses a smaller, portable RID graph for projects that target .NET 8 or later. +ms.date: 09/05/2023 +--- +# .NET SDK uses a smaller RID graph + +Projects that target .NET 8 or later versions now use a smaller, "portable" runtime identifier (RID) graph. + +## Previous behavior + +The .NET SDK used a complex [RID graph](../../../rid-catalog.md) to determine assets when building or publishing a project. + +## New behavior + +Starting in .NET 8, the .NET SDK uses a smaller graph consisting of only portable RIDs, for projects that target .NET 8 or a later version. This means that the SDK won't recognize version-specific or distro-specific RIDs by default. + +## Version introduced + +.NET 8 RC 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change) and can also affect [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +The RID graph was costly to maintain and understand, requiring .NET itself to be distro-aware in a fragile manner. The .NET team and the community spend a non-trivial amount of time updating the graph and backporting such updates to previous releases. The long-term goal is to stop updating the RID graph, stop reading it, and eventually remove it. This breaking change is a step towards that goal. + +## Recommended action + +Use portable RIDs, for example, `linux-`, `linux-musl-`, `osx-`, and `win-`. + +If you need to revert to the previous behavior of using the old, full RID graph, you can set the `UseRidGraph` MSBuild property to `true` in your project file. However, the old RID graph won't be updated in the future to attempt to handle any other distros or architectures. + +## See also + +- [Host determines RID-specific assets](../../deployment/8.0/rid-asset-list.md) diff --git a/docs/core/compatibility/sdk/8.0/tool-rollforward.md b/docs/core/compatibility/sdk/8.0/tool-rollforward.md deleted file mode 100644 index 7904e82f3dac6..0000000000000 --- a/docs/core/compatibility/sdk/8.0/tool-rollforward.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Breaking change: .NET tool roll-forward behavior" -description: Learn about a breaking change in the .NET 8 SDK where the default roll-forward behavior for .NET tools changed from 'latestPatch' to 'major'. -ms.date: 06/06/2023 ---- -# .NET tool roll-forward behavior - -We changed the default [roll-forward behavior](../../../tools/global-json.md#rollforward) for [.NET tools](../../../tools/global-tools.md) from `latestPatch` to `major`. - -## Previous behavior - -Previously, .NET tools had the same default roll-forward behavior as all other .NET apps, which is `latestPatch`. `latestPatch` allows an application to run on any runtime of the same major and minor version that's at least as high as the version that the application was built against. - -## New behavior - -Starting in .NET 8, .NET tools have a default roll-forward behavior of `major`. This change allows .NET tools to run on any .NET runtime version that's greater than or equal to the version the app was built against, including a higher major version. This change only affects tools that are rebuilt in .NET 8. - -## Version introduced - -.NET 8 Preview 5 - -## Type of breaking change - -This change is a [behavioral change](../../categories.md#behavioral-change). - -## Reason for change - -A .NET (local) tool is a specific kind of .NET application that's intended to be distributed and managed via SDK commands. .NET tools are usually development tools and utilities. The semantics of tools are such that tools should be able to run on *any* .NET runtime equal to or greater than the runtime the application originally targeted. Previously, tool authors had to either explicitly set a more flexible roll-forward policy or target multiple versions, such as .NET 6 and .NET 7. - -## Recommended action - -If this change is undesirable, you can explicitly set the roll-forward policy to `latestPatch` in the `RollForward` MSBuild property or the `rollForward` property of the runtime configuration file. - -## See also - -- [rollForward](https://github.com/dotnet/designs/blob/main/accepted/2019/runtime-binding.md#rollforward) diff --git a/docs/core/compatibility/sdk/8.0/trimming-unsupported-targetframework.md b/docs/core/compatibility/sdk/8.0/trimming-unsupported-targetframework.md index 0262dc0d597b9..66d1583599b43 100644 --- a/docs/core/compatibility/sdk/8.0/trimming-unsupported-targetframework.md +++ b/docs/core/compatibility/sdk/8.0/trimming-unsupported-targetframework.md @@ -3,7 +3,7 @@ title: "Breaking change: Trimming may not be used with .NET Standard or .NET Fra description: Learn about a breaking change in the .NET 8 SDK where trimming settings produce new warnings or errors in .NET Standard or .NET Framework projects. ms.date: 08/21/2023 --- -# Trimming may not be used with .NET standard or .NET framework +# Trimming may not be used with .NET Standard or .NET Framework Projects that set `true`, `true` or `true` with a `TargetFramework` that is any version of .NET Standard or .NET Framework produce a warning or error because trimming is unsupported for these target frameworks. @@ -11,16 +11,16 @@ Projects that set `true`, `truetrue` would have no effect. -- `true` would embed an assembly-level attribute `[assembly: AssemblyMetadata("IsTrimmable", "true")]` into the output assembly. That attribute opted the assembly into trimming when consumed in a trimmed app (even an app that uses `partial`). -- `true` would enable trim analysis for the library, using the .NET Standard or .NET Framework reference assemblies corresponding to the library's `TargetFramework` even though these reference assemblies aren't annotated for trimming. +- `true` had no effect. +- `true` embedded an assembly-level attribute `[assembly: AssemblyMetadata("IsTrimmable", "true")]` into the output assembly. That attribute opted the assembly into trimming when consumed in a trimmed app (even an app that uses `partial`). +- `true` enabled trim analysis for the library, using the .NET Standard or .NET Framework reference assemblies corresponding to the library's `TargetFramework` even though these reference assemblies aren't annotated for trimming. ## New behavior Starting in the .NET 8 SDK, in a project targeting .NET Standard or .NET Framework: - `` produces an error indicating that this setting is unsupported for the target framework. -- `` or `` produce a warning indicating that `` is unsupported for the target framework. These settings otherwise have no effect on the build output. +- `` and `` produce a warning indicating that `` is unsupported for the target framework. These settings otherwise have no effect on the build output. ## Version introduced diff --git a/docs/core/compatibility/sdk/8.0/version-requirements.md b/docs/core/compatibility/sdk/8.0/version-requirements.md new file mode 100644 index 0000000000000..b3b3108e98a96 --- /dev/null +++ b/docs/core/compatibility/sdk/8.0/version-requirements.md @@ -0,0 +1,36 @@ +--- +title: "Breaking change: Version requirements for .NET 8 SDK" +description: Learn about the breaking change in the .NET 8 SDK where specific versions of Visual Studio and MSBuild are required. +ms.date: 09/05/2023 +--- +# Version requirements for .NET 8 SDK + +Per the [published support rules](../../../porting/versioning-sdk-msbuild-vs.md#targeting-and-support-rules), we update the minimum Visual Studio and MSBuild version for each new major release with a one quarter delay. For the .NET 8 release, 8.0.100 requires version 17.7 to be loaded but only supports targeting .NET 7 in that version. To target `net8.0`, you must use version 17.8 or later. + +## Version introduced + +.NET SDK 8 RC 1 + +## Previous behavior + +.NET 8.0.1xx-preview1 required version 17.4 of Visual Studio and MSBuild. .NET 8.0.1xx-preview4 required version 17.6 of Visual Studio and MSBuild. + +## New behavior + +Versions 8.0.1xx of the .NET SDK require Visual Studio version 17.7 and MSBuild version 17.7. + +## Reason for change + +This is our standard support policy for the SDK as we can't support all prior versions of Visual Studio and MSBuild. + +## Recommended action + +Upgrade your Visual Studio version to the required version. + +## Affected APIs + +N/A + +## See also + +- [Targeting and support rules](../../../porting/versioning-sdk-msbuild-vs.md#targeting-and-support-rules) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 8c70a56060280..24cb3a58f7439 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -116,8 +116,6 @@ items: href: reflection/8.0/function-pointer-reflection.md - name: SDK and MSBuild items: - - name: .NET tool roll-forward behavior - href: sdk/8.0/tool-rollforward.md - name: CLI console output uses UTF-8 href: sdk/8.0/console-encoding.md - name: Console encoding not UTF-8 after completion @@ -130,12 +128,18 @@ items: href: sdk/8.0/dotnet-publish-config.md - name: "'dotnet restore' produces security vulnerability warnings" href: sdk/8.0/dotnet-restore-audit.md + - name: MSBuild custom derived build events deprecated + href: sdk/8.0/custombuildeventargs.md - name: MSBuild respects DOTNET_CLI_UI_LANGUAGE href: sdk/8.0/msbuild-language.md - name: Runtime-specific apps not self-contained href: sdk/8.0/runtimespecific-app-default.md + - name: SDK uses a smaller RID graph + href: sdk/8.0/rid-graph.md - name: Trimming may not be used with .NET Standard or .NET Framework href: sdk/8.0/trimming-unsupported-targetframework.md + - name: Version requirements for .NET 8 SDK + href: sdk/8.0/version-requirements.md - name: Serialization items: - name: BinaryFormatter disabled for most projects @@ -1464,8 +1468,6 @@ items: items: - name: .NET 8 items: - - name: .NET tool roll-forward behavior - href: sdk/8.0/tool-rollforward.md - name: CLI console output uses UTF-8 href: sdk/8.0/console-encoding.md - name: Console encoding not UTF-8 after completion @@ -1478,12 +1480,18 @@ items: href: sdk/8.0/dotnet-publish-config.md - name: "'dotnet restore' produces security vulnerability warnings" href: sdk/8.0/dotnet-restore-audit.md + - name: MSBuild custom derived build events deprecated + href: sdk/8.0/custombuildeventargs.md - name: MSBuild respects DOTNET_CLI_UI_LANGUAGE href: sdk/8.0/msbuild-language.md - name: Runtime-specific apps not self-contained href: sdk/8.0/runtimespecific-app-default.md + - name: SDK uses a smaller RID graph + href: sdk/8.0/rid-graph.md - name: Trimming may not be usedwith .NET Standard or .NET Framework href: sdk/8.0/trimming-unsupported-targetframework.md + - name: Version requirements for .NET 8 SDK + href: sdk/8.0/version-requirements.md - name: .NET 7 items: - name: Automatic RuntimeIdentifier for certain projects diff --git a/docs/whats-new/dotnet-docs-mod0.md b/docs/whats-new/dotnet-docs-mod0.md index 79e2221e39350..4d8ef783421aa 100644 --- a/docs/whats-new/dotnet-docs-mod0.md +++ b/docs/whats-new/dotnet-docs-mod0.md @@ -18,7 +18,6 @@ Welcome to what's new in the .NET docs for June 2023. This article lists some of - [Base64.DecodeFromUtf8 methods ignore whitespace](../core/compatibility/core-libraries/8.0/decodefromutf8-whitespace.md) - [Host determines RID-specific assets](../core/compatibility/deployment/8.0/rid-asset-list.md) - [MSBuild respects DOTNET_CLI_UI_LANGUAGE](../core/compatibility/sdk/8.0/msbuild-language.md) -- [.NET tool roll-forward behavior](../core/compatibility/sdk/8.0/tool-rollforward.md) - [SafeHandle types must have public constructor](../core/compatibility/interop/8.0/safehandle-constructor.md) - [IndexOfAnyValues renamed to SearchValues](../core/compatibility/core-libraries/8.0/indexofanyvalues-renamed.md) - [Runtime-specific apps no longer self-contained](../core/compatibility/sdk/8.0/runtimespecific-app-default.md)