Document breaking change: Double quotes disallowed in file-level directives

[Copilot]

.NET 10 GA now errors when double quotes appear in #: file-level directives for file-based apps. Previously, quotes were silently escaped to " when passed to MSBuild, which didn't provide the expected behavior.

Changes

• New document: docs/core/compatibility/sdk/10.0/file-level-directive-double-quotes.md
  • Describes the breaking change for #:property, #:sdk, #:package, and #:project directives
  • Provides migration path: use Directory.Build.props or convert to full project via dotnet project convert
  • Links to preprocessor directives documentation
• Updated TOC and index: Added entry in alphabetical order to SDK breaking changes for .NET 10

Example

// This now fails at build time:
#:property Prop="my test"

// Error: Directives currently cannot contain double quotes (").

Fixes #496360

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: Double quotes in file-level directives are disallowed</issue_title>
<issue_description>### Description

Usage of double quotes " inside #: file-level directives is now a build-time error when running file-based apps (dotnet run app.cs). dotnet/sdk#51119

Version

.NET 10 GA

Previous behavior

In .NET 10 RC2 and older .NET 10 previews, quotes in directives weren't blocked but they didn't do what you might think they did - i.e., they were only escaped as any other special character and passed to MSBuild, for example #:property Prop="my test" would result in <Prop>&quot;my test&quot</Prop>.

New behavior

An error is reported if double quote " is encountered in any file-level directive (the error is Directives currently cannot contain double quotes (").).

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

This was changed so we can later add support for quoted directives (dotnet/sdk#49367) without a breaking change. This also improves the error recovery experience if users try to use quotes now thinking that's supported syntax.

Recommended action

You should not use quotes in #: directives. If you really need to use a double quote (or another special character which 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).

Feature area

SDK

Affected APIs

No response

---

Associated WorkItem - 496360</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Breaking change]: Double quotes in file-level directives are disallowed #48916

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/10.0.md	Breaking changes in .NET 10
docs/core/compatibility/sdk/10.0/file-level-directive-double-quotes.md	Double quotes in file-level directives are disallowed
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull Request Overview

This PR adds documentation for a breaking change in .NET 10 GA where double quotes are disallowed in file-level directives (#:) for file-based apps. The change prevents potentially confusing behavior and prepares for future support of quoted directives.

Key Changes

• Adds new breaking change documentation for double quote restrictions in file-level directives.
• Updates the TOC and summary page to include the new breaking change entry.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
docs/core/compatibility/sdk/10.0/file-level-directive-double-quotes.md	New breaking change documentation describing the double quote restriction in file-level directives
docs/core/compatibility/toc.yml	Adds TOC entry for the new breaking change document
docs/core/compatibility/10.0.md	Adds table entry linking to the new breaking change