diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md index 7385aef7b34c7..86c0f7a9dcb87 100644 --- a/docs/core/compatibility/9.0.md +++ b/docs/core/compatibility/9.0.md @@ -95,6 +95,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff | Title | Type of change | Introduced version | |-------------------------------------------------------------------------------|-------------------|--------------------| +| [`dotnet watch` incompatible with Hot Reload for old frameworks](sdk/9.0/dotnet-watch.md) | Behavioral change | RC 1 | | [`dotnet workload` commands output change](sdk/9.0/dotnet-workload-output.md) | Behavioral change | Preview 1 | | [`installer` repo version no longer documented](sdk/9.0/productcommits-versions.md) | Behavioral change | Preview 5 | | [Terminal logger is default](sdk/9.0/terminal-logger.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/sdk/9.0/dotnet-watch.md b/docs/core/compatibility/sdk/9.0/dotnet-watch.md new file mode 100644 index 0000000000000..8f1f00f85a5a2 --- /dev/null +++ b/docs/core/compatibility/sdk/9.0/dotnet-watch.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: 'dotnet watch' incompatible with Hot Reload for old frameworks" +description: Learn about a breaking change in the .NET 9 SDK where 'dotnet watch' requires disabling Hot Reload for projects targeting .NET 5 or earlier. +ms.date: 11/08/2024 +--- +# 'dotnet watch' incompatible with Hot Reload for old frameworks + +.NET 9 introduces a change that requires [`dotnet watch`](../../../tools/dotnet-watch.md) to launched with Hot Reload disabled for projects targeting .NET 5 or earlier versions. + +## Previous behavior + +Previously, [`dotnet watch`](../../../tools/dotnet-watch.md) automatically disabled Hot Reload when used with projects targeting .NET 5 or earlier. + +## New behavior + +Starting in .NET 9, an error is reported when [`dotnet watch`](../../../tools/dotnet-watch.md) is launched without `--no-hot-reload` for projects targeting .NET 5 or earlier versions. The error is similar to: + +> Hot Reload based watching is only supported in .NET 6.0 or newer apps. + +## Version introduced + +.NET 9 RC 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The internal architecture of the `dotnet watch` tool underwent significant improvements. Preserving behavior for out-of-support .NET versions did not warrant increasing the complexity of the new implementation. + +## Recommended action + +Pass `--no-hot-reload` to `dotnet watch` on the command line, or update your project to target `net6.0` or later (using the `TargetFramework` property). + +## Affected APIs + +N/A diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 9df880170194a..b24f1a6999c1f 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -94,6 +94,8 @@ items: href: networking/9.0/query-redaction-logs.md - name: SDK and MSBuild items: + - name: "`dotnet watch` incompatible with Hot Reload for old frameworks" + href: sdk/9.0/dotnet-watch.md - name: "'dotnet workload' commands output change" href: sdk/9.0/dotnet-workload-output.md - name: "'installer' repo version no longer documented" @@ -1770,6 +1772,8 @@ items: items: - name: .NET 9 items: + - name: "`dotnet watch` incompatible with Hot Reload for old frameworks" + href: sdk/9.0/dotnet-watch.md - name: "'dotnet workload' commands output change" href: sdk/9.0/dotnet-workload-output.md - name: "'installer' repo version no longer documented"