diff --git a/.github/copilot-issue-verification-action-plan.md b/.github/copilot-issue-verification-action-plan.md new file mode 100644 index 000000000000..d74c96c416f4 --- /dev/null +++ b/.github/copilot-issue-verification-action-plan.md @@ -0,0 +1,220 @@ +--- +ai-usage: ai-assisted +author: tdykstra +ms.author: wpickett +ms.date: 11/13/2025 +--- + +# GitHub issue analysis and action plan prompt for ASP.NET Core documentation + +## Goal +Analyze the GitHub issue and provide a **structured report** determining: +1. Whether the issue is valid and actionable. +2. Whether the issue is within scope of the articles the issue relates to, or if a new article is needed. +3. The exact documentation changes required (if applicable). +4. A clear action plan that can guide PR creation. + +The report should be suitable for posting directly in the issue discussion. + +--- + +## Analysis Steps + +### 1. Information Gathering +Collect and review: +* The **issue title, description, and all comments**. +* The **published documentation** (via the provided URL). +* The **source file(s)** in the repository. +* Any **linked issues, PRs, or external references**. +* **Environment details**: .NET version, tooling versions (VS, VS Code, CLI, EF Core, etc.). +* **Code samples or error messages** mentioned in the issue. + +### 1.5 Source File Analysis +When examining source files: +* **Provide direct GitHub permalinks** to specific lines or sections. +* **Note exact line numbers** for proposed changes. +* **Include line number ranges** in GitHub URLs using `#L-L` format. +* **Quote current content** from specific lines before proposing changes. +* **Use permalinks with commit SHA** when referencing specific versions. + +Example format for file references: +* Single line: `https://github.com/owner/repo/blob/main/file.md#L123`. +* Line range: `https://github.com/owner/repo/blob/main/file.md#L123-L145`. +* Permalink: `https://github.com/owner/repo/blob//file.md#L123`. + +### 2. Validation Criteria +Determine if the issue is: +* **In scope**: Related to ASP.NET Core documentation (not product bugs). +* **Accurate**: The reported problem genuinely exists. +* **Clear**: Sufficient information to take action. +* **Current**: Applies to supported .NET versions. + +### 3. Translation Requirements +If any content is not in English: +* Include the original text in a quote block. +* Provide complete English translation. +* Label clearly as "Original" and "Translation". + +--- + +## Output Format + +### File Naming +`-analysis-report.md` + +### Report Structure + +#### Header +```markdown +## AI Analysis Report +**Analyzed by:** @ +**Date:** +**Issue:** # +**Model:** GitHub Copilot +--- +``` + +#### For Valid Issues + +```markdown +# Issue Analysis: + +## ✅ Issue Validation +**Status:** Valid and actionable + +## 📋 Issue Summary + + +## 📁 Affected Files +| File | Path | Lines | Section | +|------|------|-------|---------| +| Main article | [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) | 123-145 | "Section Heading" | +| Code sample | [`aspnetcore/path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/sample.cs#L45-L67) | 45-67 | `MethodName()` method | + +## 📝 Proposed Changes + +### Documentation Updates +**File:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) +**Location:** Lines 123-145 (after the paragraph containing "[specific anchor text]") +**Type:** [New paragraph / Note block / Code example / Replacement] + +**Current content (lines 123-125):** +```markdown +[Current text that will be replaced or followed] +``` + +**Proposed change:** +```markdown +[Proposed documentation text here] +``` + +### Code Sample Updates (if applicable) +**File:** [`sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) +**Lines:** 45-67 +**Change:** [Add/Modify/Remove] + +**Current code:** +```csharp +// Current code at specified lines +``` + +**Proposed code:** +```csharp +// Proposed code changes +``` + +## 🎯 Action Plan +1. **Edit file:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md) + * Navigate to: [Line 123](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123) + * Find section: "Exact Section Heading" + * After text: "last sentence before insertion point" + * Insert: [!NOTE] block with explanation + +2. **Update sample:** [`path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs) + * Navigate to: [Lines 45-67](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) + * Modify method: `MethodName()` + * Change: Update to use new pattern + +## ⚠️ Considerations +* Verify change applies to .NET [version] +* Check if similar updates needed in related articles +* Consider adding cross-references to [related topic] + +## 🔗 References +* Published article: [URL] +* Related issue: #[number] +* Microsoft Learn docs: [relevant MS docs link] +``` + +#### For Invalid Issues + +```markdown +# Issue Analysis: + +## ❌ Issue Validation +**Status:** Not actionable as is +**Reason:** [Out of scope / Insufficient information / Product issue / Already addressed] + +## 📋 Explanation + + +## 💡 Recommendation +* [Close with explanation] +* [Redirect to appropriate repository] +* [Request additional information] +* [Convert to discussion] + +## 🔗 Alternative Resources +* [Link to relevant documentation] +* [Link to appropriate repository for product issues] +``` + +--- + +## Special Instructions + +### Line Number Guidelines +* **Always inspect the actual source file** to determine accurate line numbers. +* **Provide line ranges** rather than single lines when changes affect multiple lines. +* **Use GitHub's line highlighting** format in URLs (#L123 for single, #L123-L145 for range). +* **Quote the existing content** at those lines to confirm accuracy. +* **Consider context lines** - include a few lines before/after for clarity. +* **Update line numbers** if the file has changed since issue creation. + +### Content Block Usage +Only recommend using special blocks when truly appropriate, they should not be overused: +* `[!IMPORTANT]`: Security issues, breaking changes, data loss risks +* `[!WARNING]`: Common mistakes, deprecation notices +* `[!NOTE]`: Helpful clarifications, version-specific info +* `[!TIP]`: Best practices, productivity hints + +### Code Samples +* Use appropriate language identifier for syntax highlighting. +* Include necessary `using` statements or imports. +* Add comments for complex logic. +* Ensure samples are complete and runnable. + +### Scope Boundaries +**DO:** +* Focus on documentation clarity and accuracy. +* Address missing information. +* Fix technical inaccuracies. +* Improve code samples. + +**DON'T:** +* Attempt to fix product bugs through documentation. +* Make architectural recommendations. +* Add opinions or preferences. +* Modify unrelated sections. + +## Issue labels +* Upon completion of the report, set the `ai-reviewed-issue-reported-action-plan` label for the issue. + +### Common Issue Types +1. **Missing information**: Add clarifying content +2. **Outdated content**: Update to current version +3. **Broken samples**: Fix or replace code +4. **Unclear instructions**: Rewrite for clarity +5. **Missing prerequisites**: Add setup steps + +--- diff --git a/aspnetcore/diagnostics/bl0008.md b/aspnetcore/diagnostics/bl0008.md new file mode 100644 index 000000000000..bf4f33a7a33c --- /dev/null +++ b/aspnetcore/diagnostics/bl0008.md @@ -0,0 +1,90 @@ +--- +title: "BL0008: Component parameters should be auto properties" +ai-usage: ai-assisted +description: "Learn about analysis rule BL0008: Component parameters should be auto properties" +author: guardrex +monikerRange: '>= aspnetcore-8.0' +ms.author: wpickett +ms.date: 11/17/2025 +uid: diagnostics/bl0008 +--- +# BL0008: Component parameters should be auto properties + +| | Value | +| - | - | +| **Rule ID** | BL0008 | +| **Category** | Usage | +| **Fix is breaking or non-breaking** | Non-breaking | + +## Cause + +A property has the [`[SupplyParameterFromForm]` attribute](xref:Microsoft.AspNetCore.Components.SupplyParameterFromFormAttribute) and is initialized with a non-default property initializer. + +## Rule description + +The property initializer can be overwritten with `null` during form submission, causing the `EditForm` to fail with the following exception: + +> :::no-loc text="InvalidOperationException: EditForm requires either a Model parameter, or an EditContext parameter, please provide one of these."::: + +The analyzer warns developers when this pattern is detected, while safely ignoring default value initializers (`null`, `null!`, `default`, `default!`) that don't cause the same issue. + +Consider the following `Input` form model with a property initializer: + +```csharp +[SupplyParameterFromForm] +public InputModel Input { get; set; } = new(); +``` + +The analyzer reports the following warning, where the `{COMPONENT}` placeholder is the component type name: + +> :::no-loc text="Property '{COMPONENT}.Input' has [SupplyParameterFromForm] and a property initializer. This can be overwritten with null during form posts."::: + + Safe patterns that are ignored by analyzer: + +```csharp +[SupplyParameterFromForm] +public InputModel Input { get; set; } = default!; + +[SupplyParameterFromForm] +public InputModel Input { get; set; } = null!; +``` + +## How to fix violations + +To ensure the initialized value isn't overwritten, move the initialization to one of the [`OnInitialized{Async}` lifecycle methods](xref:blazor/components/lifecycle#component-initialization-oninitializedasync). + +Consider the following Razor component that generates a BL0008 code analysis warning because the `Input` model for the form is decorated with `[SupplyParameterFromForm]` and has a property initializer: + +```razor + + ... + + +@code { + [SupplyParameterFromForm] + private InputModel Input { get; set; } = new(); + + private void Submit() + { + ... + } + + public class InputModel + { + public string? Id { get; set; } + } +} +``` + +To fix the violation, the initialization code for the `Input` property is moved to the [`OnInitialized` lifecycle method](xref:blazor/components/lifecycle#component-initialization-oninitializedasync), leaving the property as an [automatically implemented property (*auto property*)](/dotnet/csharp/programming-guide/classes-and-structs/auto-implemented-properties). The following change also makes `Input` a [nullable reference type (NRT)](xref:migration/50-to-60#nullable-reference-types-nrts-and-net-compiler-null-state-static-analysis): + +```csharp +[SupplyParameterFromForm] +private InputModel? Input { get; set; } + +protected override void OnInitialized() => Input ??= new(); +``` + +## When to suppress warnings + +Do not suppress a warning from this rule. diff --git a/aspnetcore/diagnostics/code-analysis.md b/aspnetcore/diagnostics/code-analysis.md index 5e71a9e7dfea..698b7902b6e2 100644 --- a/aspnetcore/diagnostics/code-analysis.md +++ b/aspnetcore/diagnostics/code-analysis.md @@ -50,6 +50,7 @@ Diagnostic ID: * [BL0005](xref:diagnostics/bl0005) * [BL0006](xref:diagnostics/bl0006) * [BL0007](xref:diagnostics/bl0007) +* [BL0008](xref:diagnostics/bl0008) * [MVC1000](xref:diagnostics/mvc1000) * [MVC1001](xref:diagnostics/mvc1001) * [MVC1002](xref:diagnostics/mvc1002) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index 5832d46e6df0..d46b49624b9b 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -1,11 +1,12 @@ --- title: Use HTTP/3 with the ASP.NET Core Kestrel web server +ai-usage: ai-assisted author: wtgodbe description: Learn about using HTTP/3 with Kestrel, the cross-platform web server for ASP.NET Core. monikerRange: '>= aspnetcore-6.0' ms.author: wigodbe ms.custom: mvc, linux-related-content -ms.date: 06/08/2025 +ms.date: 11/13/2025 uid: fundamentals/servers/kestrel/http3 --- @@ -64,6 +65,25 @@ Because not all routers, firewalls, and proxies properly support HTTP/3, HTTP/3 For more information, see . +## Configure QuicTransportOptions + +QUIC transport options can be configured by calling the extension method on . + +:::code language="csharp" source="samples/6.x/KestrelSample/Snippets/Program.cs" id="snippet_UseQuicWithOptions" highlight="3-8"::: + +The following table describes the available . + +| Option | Default | Description | +| ------ | ------- | ----------- | +| | `100` | The maximum number of concurrent bidirectional streams per connection. | +| | `10` | The maximum number of concurrent inbound unidirectional streams per connection. | +| | `1024 * 1024` (1 MB) | The maximum read buffer size in bytes. | +| | `64 * 1024` (64 KB) | The maximum write buffer size in bytes. | +| | `512` | The maximum length of the pending connection queue. | +| | `0x010c` (H3_REQUEST_CANCELLED) | Error code used when the stream should abort the read or write side of the stream internally. | +| | `0x100` (H3_NO_ERROR) | Error code used when an open connection is disposed. | + + ## Alt-svc HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the [`alt-svc`](https://developer.mozilla.org/docs/Web/HTTP/Headers/Alt-Svc) header. That means the first request will normally use HTTP/1.1 or HTTP/2 before switching to HTTP/3. Kestrel automatically adds the `alt-svc` header if HTTP/3 is enabled. diff --git a/aspnetcore/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Snippets/Program.cs b/aspnetcore/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Snippets/Program.cs index 331b5723b84f..511857c41bae 100644 --- a/aspnetcore/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Snippets/Program.cs +++ b/aspnetcore/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Snippets/Program.cs @@ -9,6 +9,7 @@ using Microsoft.AspNetCore.Server.Kestrel.Core; using Microsoft.AspNetCore.Server.Kestrel.Core.Features; using Microsoft.AspNetCore.Server.Kestrel.Https; +using Microsoft.AspNetCore.Server.Kestrel.Transport.Quic; namespace KestrelSample.Snippets; @@ -595,4 +596,27 @@ public static void Http3(string[] args) }); // } + + public static void UseQuicWithOptions(string[] args) + { + // + var builder = WebApplication.CreateBuilder(args); + + builder.WebHost.UseQuic(options => + { +#pragma warning disable CA2252 // Using preview features + options.MaxBidirectionalStreamCount = 200; +#pragma warning restore CA2252 + }); + + builder.WebHost.ConfigureKestrel((context, serverOptions) => + { + serverOptions.ListenAnyIP(5001, listenOptions => + { + listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3; + listenOptions.UseHttps(); + }); + }); + // + } } diff --git a/aspnetcore/includes/not-latest-version-without-not-supported-content.md b/aspnetcore/includes/not-latest-version-without-not-supported-content.md index a7f3e4d4a3a7..be5502c9fed2 100644 --- a/aspnetcore/includes/not-latest-version-without-not-supported-content.md +++ b/aspnetcore/includes/not-latest-version-without-not-supported-content.md @@ -1,14 +1,16 @@ -:::moniker range="< aspnetcore-9.0" +:::moniker range="< aspnetcore-10.0" > [!NOTE] -> This isn't the latest version of this article. For the current release, see the [.NET 9 version of this article](?view=aspnetcore-9.0&preserve-view=true). +> This isn't the latest version of this article. For the current release, see the [.NET 10 version of this article](?view=aspnetcore-10.0&preserve-view=true). :::moniker-end -:::moniker range="> aspnetcore-9.0" + diff --git a/aspnetcore/includes/not-latest-version.md b/aspnetcore/includes/not-latest-version.md index 1eccb5a2b614..6626864643e4 100644 --- a/aspnetcore/includes/not-latest-version.md +++ b/aspnetcore/includes/not-latest-version.md @@ -1,18 +1,20 @@ -:::moniker range="< aspnetcore-9.0" +:::moniker range="< aspnetcore-10.0" > [!NOTE] -> This isn't the latest version of this article. For the current release, see the [.NET 9 version of this article](?view=aspnetcore-9.0&preserve-view=true). +> This isn't the latest version of this article. For the current release, see the [.NET 10 version of this article](?view=aspnetcore-10.0&preserve-view=true). :::moniker-end :::moniker range="= aspnetcore-7.0 || = aspnetcore-5.0 || = aspnetcore-3.0 || = aspnetcore-3.1 || = aspnetcore-2.0" [!INCLUDE[](~/includes/out-of-support.md)] :::moniker-end -:::moniker range="> aspnetcore-9.0" +