Skip to content

Add conceptual documentation for new .NET Extensions packages#49372

Merged
gewarren merged 22 commits intomainfrom
copilot/add-docs-for-dotnet-extensions
Feb 27, 2026
Merged

Add conceptual documentation for new .NET Extensions packages#49372
gewarren merged 22 commits intomainfrom
copilot/add-docs-for-dotnet-extensions

Conversation

Copy link
Contributor

Copilot AI commented Oct 20, 2025

  • Explore repository structure and existing .NET Extensions documentation
  • Research packages to be documented
  • Create conceptual article for Microsoft.Extensions.DependencyInjection.AutoActivation
  • Create conceptual article for Microsoft.Extensions.AsyncState
  • Create conceptual article for Microsoft.Extensions.AmbientMetadata.Application
  • Create conceptual article for Microsoft.Extensions.TimeProvider.Testing
  • Create conceptual article for Microsoft.Extensions.AuditReports
  • Update TOC to include new articles
  • Validate articles for style and standards compliance
  • Address feedback: Fix IAsyncState references to use non-generic interface
  • Address review feedback on extracted code samples (NET 10, Task.Yield, required properties)
  • Address @gewarren review comments:
    • Updated all package versions to 10.0.0 across all articles
    • Fixed IAsyncState section (removed incorrect code with non-existent .Value property)
    • Fixed best practices descriptions in async-state.md
    • Fixed Metrics/Compliance/Metadata report descriptions in audit-reports.md
    • Removed localization-problematic code comments from inline code blocks
    • Fixed :::code source paths in auto-activation.md (added ../ for new subdirectory location)
  • Extract remaining inline code samples to compiled projects (ambient-metadata-application, timeprovider-testing, audit-reports)

Summary

All review feedback addressed. All package versions updated to 10.0.0. Documentation style improved per Microsoft style guide.

Original prompt

This section details on the original issue you should resolve

<issue_title>[Epic] Docs for new .NET Extensions</issue_title>
<issue_description>The following issue serves as an Epic, capturing task (issues) for individual work, such as but not limited to, conceptualizing and reasoning about various aspects of programming for .NET with numerous NuGet packages. Each package extends workload-agnostic cloud-native primitives, and fundamental building blocks for creating resilient, diagnostic-empowered, and robust features like health-checks and dependency injection (DI) auto-activation.

Each conceptual article with be interleaved into an appropriate section (or sub-section) of the existing .NET libraries content.

Important
The following two subsets, track currently published NuGet packages, publicly available in a prerelease state. If they're not listed here, then they're not going to have a conceptual article written for them:

.NET Extensions:

ASP.NET Core:

I'm going to tag @Rick-Anderson here, who from the ASP.NET Docs team can write a new conceptual article for the following NuGet package?

<agent_instructions>Please continue work on this issue, the task list has links to NuGet packages that need to have corresponding conceptual content. Please start creating new articles next to the existing ones under .NET Fundamentals / Extensions. These packages are a result of the: https://github.com/dotnet/extensions repo. Use that as a source of truth.</agent_instructions>

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

Fixes #37411


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.


Internal previews

📄 File 🔗 Preview link
docs/core/extensions/async-state.md Asynchronous state management
docs/core/extensions/audit-reports.md Example GitHub Actions workflow
docs/core/extensions/dependency-injection/auto-activation.md Dependency injection auto-activation
docs/core/extensions/file-globbing.md File globbing in .NET
docs/core/extensions/timeprovider-testing.md Testing with FakeTimeProvider
docs/fundamentals/toc.yml docs/fundamentals/toc

@dotnet-policy-service dotnet-policy-service bot added okr-curation OKR: Curate content to remove outdated recommendations okr-freshness OKR: Freshness of content 🏁 Release: .NET 8 Work items for the .NET 8 release labels Oct 20, 2025
@dotnet-policy-service dotnet-policy-service bot added dotnet-fundamentals/svc okr-quality Content-quality KR: Concerns article defects (bugs), freshness, or build warnings. labels Oct 20, 2025
Copilot AI changed the title [WIP] Add documentation for new .NET extensions Add conceptual documentation for new .NET Extensions packages Oct 20, 2025
Copilot AI requested a review from IEvangelist October 20, 2025 15:54
Copy link
Member

