Add article-freshness-review prompt file

[Copilot]

Adds a manually-invoked Copilot Chat prompt for generating freshness review reports on ASP.NET Core documentation articles.

• New .github/prompts/article-freshness-review.prompt.md — a structured prompt that evaluates articles against moniker range/versioning, frontmatter/metadata, content accuracy, style conventions, and external link validity
• Outputs a standardized Markdown report (Critical/Moderate/Minor issues + summary checklist) for posting in issue discussions
• Does not create PRs or modify files — report-only
• Placeholders in the report template follow repo convention ({UPPER CASE WITH SPACES})

Usage for this prompt:

1. Open a GitHub issue, open Copilot Chat, and paste:

Read and follow all instructions in .github/prompts/article-freshness-review.prompt.md.
Use this issue as context. Generate the freshness review report.

2. Copy the report into the issue discussion. Does NOT create a PR.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>AI prompt: Article freshness review report</issue_title>
<issue_description>Create a standard prompt to use in this repo for determining if an article requires freshness work and then determine if the work required is someting GitHub Copilot could handle:

I am suggesting putting this in a .github/prompt directory. Those are only manually invoked as an opt-n, rather then auto-triggered.

Suggested pathname:
github/prompts/article-freshness-review.prompt.md

Suggested draft of the prompt below this line:

---

description: "Generates a freshness review report for an ASP.NET Core documentation article. Attach this prompt in Copilot Chat, then provide the article URL. The report is for posting in issue discussions — it does NOT create a PR."

ASP.NET Core Article Freshness Review

