From 26aa4e37386a63ee9af9ab9ec1c2ef58dc660d4d Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 9 Mar 2023 20:20:40 -0800 Subject: [PATCH 1/3] preview 2 breaking change --- docs/core/compatibility/8.0.md | 1 + .../sdk/8.0/runtimespecific-app-default.md | 63 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ 3 files changed, 68 insertions(+) create mode 100644 docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index 1f1264e300ee4..f646417ed6430 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -55,6 +55,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff | [CLI console output uses UTF-8](sdk/8.0/console-encoding.md) | Behavioral change/Source and binary incompatible | Preview 1 | | ['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 | +| [Runtime-specific apps no longer self-contained](sdk/8.0/runtimespecific-app-default.md) | Source/binary incompatible | Preview 2 | ## Windows Forms diff --git a/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md new file mode 100644 index 0000000000000..bfd82859a8627 --- /dev/null +++ b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md @@ -0,0 +1,63 @@ +--- +title: "Breaking change: Runtime-specific apps no longer self-contained" +description: Learn about a breaking change in the .NET 8 SDK where apps that specify a runtime identifier are no longer self-contained by default. +ms.date: 03/09/2023 +--- +# Runtime-specific apps no longer self-contained + +Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#publish-self-contained) by default, and instead [framework-dependent](../../../deploying/index.md#publish-framework-dependent) by default. + +This is a break in the following situations: + +- If you deployed, distributed, or published your app and didn't explicitly add the `SelfContained` property, but also didn't require that the .NET runtime be installed on the machine for it to work. In this case, you may have relied on the previous behavior to produce a non-framework-dependent app by default. + +- If you relied on the IL Link tool. In this case, you'll have to take the steps described under [Recommended action](#recommended-action) to use IL Link again. + + > [!NOTE] + > Some publish properties, like `PublishTrimmed`, `PublishSingleFile`, and `PublishAot`, currently require `SelfContained` to work. If you use these properties, you'll need to add the `SelfContained` property. + +- For Blazor WASM apps, because they relied on the previous behavior. However, the Blazor WASM team may side-step this breaking change in their SDK by adding `SelfContained` automatically for all apps, so Blazor customers shouldn't be affected. + +## Previous behavior + +Previously, if a runtime identifier (RID) was specified (via [RuntimeIdentifier](../../../project-sdk/msbuild-props.md#runtimeidentifier)), the app was published as self-contained, even if `SelfContained` wasn't explicitly specified. + +## New behavior + +Starting in .NET 8, for apps that target .NET 8 or a later version, `RuntimeIdentifier` no longer implies `SelfContained` by default. Instead, apps that specify a runtime identifier will be dependent on the .NET runtime by default (framework-dependent). Apps that target .NET 7 or earlier versions aren't affected. + +## Version introduced + +.NET 8 Preview 2 + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility) and [binary compatibility](../../categories.md#binary-compatibility). + +## Reason for change + +.NET 6 alerted users to this breaking change with the following warning: + +**warning NETSDK1179: One of '--self-contained' or '--no-self-contained' options are required when '--runtime' is used.** + +Now that customers have had time to add `SelfContained` explicitly, we felt we could introduce the break. + +As for why the change is being made: + +- The new .NET SDK behavior aligns with Visual Studio behavior. +- Framework-dependent apps are now smaller by default, since there aren't copies of .NET stored in each app. +- Ideally, command-line options are orthogonal. In this case, the tooling supports both RID-specific self-contained deployment (SCD) and RID-specific framework-dependent deployment (FDD). So it didn't make sense that no RID defaulted to FDD and RID defaulted to SCD. This behavior was often confusing for users. + +## Recommended action + +If you're using .NET 7 or an earlier version and relied on the previous behavior where `SelfContained` was inferred, you'll see this warning: + +**For projects with TargetFrameworks >= 8.0, RuntimeIdentifier no longer automatically gives a SelfContained app. To continue creating a .NET framework independent app after upgrading to 8.0, consider setting SelfContained explicitly.** + +Follow the guidance of the warning if you want to continue to produce self-contained apps. If you want to move to the new default, set `SelfContained` to `false` in the project file (`false`) or as a command-line argument, for example, `dotnet publish --no-self-contained`. + +If you're using .NET 8, you don't need to do anything unless you want to keep the previous behavior. In that case, set `SelfContained` to `true`. + +## See also + +- [.NET application publishing overview](../../../deploying/index.md) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index ea68ad183f713..433ff40c62da5 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -50,6 +50,8 @@ items: href: sdk/8.0/dotnet-pack-config.md - name: "'dotnet publish' uses Release configuration" href: sdk/8.0/dotnet-publish-config.md + - name: Runtime-specific apps no longer self-contained + href: sdk/8.0/runtimespecific-app-default.md - name: Windows Forms items: - name: Anchor layout changes @@ -1282,6 +1284,8 @@ items: href: sdk/8.0/dotnet-pack-config.md - name: "'dotnet publish' uses Release configuration" href: sdk/8.0/dotnet-publish-config.md + - name: Runtime-specific apps no longer self-contained + href: sdk/8.0/runtimespecific-app-default.md - name: .NET 7 items: - name: Automatic RuntimeIdentifier for certain projects From 000abc745d9af869151bf55530c08c71f1dcd0de Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 9 Mar 2023 20:25:04 -0800 Subject: [PATCH 2/3] tweaks --- .../sdk/8.0/runtimespecific-app-default.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md index bfd82859a8627..28aeb176d2349 100644 --- a/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md +++ b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md @@ -5,7 +5,7 @@ ms.date: 03/09/2023 --- # Runtime-specific apps no longer self-contained -Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#publish-self-contained) by default, and instead [framework-dependent](../../../deploying/index.md#publish-framework-dependent) by default. +Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#publish-self-contained) by default. Instead, they are [framework-dependent](../../../deploying/index.md#publish-framework-dependent) by default. This is a break in the following situations: @@ -36,18 +36,16 @@ This change can affect [source compatibility](../../categories.md#source-compati ## Reason for change +- The new .NET SDK behavior aligns with Visual Studio behavior. +- Framework-dependent apps are now smaller by default, since there aren't copies of .NET stored in each app. +- Ideally, command-line options are orthogonal. In this case, the tooling supports both RID-specific self-contained deployment (SCD) and RID-specific framework-dependent deployment (FDD). So it didn't make sense that no RID defaulted to FDD and RID defaulted to SCD. This behavior was often confusing for users. + .NET 6 alerted users to this breaking change with the following warning: **warning NETSDK1179: One of '--self-contained' or '--no-self-contained' options are required when '--runtime' is used.** Now that customers have had time to add `SelfContained` explicitly, we felt we could introduce the break. -As for why the change is being made: - -- The new .NET SDK behavior aligns with Visual Studio behavior. -- Framework-dependent apps are now smaller by default, since there aren't copies of .NET stored in each app. -- Ideally, command-line options are orthogonal. In this case, the tooling supports both RID-specific self-contained deployment (SCD) and RID-specific framework-dependent deployment (FDD). So it didn't make sense that no RID defaulted to FDD and RID defaulted to SCD. This behavior was often confusing for users. - ## Recommended action If you're using .NET 7 or an earlier version and relied on the previous behavior where `SelfContained` was inferred, you'll see this warning: From 3847c0b87378a61464254e9767298b8106ad2e86 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 13 Mar 2023 12:58:10 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: David Pine --- .../compatibility/sdk/8.0/runtimespecific-app-default.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md index 28aeb176d2349..9574771efafb2 100644 --- a/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md +++ b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md @@ -7,16 +7,16 @@ ms.date: 03/09/2023 Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#publish-self-contained) by default. Instead, they are [framework-dependent](../../../deploying/index.md#publish-framework-dependent) by default. -This is a break in the following situations: +This is a breaking change in the following situations: - If you deployed, distributed, or published your app and didn't explicitly add the `SelfContained` property, but also didn't require that the .NET runtime be installed on the machine for it to work. In this case, you may have relied on the previous behavior to produce a non-framework-dependent app by default. -- If you relied on the IL Link tool. In this case, you'll have to take the steps described under [Recommended action](#recommended-action) to use IL Link again. +- If you rely on the IL Link tool. In this case, you'll have to take the steps described under [Recommended action](#recommended-action) to use IL Link again. > [!NOTE] > Some publish properties, like `PublishTrimmed`, `PublishSingleFile`, and `PublishAot`, currently require `SelfContained` to work. If you use these properties, you'll need to add the `SelfContained` property. -- For Blazor WASM apps, because they relied on the previous behavior. However, the Blazor WASM team may side-step this breaking change in their SDK by adding `SelfContained` automatically for all apps, so Blazor customers shouldn't be affected. +- For Blazor WebAssembly apps, because they relied on the previous behavior. However, the Blazor WASM team may side-step this breaking change in their SDK by adding `SelfContained` automatically for all apps, so Blazor customers shouldn't be affected. ## Previous behavior