Merge pull request #47971 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

.github/copilot-instructions.md

@@ -1,45 +1,59 @@
-When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced.
-
-When writing documentation, follow the following guidelines:
-
-Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
-
-Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
-
-Headings should be in sentence case, not title case. Don't use gerunds in titles.
-
-Use the active voice whenever possible, and second person to address the reader directly.
-
-Use a conversational tone with contractions.
-
-Be concise.
-
-Break up long sentences.
-
-Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value."
-
-Do not use "we" or "our" to refer to the authors of the documentation.
-
-Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method."
-
-Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception."
-
-Use the Oxford comma in lists of three or more items.
-
-Number ordered list items all as "1." instead of "1.", "2.", etc.
-
-Use bullets for unordered lists. Unless *all* the bullet list items are three words or less, each bullet item should end with a period.
-
-Use **bold** when referring to UI elements. Use `code style` for file names and folders, custom types, and other text that should never be localized.
-
-Put raw URLs within angle brackets.
-
-Include links to related topics and resources where appropriate. Use relative links if the target file lives in this repo. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link.
-
-When mentioning APIs, use cross-references to the API documentation. These links are formatted as <xref:api-doc-ID>. You can find the API doc ID in the XML files in the https://github.com/dotnet/dotnet-api-docs repository. For types, the doc ID is the value of the `Value` attribute of the `<TypeSignature>` element where the `Language` attribute value is `DocId`. For other (member) APIs, the doc ID is the value of the `Value` attribute of the `<MemberSignature>` element where the `Language` attribute value is `DocId`. Omit the first two characters of the DocId. For example, the xref link for System.String is <xref:System.String>.
-
-If you're assigned a GitHub issue that's labeled "breaking-change", include the prompt directions in the .github/prompts/breaking-change.md file in this repo.
-
-If you include a code snippet that's more than 6 lines long, put it in a separate .cs file in a folder named "snippets" in the same folder as the document. Within the "snippets" folder, add a new directory with the name of the document. For example, if the document is named "my-doc.md", create a folder named "snippets/my-doc" folder. Also add a simple .csproj file to the same directory that targets the latest version of .NET. It can be a library or executable project.
-
-If you're adding a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name.
+# .NET Documentation Guidelines
+
+## Terminology
+- Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
+
+## Writing Style
+Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics:
+
+### Voice and Tone
+- Active voice, second person addressing reader directly.
+- Conversational tone with contractions.
+- Present tense for instructions/descriptions.
+- Imperative mood for instructions ("Call the method" not "You should call the method").
+- Use "might" instead of "may" for possibility.
+- Use "can" instead of "may" for permissible actions.
+- Avoid "we"/"our" referring to documentation authors or product teams.
+
+### Structure and Format
+- Sentence case headings (no gerunds in titles).
+- Be concise, break up long sentences.
+- Oxford comma in lists.
+- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.)
+- Use bullets for unordered lists.
+- Ordered and unordered lists should use complete sentences with proper punctuation, ending with a period if it's more than three words.
+- Avoid "etc." or "and so on" - provide complete lists or use "for example".
+- No consecutive headings without content between them.
+
+### Formatting Conventions
+- **Bold** for UI elements.
+- `Code style` for file names, folders, custom types, non-localizable text.
+- Raw URLs in angle brackets.
+- Use relative links for files in this repo.
+- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links.
+
+## API References
+Use cross-references: `<xref:api-doc-ID>`.
+
+To find API doc IDs:
+1. Check XML files in https://github.com/dotnet/dotnet-api-docs.
+2. For types: `Value` attribute of `<TypeSignature>` where `Language="DocId"` (omit first 2 characters).
+3. For members: `Value` attribute of `<MemberSignature>` where `Language="DocId"` (omit first 2 characters).
+
+If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` and then use the `url` value from the results as a manual link.
+
+## Code Snippets
+For snippets >6 lines:
+1. Create `./snippets/my-doc/language` folder in same directory as document (for a document named `my-doc.md`) where language is either vb (for visual basic) or csharp (for c#). Omit the `language` component when the document is in the `docs/visual-basic`, `docs/csharp`, or `docs/fsharp` folders.
+1. Add snippet as separate code file.
+1. Include simple project file targeting latest .NET.
+1. All code should use the latest stable versions/features.
+1. Create examples in both C# and Visual Basic unless the article referencing the snippet resides in the in the `csharp`, `fsharp`, and `visual-basic` language folders.
+1. When you add code, use code comments sparingly because they don't get localized. You can use them to briefly clarify code-specific details (such as logic, parameters, or edge cases). Put any critical information and context in the markdown text of the referencing article.
+
+## File Naming
+New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.).
+
+## Special Cases
+- Breaking changes: Include directions from `.github/prompts/breaking-change.md`.
+- When you (Copilot) are assigned an issue in GitHub, after you've completed your work and the workflows (status checks) have run, check to make sure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced.

docfx.json

@@ -362,8 +362,8 @@
                 "docs/core/project-sdk/**/**.md": "gewarren",
                 "docs/core/runtime-config/**/**.md": "gewarren",
                 "docs/core/testing/**/**.md": "IEvangelist",
-                "docs/core/tools/**/**.md": "tdykstra",
-                "docs/core/tutorials/**/**.md": "tdykstra",
+                "docs/core/tools/**/**.md": "adegeo",
+                "docs/core/tutorials/**/**.md": "billwagner",
                 "docs/core/versions/**/**.md": "billwagner",
                 "docs/core/whats-new/**/**.md": "gewarren",
                 "docs/csharp/**/*.*": "billwagner",
@@ -408,7 +408,7 @@
                 "docs/standard/attributes/**/**.md": "gewarren",
                 "docs/standard/base-types/**/**.md": "adegeo",
                 "docs/standard/collections/**/**.md": "IEvangelist",
-                "docs/standard/commandline/**/**.md": "tdykstra",
+                "docs/standard/commandline/**/**.md": "gewarren",
                 "docs/standard/data/**/**.md": "gewarren",
                 "docs/standard/data/sqlite/**/**.md": "ajcvickers",
                 "docs/standard/datetime/**/**.md": "adegeo",
@@ -455,8 +455,8 @@
                 "docs/core/project-sdk/**/**.md": "gewarren",
                 "docs/core/runtime-config/**/**.md": "gewarren",
                 "docs/core/testing/**/**.md": "dapine",
-                "docs/core/tools/**/**.md": "tdykstra",
-                "docs/core/tutorials/**/**.md": "tdykstra",
+                "docs/core/tools/**/**.md": "adegeo",
+                "docs/core/tutorials/**/**.md": "wiwagn",
                 "docs/core/versions/**/**.md": "wiwagn",
                 "docs/core/whats-new/**/**.md": "gewarren",
                 "docs/csharp/**/*.*": "wiwagn",
@@ -496,7 +496,7 @@
                 "docs/standard/attributes/**/**.md": "gewarren",
                 "docs/standard/base-types/**/**.md": "adegeo",
                 "docs/standard/collections/**/**.md": "dapine",
-                "docs/standard/commandline/**/**.md": "tdykstra",
+                "docs/standard/commandline/**/**.md": "gewarren",
                 "docs/standard/data/**/**.md": "gewarren",
                 "docs/standard/datetime/**/**.md": "adegeo",
                 "docs/standard/design-guidelines/**/**.md": "kcwalina",

docs/core/compatibility/10.0.md

@@ -129,4 +129,5 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 
 | Title | Type of change                        | Introduced version |
 |-------|---------------------------------------|--------------------|
+| [Empty ColumnDefinitions and RowDefinitions are disallowed](wpf/10.0/empty-grid-definitions.md) | Source incompatible | Preview 5          |
 | [Incorrect usage of DynamicResource causes application crash](wpf/10.0/dynamicresource-crash.md) | Source incompatible/behavioral change | Preview 4          |

docs/core/compatibility/toc.yml

@@ -144,6 +144,8 @@ items:
                 href: windows-forms/10.0/statusstrip-renderer.md
           - name: WPF
             items:
+              - name: Empty ColumnDefinitions and RowDefinitions are disallowed
+                href: wpf/10.0/empty-grid-definitions.md
               - name: Incorrect usage of DynamicResource causes application crash
                 href: wpf/10.0/dynamicresource-crash.md
       - name: .NET 9

docs/core/compatibility/wpf/10.0/empty-grid-definitions.md

@@ -0,0 +1,64 @@
+---
+title: "Breaking change - Empty ColumnDefinitions and RowDefinitions are disallowed"
+description: "Learn about the breaking change in WPF in .NET 10 where empty Grid.ColumnDefinitions or Grid.RowDefinitions declarations now cause MC3063 compilation errors."
+ms.date: 08/11/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/47743
+---
+
+# Empty ColumnDefinitions and RowDefinitions are disallowed
+
+Starting with .NET 10, WPF applications fail to build if `<Grid.ColumnDefinitions>` or `<Grid.RowDefinitions>` are declared but left empty in XAML. This results in error `MC3063`, which indicates that the property doesn't have a value.
+
+## Version introduced
+
+.NET 10 Preview 5
+
+## Previous behavior
+
+Previously, WPF applications with empty `<Grid.ColumnDefinitions>` or `<Grid.RowDefinitions>` compiled successfully, even though the layout definitions were incomplete. The layout defaulted to a single row and column, placing all child elements in that single cell unless otherwise specified.
+
+Example that previously compiled:
+
+```xml
+<Grid>
+  <Grid.ColumnDefinitions>
+  </Grid.ColumnDefinitions>
+</Grid>
+```
+
+## New behavior
+
+Starting in .NET 10, the same code now fails to compile with the following error:
+
+```output
+error MC3063: Property 'ColumnDefinitions' does not have a value.
+```
+
+This occurs when `<Grid.ColumnDefinitions>` or `<Grid.RowDefinitions>` elements are declared but contain no child `<ColumnDefinition />` or `<RowDefinition />` elements.
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+This change is a direct consequence of implementing Grid XAML Shorthand Syntax support.
+
+## Recommended action
+
+Ensure that all `<Grid.ColumnDefinitions>` and `<Grid.RowDefinitions>` contains at least one valid or element.
+
+Corrected example:
+
+```xml
+<Grid>
+  <Grid.ColumnDefinitions>
+    <ColumnDefinition />
+  </Grid.ColumnDefinitions>
+</Grid>
+```
+
+## Affected APIs
+
+None.