Merge pull request #35934 from dotnet/main

Author: guardrex

.github/copilot-instructions.md

@@ -1,7 +1,7 @@
 ---
 author: wadepickett
 ms.author: wpickett
-ms.date: 07-31-2025
+ms.date: 08-17-2025
 ---
 
 # Copilot Instructions for `dotnet/AspNetCore.Docs`
@@ -31,18 +31,40 @@ When creating a PR for an issue:
   - If you cannot verify, state that explicitly in your output.
 
 ### Links and References
-- Use relative links (for example, `../folder/file.md` or `./file.md`) when referencing files within this repository. Do not use absolute URLs or GitHub web links for internal content.
-- For external links, always remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.).
-  - Example (Microsoft Learn):
-    - Original: `https://learn.microsoft.com/en-us/aspnet/core/blazor/`
-    - Correct: `https://learn.microsoft.com/aspnet/core/blazor/`
-  - Example (Wikipedia):  
-    - Original: `https://en.wikipedia.org/wiki/ASP.NET_Core`
-    - Correct: `https://wikipedia.org/wiki/ASP.NET_Core`
-- For Microsoft Learn links, also strip the base domain (`https://learn.microsoft.com/en-us`) so only the path remains.
-  - Example:  
-    - Original: `https://learn.microsoft.com/en-us/aspnet/core/blazor/`
-    - Correct: `/aspnet/core/blazor/`
+- For cross-references to other articles within the AspNetCore.Docs repository:
+  - Use the xref syntax: `<xref:target-uid>`
+  - The "target-uid" of the xref syntax is obtained from the `uid` property value in the YAML front matter of the article's markdown file
+  - Examples
+    - For a target article `uid` value of `aspnetcore/mvc/overview`, the xref cross-link is `<xref:aspnetcore/mvc/overview>`
+    - For a target article `uid` value of `blazor/index`, the xref cross-link is `<xref:blazor/index>`
+
+- For non-markdown files (files that don't have the `.md` file extension) within this repository, such as PowerShell scripts and code files:
+  - Use relative links with the appropriate file extension
+  - Example: `../build-tools/build.ps1` or `./sample.json`
+
+- For external links to non-Microsoft sites (MDN, W3C, etc.):
+  - Use absolute URLs
+  - Remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.)
+  - Example (MDN):  
+    - Original: `https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event`
+    - Correct: `https://developer.mozilla.org/docs/Web/API/Element/click_event`
+
+- For links to GitHub repositories:
+  - Use the full URL path
+    - Example: `https://github.com/maraf/blazor-wasm-react/blob/main/blazor/Counter.razor`
+    - Example: `https://github.com/dotnet/blazor-samples/blob/main/10.0/BlazorWebAssemblyReact/blazor/Counter.razor`
+  - For other Git hosting services or non-Microsoft domains, use the full URL
+    - Example: `https://gitlab.com/username/repo-name`
+
+- For links to Microsoft Learn content in other repositories:
+  - Use the relative URL starting with a forward slash
+  - Don't include the scheme and the host (example: `https://learn.microsoft.com`) and don't include the locale (example: `en-us`)
+  - Example: For the target Learn website URL `https://learn.microsoft.com/en-us/dotnet/core/introduction`, use the relative URL `/dotnet/core/introduction` for the link destination
+
+- Never use physical .md file paths in published content
+  - Wrong: `../blazor/index.md` or `/aspnet/core/blazor/index.md`
+  - Correct: `<xref:blazor/index>`
+  - Exception: GitHub-only content (such as README files, contributing guidelines, and other repository documentation that isn't published to learn.microsoft.com) should use an absolute URL to the markdown file (`.md` file extension)
 
 ## Repository-Specific Guidelines
 - Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
@@ -54,14 +76,37 @@ When creating a PR for an issue:
   - For any new or updated .md file added to the repository, ensure the following frontmatter (metadata) is included:
     - Metadata `ai-usage: ai-assisted` if any AI assistance was used
     - Place the title metadata first, followed by the remaining metadata lines in alphabetical order. Example: `title`, `author`, `description`, `monikerRange`, `ms.author`, `ms.custom`, `ms.date`, `uid`, `zone_pivot_groups`
-    - Metadata `ms.date: <today's date>` with a format of MM-DD-YYYY.  If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters are changed in the file.
+    - Metadata `ms.date: <today's date>` with a format of MM/DD/YYYY. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters are changed in the file.
 
 ### Version Targeting Common Range Patterns
 - Fixed Range: `>= aspnetcore-7.0 <= aspnetcore-9.0`
 - Open Upper Bound: `>= aspnetcore-7.0`
 - Open Lower Bound: `<= aspnetcore-9.0`
 - Specific Version: `== aspnetcore-9.0`
 
+### Handling File Redirections
+- When a Markdown (.md) article file (this does not apply to includes) is deleted in a PR, create a redirection entry.
+- Redirections ensure users following existing links aren't left with broken links
+- To add a redirection:
+  1. Update the `.openpublishing.redirection.json` file at the repository root
+  2. Follow this format for new entries:
+     ```json
+     {
+         "source_path": "aspnetcore/path/to/deleted-file.md",
+         "redirect_url": "/aspnet/core/path/to/target-file",
+         "redirect_document_id": false
+     }
+     ```
+  3. Use relative URLs for redirection to pages in the `learn.microsoft.com` domain
+     - Example: `/aspnet/core/path/to/target-file`
+  4. For URLs in a different domain, use absolute URLs including the domain.
+     - Example: `https://learn.microsoft.com/dotnet/core/introduction`
+  5. Set `redirect_document_id` to `false` unless specifically instructed otherwise
+  6. Maintain alphabetical order of the `source_path` entries for better organization
+  7. Ensure proper JSON formatting with correct commas between entries
+- When selecting a redirect target, choose the most relevant existing content that would serve the user's original intent
+- If no direct replacement exists, redirect to a parent category page or related topic
+    
 ### Code Snippets
 - For code snippets longer than 6 lines:
   1. Create a subfolder named after the document the snippet supports.
@@ -90,15 +135,15 @@ When creating a PR for an issue:
 - Use the following language code and indentation standards for markdown code blocks or the `language` attribute of code snippets:
 
   Content of the snippet | Language code | Indentation in spaces
-  :---: | :---: | :---:
-  C# | csharp | 4
-  HTML | html | 4
-  CSS | css | 4
-  JavaScript | javascript | 2 spaces (use 4 spaces for line continuation)
-  XML | xml | 2
-  JSON | json | 2
-  Console | console | 2
-  Text | - | 2
+  :--------------------: | :-----------: | :-------------------:
+  C#                     | csharp        | 4
+  HTML                   | html          | 4
+  CSS                    | css           | 4
+  JavaScript             | javascript    | 2 spaces (use 4 spaces for line continuation)
+  XML                    | xml           | 2
+  JSON                   | json          | 2
+  Console                | console       | 2
+  Text                   | -             | 2
 
 ### ASP.NET Core Specific Guidelines
 - Use the latest supported version for examples unless otherwise specified

.openpublishing.redirection.json

@@ -1628,6 +1628,31 @@
             "source_path": "aspnetcore/blazor/state-management.md",
             "redirect_url": "/aspnet/core/state-management/",
             "redirect_document_id": false
+        },
+        {
+            "source_path": "aspnetcore/fundamentals/includes/apis6.md",
+            "redirect_url": "/aspnet/core/fundamentals/apis",
+            "redirect_document_id": false
+        },
+        {
+            "source_path": "aspnetcore/fundamentals/minimal-apis/handle-errors.md",
+            "redirect_url": "/aspnet/core/fundamentals/error-handling-api",
+            "redirect_document_id": false
+        },
+        {
+            "source_path": "aspnetcore/fundamentals/minimal-apis/overview.md",
+            "redirect_url": "/aspnet/core/fundamentals/apis",
+            "redirect_document_id": false
+        },
+        {
+            "source_path": "aspnetcore/web-api/handle-errors.md",
+            "redirect_url": "/aspnet/core/fundamentals/error-handling-api",
+            "redirect_document_id": false
+        },
+        {
+            "source_path": "aspnetcore/fundamentals/handle-errors.md",
+            "redirect_url": "/aspnet/core/fundamentals/error-handling-api",
+            "redirect_document_id": false
         }
     ]
 }

