Merge main into live

.github/copilot-instructions.md

@@ -1,12 +1,23 @@
 # .NET Documentation Guidelines
 
+## Disclosure
+
+For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. Add the following frontmatter key/value pair:
+
+```markdown
+ai-usage: ai-generated
+```
+
 ## 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.
@@ -16,6 +27,7 @@ Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-g
 - 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.
@@ -26,13 +38,15 @@ Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-g
 - 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:
@@ -43,6 +57,7 @@ To find API doc IDs:
 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.
@@ -52,8 +67,10 @@ For snippets >6 lines:
 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

@@ -835,7 +835,7 @@
                 "_csharplang/proposals/csharp-14.0/null-conditional-assignment.md": "This proposal allows the null conditional operator to be used for the destination of assignment expressions. This allows you to assign a value to a property or field only if the left side is not null.",
                 "_csharplang/proposals/csharp-14.0/extensions.md": "This proposal enables new kinds of extension members. These new extension members support extension properties, extension static members, including extension operators.",
                 "_csharplang/proposals/csharp-14.0/user-defined-compound-assignment.md": "This proposal introduces user-defined compound assignment operators. Developers can override compound assignment, increment, and decrement operators.",
-                "_csharplang/proposals/csharp-14.0/ignored-directives.md": "This proposal allows a source file to include ignored directives. In most cases, ignored directives are used for file based programs, for example `#!`",
+                "_csharplang/proposals/csharp-14.0/ignored-directives.md": "This proposal allows a source file to include ignored directives. In most cases, ignored directives are used for file-based apps, for example `#!`",
                 "_csharplang/proposals/csharp-14.0/extension-operators.md": "This proposal extends the proposal for extensions to include *extension operators*, where an operator can be an extension member.",
                 "_csharplang/proposals/csharp-14.0/named-and-optional-parameters-in-expression-trees.md": "This proposal allows an expression tree to include named and optional parameters. This enables expression trees to be more flexible in how they are constructed.",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "Learn about any breaking changes since the initial release of C# 10 and included in C# 11",
@@ -902,20 +902,25 @@
             "open_to_public_contributors": {
                 "docs/standard/design-guidelines/**.md": false
             },
