Document breaking change: Double quotes disallowed in file-level directives (#49608)

Author: Copilot

docs/core/compatibility/10.0.md

@@ -119,6 +119,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [.NET tool packaging creates RuntimeIdentifier-specific tool packages](sdk/10.0/dotnet-tool-pack-publish.md) | Behavioral change | Preview 6 |
 | [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | Preview 2 |
 | [dnx.ps1 file is no longer included in .NET SDK](sdk/10.0/dnx-ps1-removed.md) | Source incompatible | GA |
+| [Double quotes in file-level directives are disallowed](sdk/10.0/file-level-directive-double-quotes.md) | Source incompatible | GA |
 | [`dotnet new sln` defaults to SLNX file format](sdk/10.0/dotnet-new-sln-slnx-default.md) | Behavioral change | RC 1 |
 | [`dotnet package list` performs restore](sdk/10.0/dotnet-package-list-restore.md) | Behavioral change | Preview 4 |
 | [`dotnet restore` audits transitive packages](sdk/10.0/nugetaudit-transitive-packages.md) | Behavioral change | Preview 3 |

docs/core/compatibility/sdk/10.0/file-level-directive-double-quotes.md

@@ -0,0 +1,41 @@
+---
+title: "Breaking change - Double quotes in file-level directives are disallowed"
+description: "Learn about the breaking change in .NET 10 where double quotes in file-level directives are disallowed."
+ms.date: 11/04/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/48916
+---
+
+# Double quotes in file-level directives are disallowed
+
+Usage of double quotes `"` inside `#:` file-level directives is now a build-time error when running file-based apps (for example, `dotnet run app.cs`).
+
+## Version introduced
+
+.NET 10 GA
+
+## Previous behavior
+
+In .NET 10 RC2 and older .NET 10 previews, quotes in directives weren't blocked but they didn't work as expected. They were only escaped as any other special character and passed to MSBuild. For example, `#:property Prop="my test"` resulted in `<Prop>&quot;my test&quot;</Prop>`.
+
+## New behavior
+
+An error is reported if a double quote `"` is encountered in any file-level directive. The error message is:
+
+> Directives currently cannot contain double quotes (").
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+This change enables future support for quoted directives without introducing a breaking change. This also improves the error recovery experience if users try to use quotes now, thinking that's supported syntax.
+
+## Recommended action
+
+Don't use quotes in `#:` directives. If you really need to use a double quote (or another special character that currently isn't supported, like trailing whitespace), move the corresponding project metadata entry into a `Directory.Build.props` file instead (it will be picked up by the file-based app). Or, convert the file-based app to a full project via `dotnet project convert`.
+
+## Affected APIs
+
+None.

docs/core/compatibility/toc.yml

@@ -134,6 +134,8 @@ items:
                 href: sdk/10.0/dotnet-tool-pack-publish.md
               - name: dnx.ps1 file is no longer included in .NET SDK
                 href: sdk/10.0/dnx-ps1-removed.md
+              - name: Double quotes in file-level directives are disallowed
+                href: sdk/10.0/file-level-directive-double-quotes.md
               - name: "`dotnet restore` audits transitive packages"
                 href: sdk/10.0/nugetaudit-transitive-packages.md
               - name: project.json not supported in `dotnet restore`