Skip to content

Commit 07e171d

Browse files
wadepickettwadepickett
authored
Merge pull request #36353 from dotnet/main
Merge to Live
2 parents 25eaff3 + af8896f commit 07e171d

File tree

8 files changed

+374
-14
lines changed

8 files changed

+374
-14
lines changed

‎.github/copilot-issue-verification-action-plan.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
---
2+
ai-usage: ai-assisted
3+
author: tdykstra
4+
ms.author: wpickett
5+
ms.date: 11/13/2025
6+
---
7+
8+
# GitHub issue analysis and action plan prompt for ASP.NET Core documentation
9+
10+
## Goal
11+
Analyze the GitHub issue and provide a **structured report** determining:
12+
1. Whether the issue is valid and actionable.
13+
2. Whether the issue is within scope of the articles the issue relates to, or if a new article is needed.
14+
3. The exact documentation changes required (if applicable).
15+
4. A clear action plan that can guide PR creation.
16+
17+
The report should be suitable for posting directly in the issue discussion.
18+
19+
---
20+
21+
## Analysis Steps
22+
23+
### 1. Information Gathering
24+
Collect and review:
25+
* The **issue title, description, and all comments**.
26+
* The **published documentation** (via the provided URL).
27+
* The **source file(s)** in the repository.
28+
* Any **linked issues, PRs, or external references**.
29+
* **Environment details**: .NET version, tooling versions (VS, VS Code, CLI, EF Core, etc.).
30+
* **Code samples or error messages** mentioned in the issue.
31+
32+
### 1.5 Source File Analysis
33+
When examining source files:
34+
* **Provide direct GitHub permalinks** to specific lines or sections.
35+
* **Note exact line numbers** for proposed changes.
36+
* **Include line number ranges** in GitHub URLs using `#L<start>-L<end>` format.
37+
* **Quote current content** from specific lines before proposing changes.
38+
* **Use permalinks with commit SHA** when referencing specific versions.
39+
40+
Example format for file references:
41+
* Single line: `https://github.com/owner/repo/blob/main/file.md#L123`.
42+
* Line range: `https://github.com/owner/repo/blob/main/file.md#L123-L145`.
43+
* Permalink: `https://github.com/owner/repo/blob/<commit-sha>/file.md#L123`.
44+
45+
### 2. Validation Criteria
46+
Determine if the issue is:
47+
* **In scope**: Related to ASP.NET Core documentation (not product bugs).
48+
* **Accurate**: The reported problem genuinely exists.
49+
* **Clear**: Sufficient information to take action.
50+
* **Current**: Applies to supported .NET versions.
51+
52+
### 3. Translation Requirements
53+
If any content is not in English:
54+
* Include the original text in a quote block.
55+
* Provide complete English translation.
56+
* Label clearly as "Original" and "Translation".
57+
58+
---
59+
60+
## Output Format
61+
62+
### File Naming
63+
`<issue-number>-analysis-report.md`
64+
65+
### Report Structure
66+
67+
#### Header
68+
```markdown
69+
## AI Analysis Report
70+
**Analyzed by:** @<github-username>
71+
**Date:** <YYYY-MM-DD>
72+
**Issue:** #<issue-number>
73+
**Model:** GitHub Copilot
74+
---
75+
```
76+
77+
#### For Valid Issues
78+
79+
```markdown
80+
# Issue Analysis: <Concise Issue Title>
81+
82+
## ✅ Issue Validation
83+
**Status:** Valid and actionable
84+
85+
## 📋 Issue Summary
86+
<Brief description of the problem and why it needs to be addressed>
87+
88+
## 📁 Affected Files
89+
| File | Path | Lines | Section |
90+
|------|------|-------|---------|
91+
| 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" |
92+
| 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 |
93+
94+
## 📝 Proposed Changes
95+
96+
### Documentation Updates
97+
**File:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145)
98+
**Location:** Lines 123-145 (after the paragraph containing "[specific anchor text]")
99+
**Type:** [New paragraph / Note block / Code example / Replacement]
100+
101+
**Current content (lines 123-125):**
102+
```markdown
103+
[Current text that will be replaced or followed]
104+
```
105+
106+
**Proposed change:**
107+
```markdown
108+
[Proposed documentation text here]
109+
```
110+
111+
### Code Sample Updates (if applicable)
112+
**File:** [`sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67)
113+
**Lines:** 45-67
114+
**Change:** [Add/Modify/Remove]
115+
116+
**Current code:**
117+
```csharp
118+
// Current code at specified lines
119+
```
120+
121+
**Proposed code:**
122+
```csharp
123+
// Proposed code changes
124+
```
125+
126+
## 🎯 Action Plan
127+
1. **Edit file:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md)
128+
* Navigate to: [Line 123](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123)
129+
* Find section: "Exact Section Heading"
130+
* After text: "last sentence before insertion point"
131+
* Insert: [!NOTE] block with explanation
132+
133+
2. **Update sample:** [`path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs)
134+
* Navigate to: [Lines 45-67](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67)
135+
* Modify method: `MethodName()`
136+
* Change: Update to use new pattern
137+
138+
## ⚠️ Considerations
139+
* Verify change applies to .NET [version]
140+
* Check if similar updates needed in related articles
141+
* Consider adding cross-references to [related topic]
142+
143+
## 🔗 References
144+
* Published article: [URL]
145+
* Related issue: #[number]
146+
* Microsoft Learn docs: [relevant MS docs link]
147+
```
148+
149+
#### For Invalid Issues
150+
151+
```markdown
152+
# Issue Analysis: <Issue Title>
153+
154+
## ❌ Issue Validation
155+
**Status:** Not actionable as is
156+
**Reason:** [Out of scope / Insufficient information / Product issue / Already addressed]
157+
158+
## 📋 Explanation
159+
<Clear explanation of why the issue cannot be addressed as documentation>
160+
161+
## 💡 Recommendation
162+
* [Close with explanation]
163+
* [Redirect to appropriate repository]
164+
* [Request additional information]
165+
* [Convert to discussion]
166+
167+
## 🔗 Alternative Resources
168+
* [Link to relevant documentation]
169+
* [Link to appropriate repository for product issues]
170+
```
171+
172+
---
173+
174+
## Special Instructions
175+
176+
### Line Number Guidelines
177+
* **Always inspect the actual source file** to determine accurate line numbers.
178+
* **Provide line ranges** rather than single lines when changes affect multiple lines.
179+
* **Use GitHub's line highlighting** format in URLs (#L123 for single, #L123-L145 for range).
180+
* **Quote the existing content** at those lines to confirm accuracy.
181+
* **Consider context lines** - include a few lines before/after for clarity.
182+
* **Update line numbers** if the file has changed since issue creation.
183+
184+
### Content Block Usage
185+
Only recommend using special blocks when truly appropriate, they should not be overused:
186+
* `[!IMPORTANT]`: Security issues, breaking changes, data loss risks
187+
* `[!WARNING]`: Common mistakes, deprecation notices
188+
* `[!NOTE]`: Helpful clarifications, version-specific info
189+
* `[!TIP]`: Best practices, productivity hints
190+
191+
### Code Samples
192+
* Use appropriate language identifier for syntax highlighting.
193+
* Include necessary `using` statements or imports.
194+
* Add comments for complex logic.
195+
* Ensure samples are complete and runnable.
196+
197+
### Scope Boundaries
198+
**DO:**
199+
* Focus on documentation clarity and accuracy.
200+
* Address missing information.
201+
* Fix technical inaccuracies.
202+
* Improve code samples.
203+
204+
**DON'T:**
205+
* Attempt to fix product bugs through documentation.
206+
* Make architectural recommendations.
207+
* Add opinions or preferences.
208+
* Modify unrelated sections.
209+
210+
## Issue labels
211+
* Upon completion of the report, set the `ai-reviewed-issue-reported-action-plan` label for the issue.
212+
213+
### Common Issue Types
214+
1. **Missing information**: Add clarifying content
215+
2. **Outdated content**: Update to current version
216+
3. **Broken samples**: Fix or replace code
217+
4. **Unclear instructions**: Rewrite for clarity
218+
5. **Missing prerequisites**: Add setup steps
219+
220+
---

‎aspnetcore/diagnostics/bl0008.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: "BL0008: Component parameters should be auto properties"
3+
ai-usage: ai-assisted
4+
description: "Learn about analysis rule BL0008: Component parameters should be auto properties"
5+
author: guardrex
6+
monikerRange: '>= aspnetcore-8.0'
7+
ms.author: wpickett
8+
ms.date: 11/17/2025
9+
uid: diagnostics/bl0008
10+
---
11+
# BL0008: Component parameters should be auto properties
12+
13+
| | Value |
14+
| - | - |
15+
| **Rule ID** | BL0008 |
16+
| **Category** | Usage |
17+
| **Fix is breaking or non-breaking** | Non-breaking |
18+
19+
## Cause
20+
21+
A property has the [`[SupplyParameterFromForm]` attribute](xref:Microsoft.AspNetCore.Components.SupplyParameterFromFormAttribute) and is initialized with a non-default property initializer.
22+
23+
## Rule description
24+
25+
The property initializer can be overwritten with `null` during form submission, causing the `EditForm` to fail with the following exception:
26+
27+
> :::no-loc text="InvalidOperationException: EditForm requires either a Model parameter, or an EditContext parameter, please provide one of these.":::
28+
29+
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.
30+
31+
Consider the following `Input` form model with a property initializer:
32+
33+
```csharp
34+
[SupplyParameterFromForm]
35+
public InputModel Input { get; set; } = new();
36+
```
37+
38+
The analyzer reports the following warning, where the `{COMPONENT}` placeholder is the component type name:
39+
40+
> :::no-loc text="Property '{COMPONENT}.Input' has [SupplyParameterFromForm] and a property initializer. This can be overwritten with null during form posts.":::
41+
42+
<span aria-hidden="true">✔️</span> Safe patterns that are ignored by analyzer:
43+
44+
```csharp
45+
[SupplyParameterFromForm]
46+
public InputModel Input { get; set; } = default!;
47+
48+
[SupplyParameterFromForm]
49+
public InputModel Input { get; set; } = null!;
50+
```
51+
52+
## How to fix violations
53+
54+
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).
55+
56+
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:
57+
58+
```razor
59+
<EditForm Model="Input" OnSubmit="Submit" FormName="Starship1">
60+
...
61+
</EditForm>
62+
63+
@code {
64+
[SupplyParameterFromForm]
65+
private InputModel Input { get; set; } = new();
66+
67+
private void Submit()
68+
{
69+
...
70+
}
71+
72+
public class InputModel
73+
{
74+
public string? Id { get; set; }
75+
}
76+
}
77+
```
78+
79+
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):
80+
81+
```csharp
82+
[SupplyParameterFromForm]
83+
private InputModel? Input { get; set; }
84+
85+
protected override void OnInitialized() => Input ??= new();
86+
```
87+
88+
## When to suppress warnings
89+
90+
Do not suppress a warning from this rule.

