Skip to content

Commit f396d3f

Browse files
gewarrengewarren
authored
Breaking changes (3) (#43874)
1 parent d1f7a9c commit f396d3f

File tree

5 files changed

+204
-3
lines changed

5 files changed

+204
-3
lines changed

‎docs/core/compatibility/9.0.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,15 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
2222
| [DefaultKeyResolution.ShouldGenerateNewKey has altered meaning](aspnet-core/9.0/key-resolution.md) | Behavioral change | Preview 3 |
2323
| [Dev cert export no longer creates folder](aspnet-core/9.0/certificate-export.md) | Behavioral change | RC 1 |
2424
| [HostBuilder enables ValidateOnBuild/ValidateScopes in development environment](aspnet-core/9.0/hostbuilder-validation.md) | Behavioral change | Preview 7 |
25+
| [Legacy Mono and Emscripten APIs not exported to global namespace](aspnet-core/9.0/legacy-apis.md) | Source incompatible | GA |
2526
| [Middleware types with multiple constructors](aspnet-core/9.0/middleware-constructors.md) | Behavioral change | RC 1 |
2627

2728
## Containers
2829

2930
| Title | Type of change | Introduced version |
3031
|-----------------------------------------------------------------------------|-------------------|--------------------|
31-
| [.NET 9 container images no longer install zlib](containers/9.0/no-zlib.md) | Behavioral change | Preview 7 |
32+
| [Container images no longer install zlib](containers/9.0/no-zlib.md) | Behavioral change | Preview 7 |
33+
| [.NET Monitor images simplified to version-only tags](containers/9.0/monitor-images.md) | Behavioral change |Preview 5 |
3234

3335
## Core .NET libraries
3436

@@ -47,6 +49,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
4749
| [Inline array struct size limit is enforced](core-libraries/9.0/inlinearray-size.md) | Behavioral change | Preview 1 |
4850
| [InMemoryDirectoryInfo prepends rootDir to files](core-libraries/9.0/inmemorydirinfo-prepends-rootdir.md) | Behavioral change | Preview 1 |
4951
| [New TimeSpan.From*() overloads that take integers](core-libraries/9.0/timespan-from-overloads.md) | Source incompatible | Preview 3 |
52+
| [New version of some OOB packages](core-libraries/9.0/oob-packages.md) | Source incompatible | Preview 5 |
5053
| [RuntimeHelpers.GetSubArray returns different type](core-libraries/9.0/getsubarray-return.md) | Behavioral change | Preview 1 |
5154
| [String.Trim(params ReadOnlySpan\<char>) overload removed](core-libraries/9.0/string-trim.md) | Source/binary incompatible | GA |
5255
| [Support for empty environment variables](core-libraries/9.0/empty-env-variable.md) | Behavioral change | Preview 6 |

‎docs/core/compatibility/aspnet-core/9.0/legacy-apis.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: "Legacy Mono and Emscripten JavaScript APIs not exported to global namespace in Blazor WebAssembly apps"
3+
description: Learn about the breaking change in ASP.NET Core 9 where legacy Mono and Emscripten APIs are now accessible through the Blazor.runtime object instead of the global namespace.
4+
ms.date: 12/4/2024
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/aspnet/Announcements/issues/516
7+
---
8+
9+
# Legacy Mono and Emscripten JavaScript APIs not exported to global namespace
10+
11+
Blazor WebAssembly no longer exports legacy Mono and Emscripten APIs to the global namespace. These APIs are now accessible through the `Blazor.runtime` object.
12+
13+
## Version introduced
14+
15+
.NET 9 GA
16+
17+
## Previous behavior
18+
19+
Legacy Mono APIs (`MONO` and `BINDING`) and the Emscripten `Module` object were exported to the global `window` object. For example, `window.Module.FS` returned the Emscripten virtual filesystem.
20+
21+
## New behavior
22+
23+
The Emscripten `Module` object is now exported to the `Blazor.runtime` object. For example, `Blazor.runtime.Module.FS` returns the Emscripten virtual filesystem. The legacy Mono API for interop (`MONO` and `BINDING`) is removed completely and replaced with `JSImport`/`JSExport`.
24+
25+
## Type of breaking change
26+
27+
This change can affect [source compatibility](../../categories.md#source-compatibility).
28+
29+
## Reason for change
30+
31+
This change was made to avoid polluting the global namespace and keep all the APIs accessible from a single Blazor object.
32+
33+
## Recommended action
34+
35+
Instead of accessing Emscripten APIs from the `window` object, access them from the `Blazor.runtime` object.
36+
37+
## Affected APIs
38+
39+
- `window.MONO.*`
40+
- `window.BINDING.*`
41+
- `window.Module.*`

‎docs/core/compatibility/containers/9.0/monitor-images.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: ".NET Monitor images simplified to version-only tags"
3+
description: Learn about the breaking change in containers where the .NET Monitor 9 image offering has been simplified to only provide Azure Linux distroless images.
4+
ms.date: 12/4/2024
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/43379
7+
---
8+
9+
# .NET Monitor images simplified to version-only tags
10+
11+
The .NET Monitor 9 image offering has been simplified to only provide Azure Linux distroless images. As part of this change, the Ubuntu Chiseled and CBL-Mariner tags have been superseded by version-only tags.
12+
13+
## Version introduced
14+
15+
.NET Monitor 9
16+
17+
## Previous behavior
18+
19+
.NET Monitor 8 offered the following types of images:
20+
21+
- Ubuntu Chiseled Arm64 and x64
22+
- CBL-Mariner Distroless Arm64 and x64
23+
24+
## New behavior
25+
26+
.NET Monitor 9 offers the following types of images and their tags:
27+
28+
- Azure Linux distroless Arm64 and x64: `9`, `9.0`, and `9.0.0`
29+
30+
The following tag patterns from .NET Monitor 8 don't have an equivalent in the .NET Monitor 9 offering:
31+
32+
- Ubuntu Chiseled Arm64 and x64:
33+
- `*-ubuntu-chiseled`
34+
- `*-ubuntu-chiseled-amd64`
35+
- `*-ubuntu-chiseled-arm64v8`
36+
- CBL-Mariner distroless Arm64 and x64:
37+
- `*-cbl-mariner-distroless`
38+
- `*-cbl-mariner-distroless-amd64`
39+
- `*-cbl-mariner-distroless-arm64v8`
40+
41+
The .NET Monitor 9 images have version-only tags. There are no OS tags due to only producing images based on a single distro.
42+
43+
The `latest` tag has been updated from the Ubuntu Chiseled images to Azure Linux images.
44+
45+
## Type of breaking change
46+
47+
This change is a [behavioral change](../../categories.md#behavioral-change).
48+
49+
## Reason for change
50+
51+
During the .NET Monitor 8.0 development cycle, only the .NET Ubuntu Chiseled images were publicly available for customers to use. Later in the development cycle, the .NET CBL-Mariner distroless images became publicly available for customers to use. At that time, it was decided to keep producing .NET Monitor images based on both distros so that current usage wasn't disrupted.
52+
53+
From the perspective of the .NET Monitor tool, both distros provided a similar capability set, footprint, and security posture. The .NET Monitor images are intended to be used as appliance images. These images aren't intended to be used as base images for derivation and are only intended to be used "as-is". With the public availability of the .NET CBL-Mariner images last year, and subsequent change to Azure Linux, the .NET Monitor image offering has been simplified to only produce images based on the Azure Linux distro. The tagging scheme has been simplified to reflect this change.
54+
55+
## Recommended action
56+
57+
Update your tag usage to indicate which image from the .NET Monitor 9 image offering you want to use. The following examples show some recommended migrations:
58+
59+
- `8-cbl-mariner-distroless` -> `9`
60+
- `8.0-cbl-mariner-distroless` -> `9.0`
61+
- `8-ubuntu-chiseled` -> `9`
62+
- `8.0-ubuntu-chiseled` -> `9.0`
63+
64+
The following table shows the recommended .NET Monitor 9 tags.
65+
66+
| Tag | Recommended use |
67+
|-------|---------------------------------------------------------------------|
68+
| `9` | To stay on the latest .NET Monitor 9 *release and servicing* update |
69+
| `9.0` | To stay on the latest .NET Monitor 9.0 *servicing* update |
70+
71+
A full list of all supported tags can be found on .NET Monitor's [README](https://github.com/dotnet/dotnet-docker/blob/main/README.monitor.md#full-tag-listing) in the `dotnet/dotnet-docker` GitHub repository.
72+
73+
Starting in .NET Monitor 8, the image offering was changed from using full distro images to using distroless images. If you're migrating from .NET Monitor 7 or earlier, the notable changes when migrating from a full distro image to a distroless image are:
74+
75+
- The use of a non-root user
76+
- The lack of a package manager
77+
- The lack of a shell
78+
79+
If you were using full distro images (for example, Alpine), you might need to adjust the running user of the .NET Monitor image in your deployments when migrating to .NET Monitor 8 or later. You can find guidance for changing the running user in the .NET Monitor 8.0 [compatibility documentation](https://github.com/dotnet/dotnet-monitor/blob/main/documentation/compatibility/8.0/README.md).
80+
81+
For changes from .NET Monitor 8 to .NET Monitor 9, see the .NET Monitor 9.0 [compatibility documentation](https://github.com/dotnet/dotnet-monitor/blob/main/documentation/compatibility/9.0/README.md).
82+
83+
## Affected APIs
84+
85+
N/A

‎docs/core/compatibility/core-libraries/9.0/oob-packages.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: "New version of some OOB packages"
3+
description: Learn about the breaking change in core .NET libraries where updates were made to TFMs and package versions for several OOB packages.
4+
ms.date: 12/4/2024
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/43564
7+
---
8+
9+
# New version of some OOB packages
10+
11+
New versions of some out-of-band (OOB) packages were generated. The following changes were made that can be considered breaking:
12+
13+
- The supported target framework monikers (TFMs) were updated.
14+
- The package version minor number was updated.
15+
- In some cases, some TFMs are no longer supported.
16+
17+
Additionally, the source code of these packages was migrated from their old location, which was a branch of .NET that is no longer in support, to the <https://github.com/dotnet/maintenance-packages> repo.
18+
19+
| Package | Old source code location | New package version |
20+
|-----------------------------------------|-----------------------------------------------------------------|---------------------|
21+
| Microsoft.Bcl.HashCode | [dotnet/corefx](https://github.com/dotnet/corefx), 3.1 branch | 6.0.0 |
22+
| Microsoft.IO.Redist | [dotnet/runtime](https://github.com/dotnet/runtime), 6.0 branch | 6.1.0 |
23+
| System.Buffers | [dotnet/corefx](https://github.com/dotnet/corefx), 2.1 branch | 4.6.0 |
24+
| System.Data.SqlClient | [dotnet/corefx](https://github.com/dotnet/corefx), 3.1 branch | 4.9.0 |
25+
| System.Json | [dotnet/corefx](https://github.com/dotnet/corefx), 3.1 branch | 4.8.0 |
26+
| System.Memory | [dotnet/corefx](https://github.com/dotnet/corefx), 2.1 branch | 4.6.0 |
27+
| System.Net.WebSockets.WebSocketProtocol | [dotnet/runtime](https://github.com/dotnet/runtime), 5.0 branch | 5.1.0 |
28+
| System.Numerics.Vectors | [dotnet/corefx](https://github.com/dotnet/corefx), 2.1 branch | 4.6.0 |
29+
| System.Reflection.DispatchProxy | [dotnet/corefx](https://github.com/dotnet/corefx), 3.1 branch | 4.8.0 |
30+
| System.Runtime.CompilerServices.Unsafe | [dotnet/runtime](https://github.com/dotnet/runtime), 6.0 branch | 6.1.0 |
31+
| System.Threading.Tasks.Extensions | [dotnet/corefx](https://github.com/dotnet/corefx), 2.1 branch | 4.6.0 |
32+
| System.Xml.XPath.XmlDocument | [dotnet/corefx](https://github.com/dotnet/corefx), 1.1 branch | 4.7.0 |
33+
34+
## Version introduced
35+
36+
.NET 9
37+
38+
## Previous behavior
39+
40+
The old packages targeted some TFMs that became out-of-support.
41+
42+
## New behavior
43+
44+
Some TFMs that were previously supported are no longer supported. However, there are no source code changes.
45+
46+
## Type of breaking change
47+
48+
This change can affect [source compatibility](../../categories.md#source-compatibility).
49+
50+
## Reason for change
51+
52+
The source code of these packages was moved from their old branch, which was already out of support, to a repository that is actively maintained.
53+
54+
## Recommended action
55+
56+
Depending on the package, different recommended actions are provided. For more information, see the [package support policy](https://github.com/dotnet/maintenance-packages/tree/main/package-support-policy.md).
57+
58+
## Affected APIs
59+
60+
All APIs contained in the affected packages.

‎docs/core/compatibility/toc.yml

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,16 @@ items:
1616
href: aspnet-core/9.0/certificate-export.md
1717
- name: HostBuilder enables ValidateOnBuild/ValidateScopes in development environment
1818
href: aspnet-core/9.0/hostbuilder-validation.md
19+
- name: Legacy Mono and Emscripten APIs not exported to global namespace
20+
href: aspnet-core/9.0/legacy-apis.md
1921
- name: Middleware types with multiple constructors
2022
href: aspnet-core/9.0/middleware-constructors.md
2123
- name: Containers
2224
items:
23-
- name: .NET 9 container images no longer install zlib
25+
- name: Container images no longer install zlib
2426
href: containers/9.0/no-zlib.md
27+
- name: .NET Monitor images simplified to version-only tags
28+
href: containers/9.0/monitor-images.md
2529
- name: Core .NET libraries
2630
items:
2731
- name: Adding a ZipArchiveEntry sets header general-purpose bit flags
@@ -48,6 +52,8 @@ items:
4852
href: core-libraries/9.0/inmemorydirinfo-prepends-rootdir.md
4953
- name: New TimeSpan.From*() overloads that take integers
5054
href: core-libraries/9.0/timespan-from-overloads.md
55+
- name: New version of some OOB packages
56+
href: core-libraries/9.0/oob-packages.md
5157
- name: RuntimeHelpers.GetSubArray returns different type
5258
href: core-libraries/9.0/getsubarray-return.md
5359
- name: String.Trim(params ReadOnlySpan<char>) overload removed
@@ -1048,6 +1054,8 @@ items:
10481054
href: aspnet-core/9.0/certificate-export.md
10491055
- name: HostBuilder enables ValidateOnBuild/ValidateScopes in development environment
10501056
href: aspnet-core/9.0/hostbuilder-validation.md
1057+
- name: Legacy Mono and Emscripten APIs not exported to global namespace
1058+
href: aspnet-core/9.0/legacy-apis.md
10511059
- name: Middleware types with multiple constructors
10521060
href: aspnet-core/9.0/middleware-constructors.md
10531061
- name: .NET 8
@@ -1256,8 +1264,10 @@ items:
12561264
items:
12571265
- name: .NET 9
12581266
items:
1259-
- name: .NET 9 container images no longer install zlib
1267+
- name: Container images no longer install zlib
12601268
href: containers/9.0/no-zlib.md
1269+
- name: .NET Monitor images simplified to version-only tags
1270+
href: containers/9.0/monitor-images.md
12611271
- name: .NET 8
12621272
items:
12631273
- name: "'ca-certificates' removed from Alpine images"
@@ -1310,6 +1320,8 @@ items:
13101320
href: core-libraries/9.0/inmemorydirinfo-prepends-rootdir.md
13111321
- name: New TimeSpan.From*() overloads that take integers
13121322
href: core-libraries/9.0/timespan-from-overloads.md
1323+
- name: New version of some OOB packages
1324+
href: core-libraries/9.0/oob-packages.md
13131325
- name: RuntimeHelpers.GetSubArray returns different type
13141326
href: core-libraries/9.0/getsubarray-return.md
13151327
- name: String.Trim(params ReadOnlySpan<char>) overload removed

0 commit comments

Comments
 (0)