Usage: Attach this prompt file in Copilot Chat, then type the article URL
(e.g., Review https://learn.microsoft.com/aspnet/core/web-api/action-return-types).
Paste the resulting report into the GitHub issue discussion.
This prompt does NOT create a PR or modify any files.

Instructions

You are reviewing an ASP.NET Core documentation article for freshness and accuracy.

Step 1: Load Context

Read the repository's copilot instruction file for conventions and rules:
copilot-instructions.md

And read the dotnet/docs repository editing instructions:
https://raw.githubusercontent.com/dotnet/docs/refs/heads/main/.github/agents/docseditor.agent.md

Step 2: Review the Article

Review the article provided by the user.

Evaluate it against ALL of the following criteria:

A. Moniker Range & Versioning

• Are there newer APIs, packages, or approaches that supersede what the article describes?
• If so: Is the monikerRange in the frontmatter still appropriate?
• If the article covers a version that is no longer the latest, does it include guidance directing readers to the current version's documentation?

B. Frontmatter & Metadata

• Is ms.date in MM/DD/YYYY format?
• Is the title field listed first, with remaining fields in alphabetical order?
• Are all required metadata fields present?

C. Content Accuracy

• Are code samples correct for the targeted framework version(s)?
• Are NuGet package names and namespaces still valid?
• Are referenced APIs still available and not deprecated in the targeted version?
• Do xref links (xref:) resolve to valid UIDs?

D. Style & Conventions (per copilot-instructions.md)

• Placeholders in code/commands use {UPPER CASE WITH SPACES} format with descriptions in surrounding text.
• Section headers do NOT end with periods.
• Bullet markers use * (not -).
• Links follow the documented conventions (relative for MS Learn, full URL for external).
• Code blocks use :::code snippet references where appropriate.

E. External Links

• Are external URLs likely still valid? (Flag any that point to known-sunset services or archived repos.)

Step 3: Produce the Report

Output a single Markdown report with this EXACT structure:

# Freshness Review Report

**File:** `{file path}`
**Repository:** `dotnet/AspNetCore.Docs`
**Reviewed:** {YYYY-MM-DD}
**Reviewer:** @{reviewer}
**Article URL:** {learn.microsoft.com URL}
**Source URL:** {GitHub source URL}

---

## Verdict: **{Needs Updating | Current — No Changes Needed}**

A verdict of "Needs Updating" requires at least one Critical or Moderate issue.

---

## Critical Issues

{Issues that affect correctness, reader confusion, or discoverability.
Each issue should include:
- **Issue title**
- **Location:** file path and line number(s)
- **Current content:** (quoted)
- **Recommended fix:** (exact replacement text)
- **Rationale:** why this matters}

## Moderate Issues

{Issues that affect style compliance or minor accuracy.
Same sub-structure as Critical.}

## Minor Issues

{Cosmetic or convention-based issues.
Same sub-structure as Critical.}

---

## Summary of Recommended Changes

{A numbered checklist of ALL changes, in order of priority, that can be
used directly as a task list for the PR author.}

Rules

• Do NOT invent issues. If something is correct, say so.
• Do NOT suggest changes outside the scope of the copilot-instructions.md rules and current ASP.NET Core documentation standards.
• If recommending a NOTE or callout, provide the EXACT Markdown to insert including moniker-range fencing if applicable.
• Flag the issue title if it doesn't match the actual file name or path.
• Every recommended change must include the exact "before" and "after" text.</issue_description>

<agent_instructions>The result should be a new prompt file:
github/prompts/article-freshness-review.prompt.md</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes AI prompt: Article freshness review report #36913

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

---

Internal previews

📄 File	🔗 Preview link
.github/prompts/article-freshness-review.prompt.md	ASP.NET Core Article Freshness Review

[wadepickett]

Approved.

[wadepickett]

@tdykstra: Example report output so you can see what this generates. The prompt was applied to a random file I picked, in this case aspnetcore/security/authorization/policies.md. Also note the Copilot Feasibility Assessment section in the report:

Freshness Review Report

File: aspnetcore/security/authorization/policies.md
Repository: dotnet/AspNetCore.Docs
Reviewed: 2026-03-24
Reviewer: @wadepickett
Article URL: https://learn.microsoft.com/aspnet/core/security/authorization/policies
Source URL: https://github.com/dotnet/AspNetCore.Docs/blob/77921885159484b16e9ea1a888b81f8bf88479fc/aspnetcore/security/authorization/policies.md

---

Verdict: Needs Updating

A verdict of "Needs Updating" requires at least one Critical or Moderate issue.

---

Critical Issues

1. Outdated GitHub link to IAuthorizationService.cs (v2.2.4 tag)

• Issue title: GitHub link references deprecated v2.2.4 tag on old uppercase repo name
• Location: aspnetcore/security/authorization/policies.md — within the >= aspnetcore-6.0 moniker section; also repeated in aspnetcore/security/authorization/policies/includes/policies5.md line 17
• Current content:

  The preceding code highlights the two methods of the [IAuthorizationService](https://github.com/dotnet/AspNetCore/blob/v2.2.4/src/Security/Authorization/Core/src/IAuthorizationService.cs).

• Recommended fix:

  The preceding code highlights the two methods of the [IAuthorizationService](https://github.com/dotnet/aspnetcore/blob/main/src/Security/Authorization/Core/src/IAuthorizationService.cs).

• Rationale: The link references the v2.2.4 tag of the old dotnet/AspNetCore (uppercase) repository. The repository was renamed to dotnet/aspnetcore (lowercase). The 6.0+ moniker version of this article should reference a current tag or main branch rather than a v2.2.4 tag from an unsupported version. The same issue exists in the < aspnetcore-6.0 include file (policies5.md line 17), though for that older moniker it is less critical since v2.2.4 is within the targeted range.

2. Article references code samples from 6.0 sample folder only — no .NET 10 samples

• Issue title: All code sample references target .NET 6.0 despite .NET 10 being current GA
• Location: Throughout the >= aspnetcore-6.0 moniker section — all :::code references point to ~/security/authorization/policies/samples/6.0/AuthorizationPoliciesSample/...
• Current content: e.g.,

  :::code language="csharp" source="~/security/authorization/policies/samples/6.0/AuthorizationPoliciesSample/Program.cs" range="20-23,29":::
  

• Recommended fix: Verify whether updated sample projects exist for .NET 10 (the current GA release). If so, add a new >= aspnetcore-10.0 moniker section pointing to .NET 10 samples, and scope the current section to >= aspnetcore-6.0 < aspnetcore-10.0.
• Rationale: .NET 10 is the current LTS release (GA November 2025). The article's monikerRange is '>= aspnetcore-3.1' but all modern-version code samples reference .NET 6.0. Readers on .NET 10 may be seeing outdated patterns.

---

Moderate Issues

3. Inline code comment has plural IAuthorizationHandlers instead of singular IAuthorizationHandler

• Issue title: Typo in inline code comment — plural interface name
• Location: aspnetcore/security/authorization/policies.md — inline code block in the "simplified default implementation" section; also in includes/policies5.md line 55
• Current content:

  // By default this returns an IEnumerable<IAuthorizationHandlers> from DI.

• Recommended fix:

  // By default this returns an IEnumerable<IAuthorizationHandler> from DI.

• Rationale: The actual interface name is IAuthorizationHandler (singular). The plural form IAuthorizationHandlers does not exist in the API and could confuse readers.

4. HTML comment references v2.2.4 tag on old uppercase repo name

• Issue title: HTML comment for IAuthorizationHandler.cs references deprecated URL
• Location: aspnetcore/security/authorization/policies.md and includes/policies5.md — HTML comment before the IAuthorizationHandler interface code block
• Current content:

  <!--The following code is a copy/paste from 
  https://github.com/dotnet/AspNetCore/blob/v2.2.4/src/Security/Authorization/Core/src/IAuthorizationHandler.cs -->

• Recommended fix:

  <!--The following code is a copy/paste from 
  https://github.com/dotnet/aspnetcore/blob/main/src/Security/Authorization/Core/src/IAuthorizationHandler.cs -->

• Rationale: Same case-sensitivity and versioning issue as Critical Issue HostingEngine.Start returns IDisposable. Usage patterns around IDisposable return values should be documented. #1. The HTML comment links to the old uppercase AspNetCore repo at the v2.2.4 tag.

5. No mention of MapGroup authorization pattern from .NET 7+

• Issue title: Missing modern minimal API route group authorization example
• Location: "Apply policies to endpoints" section in the >= aspnetcore-6.0 moniker
• Current content: Only shows RequireAuthorization on individual endpoints.
• Recommended fix: Consider adding a note or example for MapGroup(...).RequireAuthorization("PolicyName") which was introduced in .NET 7.
• Rationale: Many readers using .NET 7+ and .NET 10 would benefit from seeing route group authorization patterns, which are a common modern pattern.

---

Minor Issues

6. Azure AD documentation links use old /azure/active-directory/ path

• Issue title: Azure AD links may use non-canonical path structure
• Location: aspnetcore/security/authorization/policies.md — "Configure the sample" subsection
• Current content:

  Create an [application registration](/azure/active-directory/develop/quickstart-register-app) in your [Microsoft Entra ID tenant](/azure/active-directory/develop/quickstart-create-new-tenant):

• Recommended fix: Verify the links still resolve to canonical URLs. Azure Active Directory was rebranded to Microsoft Entra ID, and the canonical documentation paths may have moved to /azure/entra-id/.... Update if Microsoft has published new canonical paths.
• Rationale: The text correctly says "Microsoft Entra ID" but the link paths still reference the old azure/active-directory structure. While Microsoft likely has redirects, canonical paths should be used.

---

Copilot Feasibility Assessment

Can Copilot handle this freshness update? Partial

Justification:

• The link fixes (Critical HostingEngine.Start returns IDisposable. Usage patterns around IDisposable return values should be documented. #1, Moderate I am ready to translate #4) and the inline code comment fix (Moderate Add how to build in README.md #3) are mechanical and well-defined — Copilot can handle these.
• Verifying Azure AD / Microsoft Entra ID link redirects (Minor Web api migration #6) requires checking current Microsoft docs URL structures — partially automatable.
• Adding .NET 10 sample references (Critical Configuring first article and author block #2) and modern minimal API patterns (Moderate Migrating from ASP.NET MVC5 to MVC6, Part 1 #5) would require:
  • Deep domain knowledge of ASP.NET Core authorization in .NET 10
  • Verifying or creating new sample projects
  • Understanding of moniker-range fencing for multi-version articles
  • Testing code samples against a running application

Recommendation:

• "Assign to Copilot with human review of [sample updates and .NET 10 moniker range changes]" — The link fixes and comment corrections are mechanical, but the sample project updates and version-targeted content additions require domain expertise and code verification.

---

Summary of Recommended Changes

• 1. [Critical] Update the IAuthorizationService GitHub link from https://github.com/dotnet/AspNetCore/blob/v2.2.4/... to https://github.com/dotnet/aspnetcore/blob/main/... (in both the main article and policies5.md)
• 2. [Critical] Evaluate whether .NET 10 authorization samples exist and update moniker ranges and :::code references accordingly
• 3. [Moderate] Fix the inline code comment IEnumerable<IAuthorizationHandlers> → IEnumerable<IAuthorizationHandler> (singular) in both the main article and policies5.md
• 4. [Moderate] Update the HTML comment referencing IAuthorizationHandler.cs to use the correct lowercase repo name and modern branch
• 5. [Moderate] Consider adding MapGroup authorization example for .NET 7+ readers
• 6. [Minor] Verify Azure AD / Microsoft Entra ID documentation links still resolve to canonical URLs and update paths if needed

[wadepickett]

@tdykstra see latest examples of output at the bottom of the discussions.

[wadepickett]

@tdykstra, report output example after addressing metadata/frontmatter concerns:

• ms.date out of date does not assume the article contents are out of date and flags as a minor item to remember to udpate.
• ms.author and author and other frontmatter values are not compared. Copilot would tr to do this on its own assuming it should pattern match even though it was not asked to in the promt. Update the prompt so it would not.

Freshness Review Report

File: aspnetcore/web-api/index.md
Repository: dotnet/AspNetCore.Docs
Reviewed: 2026-03-24
Reviewer: @wadepickett
Article URL: https://learn.microsoft.com/aspnet/core/web-api/
Source URL: https://github.com/dotnet/AspNetCore.Docs/blob/77921885159484b16e9ea1a888b81f8bf88479fc/aspnetcore/web-api/index.md

---

Verdict: Needs Updating

A verdict of "Needs Updating" requires at least one Critical or Moderate issue.

---

Critical Issues

1. The >= aspnetcore-7.0 moniker section references 6.x code samples

• Issue title: Code samples reference 6.x folder in the >= aspnetcore-7.0 moniker range
• Location: aspnetcore/web-api/index.md, throughout the >= aspnetcore-7.0 moniker section (multiple occurrences)
• Current content:

  [!code-csharp[](index/samples/6.x/Controllers/WeatherForecastController.cs?name=snippet_ControllerSignature&highlight=3)]
  [!code-csharp[](index/samples/6.x/Controllers/PetsController.cs?name=snippet_400And201&highlight=10)]
  [!code-csharp[](index/samples/6.x/Controllers/MyControllerBase.cs?name=snippet_MyControllerBase)]
  [!code-csharp[](index/samples/6.x/Program.cs?name=snippet_global&highlight=1-3)]
  [!code-csharp[](index/samples/6.x/Program.cs?name=snippet_l400&highlight=3-23)]
  [!code-csharp[](index/samples/6.x/Program.cs?name=snippet_d400D6&highlight=10)]
  [!code-csharp[](index/samples/6.x/Program.cs?name=snippet_d400D7&highlight=9)]

• Recommended fix: Verify whether a 10.x sample folder exists in the repository. If so, update all references. If not, create or migrate samples for the latest version (10.x) and update references. Example:

  [!code-csharp[](index/samples/10.x/Controllers/WeatherForecastController.cs?name=snippet_ControllerSignature&highlight=3)]

• Rationale: The >= aspnetcore-7.0 moniker range implies coverage through the current stable release (ASP.NET Core 10.0). Per copilot-instructions.md: "Use the latest supported version for examples unless otherwise specified." Readers selecting 10.0 see 6.x sample code, which is misleading.

2. Inconsistent sample version references within the >= aspnetcore-7.0 moniker section

• Issue title: FromServices inference notes reference 7.x samples while all other samples reference 6.x
• Location: aspnetcore/web-api/index.md, within the >= aspnetcore-7.0 moniker range, "FromServices inference notes" subsection
• Current content:

  [!code-csharp[](index/samples/7.x/ApiController/Controllers/MyController.cs?name=snippet)]
  [!code-csharp[](index/samples/7.x/ApiController/Program.cs?name=snippet_dis&highlight=8-11)]

• Recommended fix: When the overall sample version is migrated (see Critical Issue HostingEngine.Start returns IDisposable. Usage patterns around IDisposable return values should be documented. #1), update these to the same version folder for consistency.
• Rationale: Mixed sample folder versions (6.x and 7.x) within the same moniker section suggests an incomplete sample migration and confuses contributors.

---

Moderate Issues

3. Trailing bracket typo in [ApiController] attribute code snippet references

• Issue title: Extra ] in code snippet reference closing
• Location: aspnetcore/web-api/index.md, appears under "Attribute on specific controllers" in the >= aspnetcore-7.0, = aspnetcore-6.0, and >= aspnetcore-3.0 < aspnetcore-6.0 moniker sections
• Current content:

  [!code-csharp[](index/samples/6.x/Controllers/WeatherForecastController.cs?name=snippet_ControllerSignature&highlight=2])]

• Recommended fix:

  [!code-csharp[](index/samples/6.x/Controllers/WeatherForecastController.cs?name=snippet_ControllerSignature&highlight=2)]

  (Remove the extra ] before the closing ).)
• Rationale: The ])] is a syntax error in the snippet reference. The correct closing is )]. This may cause a build warning or render incorrectly.