‎aspnetcore/diagnostics/code-analysis.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ Diagnostic ID:
5050
* [BL0005](xref:diagnostics/bl0005)
5151
* [BL0006](xref:diagnostics/bl0006)
5252
* [BL0007](xref:diagnostics/bl0007)
53+
* [BL0008](xref:diagnostics/bl0008)
5354
* [MVC1000](xref:diagnostics/mvc1000)
5455
* [MVC1001](xref:diagnostics/mvc1001)
5556
* [MVC1002](xref:diagnostics/mvc1002)

‎aspnetcore/fundamentals/servers/kestrel/http3.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
22
title: Use HTTP/3 with the ASP.NET Core Kestrel web server
3+
ai-usage: ai-assisted
34
author: wtgodbe
45
description: Learn about using HTTP/3 with Kestrel, the cross-platform web server for ASP.NET Core.
56
monikerRange: '>= aspnetcore-6.0'
67
ms.author: wigodbe
78
ms.custom: mvc, linux-related-content
8-
ms.date: 06/08/2025
9+
ms.date: 11/13/2025
910
uid: fundamentals/servers/kestrel/http3
1011
---
1112

@@ -64,6 +65,25 @@ Because not all routers, firewalls, and proxies properly support HTTP/3, HTTP/3
6465

6566
For more information, see <xref:fundamentals/servers/kestrel/endpoints>.
6667

