dotnet sln add breaking change (#43931)

dotnet · Jan 6, 2025 · bf5a621 · bf5a621
1 parent 53ac700
commit bf5a621
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 0 deletions.
diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md
@@ -100,6 +100,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 | Title                                                                         | Type of change    | Introduced version |
 |-------------------------------------------------------------------------------|-------------------|--------------------|
 | [`dotnet restore` audits transitive packages](sdk/9.0/nugetaudit-transitive-packages.md) | Behavioral change | Preview 6 |
+| [`dotnet sln add` doesn't allow invalid file names](sdk/9.0/dotnet-sln.md) | Behavioral change | 9.0.2xx |
 | [`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    |

diff --git a/docs/core/compatibility/sdk/9.0/dotnet-sln.md b/docs/core/compatibility/sdk/9.0/dotnet-sln.md
@@ -0,0 +1,47 @@
+---
+title: "'dotnet sln add' no longer allows invalid file names"
+description: Learn about the breaking change in the .NET SDK where the CLI command 'dotnet sln add' adds support for .slnx solution files and no longer allows invalid file names.
+ms.date: 12/10/2024
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/43882
+---
+
+# `dotnet sln add` no longer allows invalid file names
+
+Starting in .NET SDK 9.0.2xx, the [`dotnet sln add`](../../../tools/dotnet-sln.md#add) CLI command includes support for *.slnx* solution files using the [vs-solutionpersistence](https://github.com/microsoft/vs-solutionpersistence) serializer. As a result, slight changes in behavior are expected.
+
+## Version introduced
+
+.NET SDK 9.0.2xx
+
+## Previous behavior
+
+Previously, projects and solution folders could have invalid Windows file names. They could also have invalid characters in their names. In addition, `dotnet sln add` failed if you attempted to add a nested project with the same name as an existing project.
+
+## New behavior
+
+Starting in .NET SDK 9.0.2xx, projects and solution folder names:
+
+- Can't be a DOS word: `NUL`, `CON`, `AUX`, `PRN`, `COM?`, `LPT?`, or `CLOCK$` (where `?` is any number of digits).
+- Must be 260 characters or less.
+- Can't contain invalid characters, such as control characters or `?`, `:`, `\`, `/`, `*`, `"`, `"`, `<`, `>`, and `|`.
+
+In addition, `dotnet sln add` now succeeds if you attempt to add a nested project with the same name as an existing project, which mimics the behavior for non-nested projects. Example: Adding `folder/project.csproj` and `parent/child/project.csproj` doesn't result in an error.
+
+Exceptions contain the current strings, but wrap error messages from [vs-solutionpersistence](https://github.com/microsoft/vs-solutionpersistence).
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+These changes were introduced to transition to the new `vs-solutionpersistence` serializer.
+
+## Recommended action
+
+Review project and solution folders names to ensure they comply with the new naming restrictions.
+
+## Affected APIs
+
+N/A
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -106,6 +106,8 @@ items:
             items:
               - name: "`dotnet restore` audits transitive packages"
                 href: sdk/9.0/nugetaudit-transitive-packages.md
+              - name: "`dotnet sln add` doesn't allow invalid file names"
+                href: sdk/9.0/dotnet-sln.md
               - name: "`dotnet watch` incompatible with Hot Reload for old frameworks"
                 href: sdk/9.0/dotnet-watch.md
               - name: "`dotnet workload` commands output change"
@@ -1810,6 +1812,8 @@ items:
             items:
               - name: "`dotnet restore` audits transitive packages"
                 href: sdk/9.0/nugetaudit-transitive-packages.md
+              - name: "`dotnet sln add` doesn't allow invalid file names"
+                href: sdk/9.0/dotnet-sln.md
               - name: "`dotnet watch` incompatible with Hot Reload for old frameworks"
                 href: sdk/9.0/dotnet-watch.md
               - name: "`dotnet workload` commands output change"