aspnetcore/blazor/components/component-disposal.md

@@ -12,7 +12,7 @@ uid: blazor/components/component-disposal
 
 [!INCLUDE[](~/includes/not-latest-version.md)]
 
-This article explains the ASP.NET Core Razor component disposal with with <xref:System.IDisposable> and <xref:System.IAsyncDisposable>.
+This article explains the ASP.NET Core Razor component disposal process with <xref:System.IDisposable> and <xref:System.IAsyncDisposable>.
 
 If a component implements <xref:System.IDisposable> or <xref:System.IAsyncDisposable>, the framework calls for resource disposal when the component is removed from the UI. Don't rely on the exact timing of when these methods are executed. For example, <xref:System.IAsyncDisposable> can be triggered before or after an asynchronous <xref:System.Threading.Tasks.Task> awaited in [`OnInitalizedAsync`](xref:blazor/components/lifecycle#component-initialization-oninitializedasync) or [`OnParametersSetAsync`](xref:blazor/components/lifecycle#after-parameters-are-set-onparameterssetasync) is called or completes. Also, object disposal code shouldn't assume that objects created during initialization or other lifecycle methods exist.
 

aspnetcore/blazor/forms/validation.md

@@ -597,7 +597,7 @@ app.MapDefaultControllerRoute();
 For more information on controller routing and validation failure error responses, see the following resources:
 
 * <xref:mvc/controllers/routing>
