Skip to content

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

Merged
gewarren merged 6 commits intomainfrom
copilot/fix-double-quotes-in-directives
Nov 6, 2025
Merged

Document breaking change: Double quotes disallowed in file-level directives#49608
gewarren merged 6 commits intomainfrom
copilot/fix-double-quotes-in-directives

Conversation

Copy link
Contributor

Copilot AI commented Nov 4, 2025 •
edited by github-actions bot
Loading

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

💬 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

@gewarren
Add breaking change documentation for double quotes in file-level dir…
b851024 
…ectives

Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>
@gewarren
Fix XML example typo: add missing semicolon
65a8350 
Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>
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
gewarren
gewarren approved these changes Nov 4, 2025
View reviewed changes
gewarren
gewarren reviewed Nov 4, 2025
View reviewed changes
@gewarren gewarren marked this pull request as ready for review November 4, 2025 02:03
@gewarren 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 gewarren enabled auto-merge (squash) November 4, 2025 02:04
Copilot AI reviewed Nov 4, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@gewarren gewarren requested a review from jjonescz November 6, 2025 01:35
@gewarren gewarren merged commit 6c4d329 into main Nov 6, 2025
11 checks passed
@gewarren gewarren deleted the copilot/fix-double-quotes-in-directives branch November 6, 2025 15:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gewarren gewarren gewarren approved these changes

Copilot code review Copilot Copilot left review comments

@jjonescz jjonescz jjonescz approved these changes

Assignees

@gewarren gewarren

Copilot code review Copilot

Labels

dotnet-fundamentals/svc

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Breaking change]: Double quotes in file-level directives are disallowed

4 participants

@jjonescz @gewarren