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

Copilot · 2025-11-04T01:27:01Z

.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>"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

…ectives Co-authored-by: gewarren <[email protected]>

Co-authored-by: gewarren <[email protected]>

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

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

Copilot · 2025-11-04T02:05:30Z

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

+
+## 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>`.


According to the Markdown guidelines, contractions should be used for improved conversational tone. Change "weren't" to "weren't" and "didn't" to "didn't" for consistency with the writing style (though they appear correct already). However, the more important issue is the use of passive voice. Rewrite this sentence in active voice: 'In .NET 10 RC2 and older .NET 10 previews, .NET didn't block quotes in directives, but they didn't work as expected. .NET escaped them as any other special character and passed them to MSBuild.'

Copilot · 2025-11-04T02:05:31Z

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

+
+## Reason for change
+
+This change was made so support can be added later 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.


Rewrite in active voice and use imperative mood where appropriate. The phrase 'This change was made so' is passive. Consider: 'This change enables future support for quoted directives without introducing a breaking change. It also improves the error recovery experience when users try quotes, thinking they're supported syntax.'

Copilot · 2025-11-04T02:05:31Z

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

+
+## 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`.


Remove the conversational filler 'really' as per guidelines to avoid unnecessary adverbs. Change to: 'If you need to use a double quote...'

Copilot · 2025-11-04T02:05:31Z

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

+
+## 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`.


The parenthetical '(it will be picked up by the file-based app)' is unnecessary explanation. According to guidelines to be concise and front-load important information, consider removing this parenthetical or moving it to the beginning of the sentence if it's critical context.

Initial plan

94e369d

Copilot AI assigned Copilot and gewarren Nov 4, 2025

Copilot started work on behalf of gewarren November 4, 2025 01:27 View session

Add breaking change documentation for double quotes in file-level dir…

b851024

…ectives Co-authored-by: gewarren <[email protected]>

dotnet-policy-service bot added the dotnet-fundamentals/svc label Nov 4, 2025

Fix XML example typo: add missing semicolon

65a8350

Co-authored-by: gewarren <[email protected]>

Copilot AI changed the title ~~[WIP] Fix error for double quotes in file-level directives~~ Document breaking change: Double quotes disallowed in file-level directives Nov 4, 2025

Copilot AI requested a review from gewarren November 4, 2025 01:37

Copilot finished work on behalf of gewarren November 4, 2025 01:37

gewarren approved these changes Nov 4, 2025

View reviewed changes

Apply suggestions from code review

e72622f

gewarren reviewed Nov 4, 2025

View reviewed changes

Apply suggestions from code review

d085f5a

gewarren marked this pull request as ready for review November 4, 2025 02:03

gewarren requested a review from a team as a code owner November 4, 2025 02:03

Copilot AI review requested due to automatic review settings November 4, 2025 02:03

gewarren enabled auto-merge (squash) November 4, 2025 02:04

Copilot AI reviewed Nov 4, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

Copilot AI commented Nov 4, 2025 •

edited by github-actions bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 4, 2025

Uh oh!

Copilot AI Nov 4, 2025

Uh oh!

Copilot AI Nov 4, 2025

Uh oh!

Copilot AI Nov 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## 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>"my test"</Prop>`.


		## Reason for change

		This change was made so support can be added later 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`.

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

Copilot AI commented Nov 4, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Example

Version

Previous behavior

New behavior

Type of breaking change

Reason for change

Recommended action

Feature area

Affected APIs

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

Internal previews

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Nov 4, 2025 •

edited by github-actions bot

Loading