68+
## Configure QuicTransportOptions
69+
70+
QUIC transport options can be configured by calling the <xref:Microsoft.AspNetCore.Hosting.WebHostBuilderQuicExtensions.UseQuic%2A> extension method on <xref:Microsoft.AspNetCore.Hosting.IWebHostBuilder>.
71+
72+
:::code language="csharp" source="samples/6.x/KestrelSample/Snippets/Program.cs" id="snippet_UseQuicWithOptions" highlight="3-8":::
73+
74+
The following table describes the available <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions>.
75+
76+
| Option | Default | Description |
77+
| ------ | ------- | ----------- |
78+
| <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions.MaxBidirectionalStreamCount> | `100` | The maximum number of concurrent bidirectional streams per connection. |
79+
| <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions.MaxUnidirectionalStreamCount> | `10` | The maximum number of concurrent inbound unidirectional streams per connection. |
80+
| <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions.MaxReadBufferSize> | `1024 * 1024` (1 MB) | The maximum read buffer size in bytes. |
81+
| <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions.MaxWriteBufferSize> | `64 * 1024` (64 KB) | The maximum write buffer size in bytes. |
82+
| <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions.Backlog> | `512` | The maximum length of the pending connection queue. |
83+
| <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions.DefaultStreamErrorCode> | `0x010c` (H3_REQUEST_CANCELLED) | Error code used when the stream should abort the read or write side of the stream internally. |
84+
| <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.QuicTransportOptions.DefaultCloseErrorCode> | `0x100` (H3_NO_ERROR) | Error code used when an open connection is disposed. |
85+
86+
6787
## Alt-svc
6888

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