-* <xref:web-api/handle-errors#validation-failure-error-response>
+* <xref:fundamentals/error-handling-api#validation-failure-error-response>
 
 In the `.Client` project, add the `CustomValidation` component shown in the [Validator components](#validator-components) section. Update the namespace to match the app (for example, `namespace BlazorSample.Client`).
 

aspnetcore/blazor/host-and-deploy/index.md

@@ -133,10 +133,7 @@ When `WasmBundlerFriendlyBootConfig` is enabled, the produced JS contains `impor
 
 The following sample apps are based on [Rollup](https://rollupjs.org/). Similar concepts apply when using other JS bundlers.
 
-Demonstration sample apps:
-
-* [Blazor WASM in a React application (`maraf/blazor-wasm-react` GitHub repository)](https://github.com/maraf/blazor-wasm-react)
-* [.NET on WASM in a React component sample (`maraf/dotnet-wasm-react` GitHub repository)](https://github.com/maraf/dotnet-wasm-react)
+Demonstration sample apps for Blazor WebAssembly in a React app (`BlazorWebAssemblyReact`) and .NET on WebAssembly in a React app (`DotNetWebAssemblyReact`) for .NET 10 or later are available in the [Blazor samples GitHub repository (`dotnet/blazor-samples`)](https://github.com/dotnet/blazor-samples).
 
 :::moniker-end
 

aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md

@@ -462,8 +462,8 @@ IJSRuntime JS { get; set; }
 
 Create an instance of a JS object using a constructor function and get the <xref:Microsoft.JSInterop.IJSObjectReference>/<xref:Microsoft.JSInterop.IJSInProcessObjectReference> .NET handle for referencing the instance with the following API:
 
-* `InvokeNewAsync` (asynchronous)
-* `InvokeNew` (synchronous)
+* `InvokeConstructorAsync` (asynchronous)
+* `InvokeConstructor` (synchronous)
 
 Examples in this section demonstrate the API calls with the following `TestClass` with a constructor function (`constructor(text)`):
 
@@ -479,25 +479,25 @@ window.TestClass = class {
 }
 ```
 
-### Asynchronous `InvokeNewAsync`
+### Asynchronous `InvokeConstructorAsync`
 
-Use `InvokeNewAsync(string identifier, object?[]? args)` on <xref:Microsoft.JSInterop.IJSRuntime> and <xref:Microsoft.JSInterop.IJSObjectReference> to invoke the specified JS constructor function asynchronously. The function is invoked with the `new` operator. In the following example, `TestClass` contains a constructor function, and `classRef` is an <xref:Microsoft.JSInterop.IJSObjectReference>.
+Use `InvokeConstructorAsync(string identifier, object?[]? args)` on <xref:Microsoft.JSInterop.IJSRuntime> and <xref:Microsoft.JSInterop.IJSObjectReference> to invoke the specified JS constructor function asynchronously. The function is invoked with the `new` operator. In the following example, `TestClass` contains a constructor function, and `classRef` is an <xref:Microsoft.JSInterop.IJSObjectReference>.
 
 ```csharp
-var classRef = await JSRuntime.InvokeNewAsync("TestClass", "Blazor!");
+var classRef = await JSRuntime.InvokeConstructorAsync("TestClass", "Blazor!");
 var text = await classRef.GetValueAsync<string>("text");
 var textLength = await classRef.InvokeAsync<int>("getTextLength");
 ```
 
 An overload is available that takes a <xref:System.Threading.CancellationToken> argument or <xref:System.TimeSpan> timeout argument.
 
-### Synchronous `InvokeNew`
+### Synchronous `InvokeConstructor`
 
-Use `InvokeNew(string identifier, object?[]? args)` on <xref:Microsoft.JSInterop.IJSInProcessRuntime> and <xref:Microsoft.JSInterop.IJSInProcessObjectReference> to invoke the specified JS constructor function synchronously. The function is invoked with the `new` operator. In the following example, `TestClass` contains a constructor function, and `classRef` is an <xref:Microsoft.JSInterop.IJSInProcessObjectReference>:
+Use `InvokeConstructor(string identifier, object?[]? args)` on <xref:Microsoft.JSInterop.IJSInProcessRuntime> and <xref:Microsoft.JSInterop.IJSInProcessObjectReference> to invoke the specified JS constructor function synchronously. The function is invoked with the `new` operator. In the following example, `TestClass` contains a constructor function, and `classRef` is an <xref:Microsoft.JSInterop.IJSInProcessObjectReference>:
 
 ```csharp
 var inProcRuntime = ((IJSInProcessRuntime)JSRuntime);
-var classRef = inProcRuntime.InvokeNew("TestClass", "Blazor!");
+var classRef = inProcRuntime.InvokeConstructor("TestClass", "Blazor!");
 var text = classRef.GetValue<string>("text");
 var textLength = classRef.Invoke<int>("getTextLength");
 ```
@@ -630,7 +630,7 @@ In server-side scenarios, JS interop calls can't be issued after Blazor's Signal
   * <xref:Microsoft.JSInterop.IJSRuntime.InvokeAsync%2A?displayProperty=nameWithType>
   * <xref:Microsoft.JSInterop.JSRuntimeExtensions.InvokeAsync%2A?displayProperty=nameWithType>
   * <xref:Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync%2A?displayProperty=nameWithType>
-  * `InvokeNewAsync`
+  * `InvokeConstructorAsync`
   * `GetValueAsync`
   * `SetValueAsync`
 * `Dispose`/`DisposeAsync` calls on any <xref:Microsoft.JSInterop.IJSObjectReference>.

aspnetcore/blazor/javascript-interoperability/index.md

@@ -337,7 +337,7 @@ JavaScript (JS) interop calls can't be issued after Blazor's SignalR circuit is
   * <xref:Microsoft.JSInterop.IJSRuntime.InvokeAsync%2A?displayProperty=nameWithType>
   * <xref:Microsoft.JSInterop.JSRuntimeExtensions.InvokeAsync%2A?displayProperty=nameWithType>
   * <xref:Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync%2A?displayProperty=nameWithType>
-  * `InvokeNewAsync`
+  * `InvokeConstructorAsync`
   * `GetValueAsync`
   * `SetValueAsync`
 * `Dispose`/`DisposeAsync` calls on any <xref:Microsoft.JSInterop.IJSObjectReference>.

aspnetcore/blazor/project-structure.md

@@ -600,6 +600,12 @@ In a Blazor WebAssembly app, the Blazor script content is located in the `wwwroo
 <script src="_framework/blazor.webassembly.js"></script>
 ```
 
+For a Blazor Web App or a Blazor Server app, the project must contain at least one Razor component file (`.razor`) in order to automatically include the Blazor script when the app is published. If the project doesn't contain at least one Razor component, set the `RequiresAspNetWebAssets` MSBuild property `true` in the app's project file to include the Blazor script:
+
+```xml
+<RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>
+```
+
 ## Location of `<head>` and `<body>` content
 
 :::moniker range=">= aspnetcore-8.0"
@@ -642,7 +648,7 @@ To create an app that can run as either a Blazor Server app or a Blazor WebAssem
 
 * <xref:blazor/tooling>
 * <xref:blazor/hosting-models>
-* <xref:fundamentals/minimal-apis/overview>
+* <xref:fundamentals/apis>
 * [Blazor samples GitHub repository (`dotnet/blazor-samples`)](https://github.com/dotnet/blazor-samples) ([how to download](xref:blazor/fundamentals/index#sample-apps))
 
 :::moniker-end