diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 7450fa0d83314..369f0af6dd2a0 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -98,5 +98,6 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking- | [dnx scripts bypass global.json SDK selection](sdk/11/dnx-scripts-bypass-global-json.md) | Behavioral change | | [mono launch target not set for .NET Framework apps](sdk/11/mono-launch-target-removed.md) | Behavioral change | | [NU1703 warns for packages that use deprecated MonoAndroid framework assets](sdk/11/nu1703-deprecated-monoandroid-framework.md) | Source incompatible | +| [NuGet pack warns for package IDs with restricted characters](sdk/11/nuget-pack-nu5052-packageid.md) | Behavioral change | | [Template engine packages no longer support netstandard2.0](sdk/11/template-engine-netstandard.md) | Binary/source incompatible | | [VSTest removes dependency on Newtonsoft.Json](sdk/11/vstest-removes-newtonsoft-json.md) | Binary/source incompatible | diff --git a/docs/core/compatibility/sdk/11/nuget-pack-nu5052-packageid.md b/docs/core/compatibility/sdk/11/nuget-pack-nu5052-packageid.md new file mode 100644 index 0000000000000..04184765851d6 --- /dev/null +++ b/docs/core/compatibility/sdk/11/nuget-pack-nu5052-packageid.md @@ -0,0 +1,50 @@ +--- +title: "Breaking change: NuGet pack warns for package IDs with restricted characters" +description: "Learn about the breaking change in .NET 11 where NuGet's pack command emits warning NU5052 for package IDs that use characters outside the restricted set." +ms.date: 07/22/2026 +ai-usage: ai-assisted +--- + +# NuGet pack warns for package IDs with restricted characters + +Starting in .NET 11, `dotnet pack` emits warning **NU5052** when a package ID contains characters outside the restricted character set enforced by nuget.org. + +## Version introduced + +.NET 11 Preview 6 + +## Previous behavior + +Previously, `dotnet pack` produced a package for any package ID that the legacy NuGet ID rules accepted, including IDs with characters outside ASCII letters, digits, dots, and dashes, or with consecutive `.` or `-` characters. + +## New behavior + +Starting in .NET 11 (with `SdkAnalysisLevel >= 11.0.100`), packing a project whose `PackageId` doesn't meet the restricted rules emits warning **NU5052**. A valid package ID: + +- Must start with a letter, digit, or underscore (`_`). +- Can contain only ASCII letters, digits, dots (`.`), dashes (`-`), and underscores (`_`). +- Can't contain consecutive `.` or `-` characters. +- Must be 100 characters or fewer. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +NuGet derives strings such as URLs and file-system paths from a normalized version of the package ID. Normalization relies on built-in string libraries that are inconsistent across .NET Framework, modern .NET, Windows, and Linux, so two visibly different IDs can normalize to the same string. Restricting the allowed character set, as npm, PyPI, and other registries have done, closes this security and branding gap. + +For more information, see the [NuGet announcement](https://github.com/NuGet/Announcements/issues/75). + +## Recommended action + +Rename the package to an ID within the restricted character set—for example, transliterate non-ASCII characters to their ASCII equivalents (`Müller.Logging` becomes `Mueller.Logging`). Then deprecate the old package ID and point it at the new one. + +Because this warning doesn't block the build, you can also suppress it: + +- Add `NU5052` to the project file. +- Set `SdkAnalysisLevel` to a version below `11.0.100`. + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 6117c83450f24..438745e3a1f56 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -78,6 +78,8 @@ items: href: sdk/11/mono-launch-target-removed.md - name: NU1703 warns for packages that use deprecated MonoAndroid framework assets href: sdk/11/nu1703-deprecated-monoandroid-framework.md + - name: NuGet pack warns for package IDs with restricted characters + href: sdk/11/nuget-pack-nu5052-packageid.md - name: Template engine packages no longer support netstandard2.0 href: sdk/11/template-engine-netstandard.md - name: VSTest removes dependency on Newtonsoft.Json