@IEvangelist IEvangelist left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @copilot - This looks good so far, but I'm seeing the IAsyncState<T> doesn't exist. Instead it's simply IAsyncState, please see my ssuggestions.

@IEvangelist
Copy link
Member

@copilot please address my feedback

Copy link
Contributor Author

Copilot AI commented Oct 20, 2025

@copilot please address my feedback

Fixed in commit 4c82751. Updated all references from IAsyncState<T> to IAsyncState throughout the async-state.md article.

@BillWagner
Copy link
Member

@copilot

Separate the code samples that are inline in the markdown files into compiled projects. See this section of the copilot instructions for details.

@BillWagner BillWagner dismissed their stale review February 17, 2026 20:58

This set of review comments has been addressed

@gewarren gewarren assigned gewarren and unassigned BillWagner Feb 26, 2026
…ode comments, and :::code paths

Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>
@gewarren gewarren marked this pull request as ready for review February 26, 2026 23:49
@gewarren gewarren requested a review from a team as a code owner February 26, 2026 23:49
Copilot AI review requested due to automatic review settings February 26, 2026 23:49
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds new conceptual documentation pages for recently introduced .NET Extensions packages and wires them into the .NET fundamentals table of contents, along with compiled snippet projects for some of the new articles.

Changes:

  • Adds new conceptual articles for AsyncState, DI auto-activation, TimeProvider testing (FakeTimeProvider), and AuditReports.
  • Updates docs/fundamentals/toc.yml to include the new Extensions content.
  • Adds new snippet projects under docs/core/extensions/snippets/... to support the new docs.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 16 comments.

Show a summary per file
File Description
docs/fundamentals/toc.yml Adds TOC entries for the new Extensions articles.
docs/core/extensions/timeprovider-testing.md New conceptual article for Microsoft.Extensions.TimeProvider.Testing and FakeTimeProvider.
docs/core/extensions/audit-reports.md New conceptual article for Microsoft.Extensions.AuditReports and MSBuild report generation.
docs/core/extensions/async-state.md New conceptual article for Microsoft.Extensions.AsyncState.
docs/core/extensions/dependency-injection/auto-activation.md New conceptual article for Microsoft.Extensions.DependencyInjection.AutoActivation.
docs/core/extensions/file-globbing.md Minor formatting/link update for the FileSystemGlobbing package reference.
docs/core/extensions/snippets/dependency-injection-auto-activation/** New compiled snippet projects for auto-activation examples.
docs/core/extensions/snippets/async-state/** New compiled snippet projects for async state examples.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great. I had a number of comments around the code. Most of them are to use primary constructors: Many of these types are the primary use case for primary ctors: A type that requires one or more dependencies as part of its initialization.

Also, many of the same project files use .NET 9 instead of .NET 10 (which all the code uses). That should be consistent.

Once you've looked at the comments, :shipit:

gewarren and others added 4 commits February 27, 2026 10:42
Co-authored-by: Bill Wagner <wiwagn@microsoft.com>
…otnet/docs into copilot/add-docs-for-dotnet-extensions
@gewarren gewarren mentioned this pull request Feb 27, 2026
14 tasks
@gewarren gewarren enabled auto-merge (squash) February 27, 2026 18:48
@gewarren gewarren merged commit 4b4f3c4 into main Feb 27, 2026
11 checks passed
@gewarren gewarren deleted the copilot/add-docs-for-dotnet-extensions branch February 27, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🏁 Release: .NET 8 Work items for the .NET 8 release dotnet-fundamentals/svc okr-curation OKR: Curate content to remove outdated recommendations okr-freshness OKR: Freshness of content okr-quality Content-quality KR: Concerns article defects (bugs), freshness, or build warnings.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Epic] Docs for new .NET Extensions

6 participants