4. Missing preposition in port tunneling link text

• Issue title: Grammar error in "Additional resources" link text
• Location: aspnetcore/web-api/index.md, "Additional resources" in the >= aspnetcore-7.0 and = aspnetcore-6.0 moniker sections
• Current content:

  * [Use port tunneling Visual Studio to debug web APIs](/connectors/custom-connectors/port-tunneling)

• Recommended fix:

  * [Use port tunneling in Visual Studio to debug web APIs](/connectors/custom-connectors/port-tunneling)

• Rationale: The link text is missing the preposition "in," making it grammatically incorrect and potentially confusing to readers.

5. External RFC links use redirecting tools.ietf.org domain

• Issue title: Authored RFC links point to tools.ietf.org which redirects
• Location: aspnetcore/web-api/index.md, multiple locations across all moniker sections (Markdown links only, not JSON response body examples)
• Current content:

  [RFC 7807 specification](https://tools.ietf.org/html/rfc7807)

• Recommended fix:

  [RFC 7807 specification](https://www.rfc-editor.org/rfc/rfc7807)

  (Do NOT modify the tools.ietf.org URLs inside JSON response body code blocks — those represent actual API runtime output.)
• Rationale: The tools.ietf.org domain redirects to www.rfc-editor.org. Per the prompt's Section E (External Links), flag URLs pointing to known-redirect or sunset services. Only authored Markdown links should be updated.

6. The < aspnetcore-3.0 moniker's [Consumes] section references 3.x samples

• Issue title: Sample version mismatch in < aspnetcore-3.0 moniker section
• Location: aspnetcore/web-api/index.md, < aspnetcore-3.0 moniker range, "Define supported request content types with the [Consumes] attribute" section
• Current content:

  [!code-csharp[](index/samples/3.x/Controllers/ConsumesController.cs?name=snippet_Class)]

• Recommended fix: Verify whether a 2.x version of ConsumesController.cs exists at index/samples/2.x/2.2/Controllers/ConsumesController.cs. If so:

  [!code-csharp[](index/samples/2.x/2.2/Controllers/ConsumesController.cs?name=snippet_Class)]

  If no 2.x version exists, add a comment noting the 3.x sample is used as a cross-version fallback.
• Rationale: The < aspnetcore-3.0 moniker section targets versions 2.1 and 2.2. Referencing a 3.x sample within this section is inconsistent with the targeted version range.

---

Minor Issues

7. ms.date is older than 6 months

• Issue title: Stale ms.date metadata (metadata-only)
• Location: aspnetcore/web-api/index.md, frontmatter line 8
• Current content:

  ms.date: 05/29/2024

• Recommended fix:

  ms.date: 03/24/2026

  (Update to the current date when any changes are made to this file.)
• Rationale: The ms.date is nearly two years old. Per copilot-instructions.md, ms.date should be updated to the current date (MM/DD/YYYY format) when more than 50 characters are changed. This is a metadata-only concern — the old date does not by itself indicate the article content is stale.

---

Copilot Feasibility Assessment

Can Copilot handle this freshness update? Partial

Justification:

• The typo fix (Moderate Add how to build in README.md #3), grammar fix (Moderate I am ready to translate #4), RFC link update (Moderate Migrating from ASP.NET MVC5 to MVC6, Part 1 #5), and ms.date refresh (Minor Review Request #7) are purely mechanical and well-suited for Copilot.
• The sample code version migration (Critical HostingEngine.Start returns IDisposable. Usage patterns around IDisposable return values should be documented. #1, Configuring first article and author block #2) requires verifying that newer sample folders exist in the repository, potentially creating new sample files, and ensuring the code compiles for the targeted framework version. This requires human judgment and possibly running/testing code.
• The < aspnetcore-3.0 sample mismatch (Moderate Web api migration #6) requires checking repository contents for a 2.x version of the file, which Copilot could attempt, but the decision on fallback strategy requires human judgment.

Recommendation:

• "Assign to Copilot with human review of [sample code version migration (Critical HostingEngine.Start returns IDisposable. Usage patterns around IDisposable return values should be documented. #1, Configuring first article and author block #2) and cross-version sample fallback decisions (Moderate Web api migration #6)]" — The metadata, link, typo, and grammar fixes are mechanical, but sample migration requires expert judgment and code verification.

Summary of Recommended Changes

• 1. [Critical] Migrate code sample references in the >= aspnetcore-7.0 moniker from 6.x to the latest version folder (10.x), creating samples if needed
• 2. [Critical] Resolve inconsistent 7.x vs 6.x sample references within the >= aspnetcore-7.0 moniker section — unify to a single latest version
• 3. [Moderate] Fix trailing bracket typo ])] → )] in "Attribute on specific controllers" code snippet references (multiple moniker sections)
• 4. [Moderate] Add missing preposition "in" to port tunneling link text: "Use port tunneling in Visual Studio to debug web APIs"
• 5. [Moderate] Update authored RFC 7807 Markdown links from tools.ietf.org to www.rfc-editor.org (do NOT change JSON response body code blocks)
• 6. [Moderate] Verify and fix the < aspnetcore-3.0 moniker's [Consumes] section to reference 2.x samples instead of 3.x
• 7. [Minor] Update ms.date to 03/24/2026 (or current date at time of update)

[wadepickett]

After some discussion about its helpfulness, we may not choose to use this prompt. I'll leave it here for a few days as we have time to think about it some more. Setting back to draft.