-            "ms.custom": {
-                "docs/framework/**/*.md": "UpdateFrequency5",
-                "docs/visual-basic/**/*.md": "UpdateFrequency5"
-            },
             "ms.collection": {
-                "docs/ai/**/**.md": "ce-skilling-ai-copilot",
-                "docs/ai/**/**.yml": "ce-skilling-ai-copilot"
+                "docs/ai/**/**.{md,yml}": "ce-skilling-ai-copilot"
             },
             "ms.update-cycle": {
                 "docs/ai/**/**.{md,yml}": "180-days",
-                "docs/csharp/whats-new/**/*.md": "1825-days",
-                "docs/framework/**/*.md": "1825-days",
-                "docs/visual-basic/**/*.md": "1825-days",
-                "docs/framework/additional-apis/pos-for-net/**/**.md": "1825-days"
+                "docs/csharp/whats-new/**/**.{md,yml}": "1095-days",
+                "docs/csharp/advanced-topics/interop/**/**.{md,yml}": "1825-days",
+                "docs/csharp/advanced-topics/reflection-and-attributes/**/**.{md,yml}": "1825-days",
+                "docs/csharp/fundamentals/exceptions/**/**.{md,yml}": "1825-days",
+                "docs/csharp/language-reference/**/**.{md,yml}": "1095-days",
+                "docs/csharp/language-reference/compiler-messages/**/**.{md,yml}": "3650-days",
+                "docs/csharp/language-reference/xmldoc/**/**.{md,yml}": "3650-days",
+                "docs/csharp/linq/**/**.{md,yml}": "1825-days",
+                "docs/csharp/misc/**/**.{md,yml}": "3650-days",
+                "docs/csharp/roslyn-sdk/**/**.{md,yml}": "1825-days",
+                "docs/csharp/specification/**/**.{md,yml}": "1825-days",
+                "docs/framework/**/*.md": "3650-days",
+                "docs/iot/**/**.{md,yml}": "1825-days",
+                "docs/visual-basic/**/**.{md,yml}": "3650-days"
             },
             "no-loc": {
                 "docs/orleans/**/**.md": [

docs/ai/conceptual/how-genai-and-llms-work.md

@@ -46,7 +46,7 @@ For example, given the user input *Give me three ideas for a healthy breakfast i
 
 Some generative AI applications produce image outputs from natural language inputs. Depending on the application and its models, users might be able to specify:
 
-- The people or things to appear the image
+- The people or things to appear in the image
 - The artistic style to create the image in
 - References for generating similar images
 

docs/ai/conceptual/understanding-openai-functions.md

@@ -51,7 +51,7 @@ The Kernel builds the `tools` parameter of a request based on your decorators, o
 
 ## Token counts
 
-Function descriptions are include in the system message of your request to a model. These function descriptions count against your model's [token limit](/azure/ai-services/openai/quotas-limits) and are [included in the cost of the request](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/).
+Function descriptions are included in the system message of your request to a model. These function descriptions count against your model's [token limit](/azure/ai-services/openai/quotas-limits) and are [included in the cost of the request](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/).
 
 If your request exceeds the model's token limit, try the following modifications:
 

docs/ai/conceptual/vector-databases.md

@@ -34,7 +34,7 @@ Vector databases and their search features are especially useful in [RAG pattern
 1. Store and index the embeddings in a vector database or search service.
 1. Convert user prompts from your application to embeddings.
 1. Run a vector search across your data, comparing the user prompt embedding to the embeddings your database.
-1. Use a language model such as GPT-35 or GPT-4 to assembly a user friendly completion from the vector search results.
+1. Use a language model such as GPT-35 or GPT-4 to assemble a user friendly completion from the vector search results.
 
 Visit the [Implement Azure OpenAI with RAG using vector search in a .NET app](../tutorials/tutorial-ai-vector-search.md) tutorial for a hands-on example of this flow.
 

docs/ai/conceptual/zero-shot-learning.md

@@ -32,7 +32,7 @@ Intent:
 
 There are two primary use cases for zero-shot learning:
 
-- **Work with fined-tuned LLMs** - Because it relies on the model's existing knowledge, zero-shot learning is not as resource-intensive as few-shot learning, and it works well with LLMs that have already been fined-tuned on instruction datasets. You might be able to rely solely on zero-shot learning and keep costs relatively low.
+- **Work with fined-tuned LLMs** - Because it relies on the model's existing knowledge, zero-shot learning is not as resource-intensive as few-shot learning, and it works well with LLMs that have already been fine-tuned on instruction datasets. You might be able to rely solely on zero-shot learning and keep costs relatively low.
 - **Establish performance baselines** - Zero-shot learning can help you simulate how your app would perform for actual users. This lets you evaluate various aspects of your model's current performance, such as accuracy or precision. In this case, you typically use zero-shot learning to establish a performance baseline and then experiment with few-shot learning to improve performance.
 
 ## Few-shot learning

docs/ai/get-started-mcp.md

@@ -68,7 +68,7 @@ dotnet add package ModelContextProtocol --prerelease
 
 Instead of building unique connectors for each integration point, you can often leverage or reference prebuilt integrations from various providers such as GitHub and Docker:
 
-- [Available MPC clients](https://modelcontextprotocol.io/clients)
+- [Available MCP clients](https://modelcontextprotocol.io/clients)
 - [Available MCP servers](https://modelcontextprotocol.io/examples)
 
 ### Integration with Microsoft.Extensions.AI

docs/ai/microsoft-extensions-ai.md

@@ -146,7 +146,7 @@ As with other `IChatClient` implementations, the `RateLimitingChatClient` can be
 
 :::code language="csharp" source="snippets/microsoft-extensions-ai/ConsoleAI.CustomClientMiddle/Program.cs":::
 
-To simplify the composition of such components with others, component authors should create a `Use*` extension method for registering the component into a pipeline. For example, consider the following `UseRatingLimiting` extension method:
+To simplify the composition of such components with others, component authors should create a `Use*` extension method for registering the component into a pipeline. For example, consider the following `UseRateLimiting` extension method:
 
 :::code language="csharp" source="snippets/microsoft-extensions-ai/AI.Shared/RateLimitingChatClientExtensions.cs" id="one":::
 

docs/ai/overview.md

@@ -25,7 +25,7 @@ Millions of developers use .NET to create applications that run on the web, on m
 The opportunities with AI are near endless. Here are a few examples of solutions you can build using AI in your .NET applications:
 
 * Language processing: Create virtual agents or chatbots to talk with your data and generate content and images.
-* Computer vision: Identify objects in an object or video.
+* Computer vision: Identify objects in an image or video.
 * Audio generation: Use synthesized voices to interact with customers.
 * Classification: Label the severity of a customer-reported issue.
 * Task automation: Automatically perform the next step in a workflow as tasks are completed.

docs/azure/includes/dotnet-all.md

@@ -414,6 +414,7 @@
 | Speech Extension Telemetry | NuGet [1.45.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Extension.Telemetry/1.45.0) |  |  |
 | System Net Client Model | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/System.Net.ClientModel/1.0.0-beta.1) |  |  |
 | Unknown Display Name | NuGet [0.12.0](https://www.nuget.org/packages/Azure.Iot.Operations.Connector/0.12.0) |  |  |
+| Unknown Display Name | NuGet [0.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Aot/0.1.0-preview.1) |  |  |
 | Unknown Display Name | NuGet [1.1.2-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AzureCosmosDb.Mongo/1.1.2-preview) |  |  |
 | Unknown Display Name | NuGet [1.45.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Extension.MAS/1.45.0) |  |  |
 | Unknown Display Name | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Postgres/1.0.0) |  |  |

docs/core/compatibility/10.0.md

@@ -126,6 +126,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [Renamed parameter in HtmlElement.InsertAdjacentElement](windows-forms/10.0/insertadjacentelement-orientation.md) | Source incompatible | Preview 1 |
 | [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change   | Preview 1 |
 | [StatusStrip uses System RenderMode by default](windows-forms/10.0/statusstrip-renderer.md) | Behavioral change   | Preview 1 |
+| [System.Drawing OutOfMemoryException changed to ExternalException](windows-forms/10.0/system-drawing-outofmemory-externalexception.md) | Behavioral change | Preview 5 |
 
 ## Windows Presentation Foundation (WPF)
 

docs/core/compatibility/toc.yml

@@ -146,6 +146,8 @@ items:
                 href: windows-forms/10.0/treeview-text-location.md
               - name: StatusStrip uses System RenderMode by default
                 href: windows-forms/10.0/statusstrip-renderer.md
+              - name: System.Drawing OutOfMemoryException changed to ExternalException
+                href: windows-forms/10.0/system-drawing-outofmemory-externalexception.md
           - name: WPF
             items:
               - name: Empty ColumnDefinitions and RowDefinitions are disallowed

docs/core/compatibility/windows-forms/10.0/system-drawing-outofmemory-externalexception.md

@@ -0,0 +1,74 @@
+---
+title: "Breaking change: System.Drawing OutOfMemoryException changed to ExternalException"
+description: "Learn about the breaking change in .NET 10 where System.Drawing GDI+ OutOfMemory errors now throw ExternalException instead of OutOfMemoryException."
+ms.date: 08/15/2025
+ai-usage: ai-assisted
+dev_langs:
+- CSharp
+- VB
+---
+
+# System.Drawing OutOfMemoryException changed to ExternalException
+
+GDI+ error handling in System.Drawing has been updated to throw <xref:System.Runtime.InteropServices.ExternalException> instead of <xref:System.OutOfMemoryException> for `Status.OutOfMemory` errors.
+
+## Version introduced
+
+.NET 10 Preview 5
+
+## Previous behavior
+
+When GDI+ encountered `Status.OutOfMemory` errors (often due to invalid input rather than actual memory issues), System.Drawing APIs threw <xref:System.OutOfMemoryException>.
+
+## New behavior
+
+Starting in .NET 10, when GDI+ encounters `Status.OutOfMemory` errors, System.Drawing APIs now throw <xref:System.Runtime.InteropServices.ExternalException>.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+GDI+ isn't particularly good at returning errors when it's unable to create internal objects. There are many cases where object creation fails due to invalid input, and higher-level code gets a null and turns it into `Status.OutOfMemory`. This is frequently a source of confusion since the error is often not related to actual memory issues.
+
+The change to `ExternalException` provides more accurate error reporting, as this exception type is already thrown in other System.Drawing code paths for similar GDI+ errors.
+
+## Recommended action
+
+If your code catches `OutOfMemoryException` when using System.Drawing APIs, ensure you also catch `ExternalException` to handle these GDI+ errors.
+
+```csharp
+try
+{
+    // System.Drawing operations
+}
+catch (ExternalException ex)
+{
+    // Handle GDI+ errors (including former OutOfMemoryException cases)
+}
+catch (OutOfMemoryException ex)
+{
+    // Handle actual memory issues
+}
+```
+
+```vb
+Try
+    ' System.Drawing operations
+Catch ex As ExternalException
+    ' Handle GDI+ errors (including former OutOfMemoryException cases)
+Catch ex As OutOfMemoryException
+    ' Handle actual memory issues
+End Try
+```
+
+## Affected APIs
+
+All System.Drawing APIs that interact with GDI+ and previously could throw `OutOfMemoryException` for `Status.OutOfMemory` errors, including but not limited to:
+
+- <xref:System.Drawing.Bitmap?displayProperty=fullName> constructors and methods
+- <xref:System.Drawing.Graphics?displayProperty=fullName> methods
+- <xref:System.Drawing.Image?displayProperty=fullName> methods
+- <xref:System.Drawing.Icon?displayProperty=fullName> constructors and methods
+- Other System.Drawing types that use GDI+ internally