‎aspnetcore/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Snippets/Program.cs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
using Microsoft.AspNetCore.Server.Kestrel.Core;
1010
using Microsoft.AspNetCore.Server.Kestrel.Core.Features;
1111
using Microsoft.AspNetCore.Server.Kestrel.Https;
12+
using Microsoft.AspNetCore.Server.Kestrel.Transport.Quic;
1213

1314
namespace KestrelSample.Snippets;
1415

@@ -595,4 +596,27 @@ public static void Http3(string[] args)
595596
});
596597
// </snippet_Http3>
597598
}
599+
600+
public static void UseQuicWithOptions(string[] args)
601+
{
602+
// <snippet_UseQuicWithOptions>
603+
var builder = WebApplication.CreateBuilder(args);
604+
605+
builder.WebHost.UseQuic(options =>
606+
{
607+
#pragma warning disable CA2252 // Using preview features
608+
options.MaxBidirectionalStreamCount = 200;
609+
#pragma warning restore CA2252
610+
});
611+
612+
builder.WebHost.ConfigureKestrel((context, serverOptions) =>
613+
{
614+
serverOptions.ListenAnyIP(5001, listenOptions =>
615+
{
616+
listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
617+
listenOptions.UseHttps();
618+
});
619+
});
620+
// </snippet_UseQuicWithOptions>
621+
}
598622
}

0 commit comments

Comments
 (0)