Modernize Examples for the current release wave

[tillig]

I just shipped updated versions across all the Autofac libraries, and this repo has fallen behind far enough that several examples no longer reflect what we actually publish. This issue tracks getting it current, gating it so it stays current, and closing the biggest coverage gaps.

Why this is more than a version bump

Three findings from the audit shape the work:

The .NET Framework integration packages target net481 now. Confirmed at the release tags — Autofac.Mvc5 v7.0.0, Autofac.Wcf v8.0.0, Autofac.Web v8.0.0, Autofac.Owin v8.0.0. The six net472 projects in here cannot take current packages without retargeting. They are also the furthest behind: still on Autofac 6.5.0 against a current 9.3.2.

Four org repos have no published package, so they can't have copy-pasteable examples: Autofac.Analyzers, Autofac.AspNetCore, Autofac.Extensions.Hosting, Autofac.Extras.AggregateService.SourceGenerator. Notably that rules out using our own analyzer package to raise code quality in here.

dotnet format fails today — missing UTF-8 BOM in the three ASP.NET Core projects, import ordering, final newlines, and one whitespace error. All auto-fixable, but it means adding the CI gate and fixing the code have to land together.

Two bugs also turned up that have nothing to do with modernization:

• WebFormsExample.csproj sets RootNamespace and AssemblyName to MvcExample. Combined with OutputPath=bin/ and AppendTargetFrameworkToOutputPath=false, its output collides with the real MvcExample.
• ci.yml triggers on develop and gates pull requests against develop, but this repo only has main — it's one of our non-Gitflow repos. PR builds never fire.

Decisions

Recording these so the tasks below don't get relitigated:

• Retarget the legacy examples to net481 rather than freezing them on Autofac 6.x. Examples that don't match what we ship are worse than no examples.
• Keep CI local to this repo. The org's shared ci.yml assumes default.proj, a codecov upload, and NuGet publishing — none of which apply to a repo with no packages and no tests. Adding inputs for a single consumer isn't worth the conditional complexity.
• .editorconfig plus AnalysisLevel=latest-recommended, and no StyleCop. Nullable on, warnings-as-errors in Release. StyleCop wants file headers and XML docs on public members, which is a lot of ceremony wrapped around ten-line teaching samples.
• No test projects except where testing is the point. The Moq and FakeItEasy examples are the only ones that should carry tests, and both are deferred below.

Work

Ordered, because they stack. Each lands as its own pull request against main.

• 1. Root config refresh. Replace .editorconfig with the current one from the core repo (ours is the pre-2020 version — no per-filetype sections, no dotnet_diagnostic severities). Add .markdownlint.json; pre-commit runs markdownlint with no config today. Bump the markdownlint hook to v0.49.1 to match core. Relax the global.json pin from 10.0.203 to 10.0.100 so any 10.0 SDK can build this. Fix the develop triggers in ci.yml. Clean up the README: dead AppVeyor badge, Examples.sln should be Examples.slnx, and it still advertises a ServiceFabric example that was deleted in cae30c6. Verify: pre-commit run --all-files is clean.
• 2. CI gates. Add dotnet format and pre-commit jobs to build.yml, mirroring the org workflow's job bodies minus the default.proj, codecov, and publish steps. The format job needs windows-latest — net481 projects won't restore on Linux. Also port the org workflow's gate job: Refresh root configuration and normalize the repo #33 built twice for one commit, once for the branch push and once for the pull request, and adding two more jobs would triple that waste. Verify: all jobs run, fail loudly on a deliberate violation, and only one run happens per change.
• 3. Dependency updates, net10.0 projects. Autofac and the integration packages to current, plus Microsoft.Extensions.*. Split from the retarget below so a net481 surprise can't block the modern examples. Verify: dotnet build Examples.slnx -c Release clean.
• 4. Retarget net472 → net481. All six legacy projects, with every Autofac package to current, plus Microsoft.AspNet.Mvc, Newtonsoft.Json, Microsoft.Bcl.AsyncInterfaces, and Microsoft.NETFramework.ReferenceAssemblies. Verify: dotnet build Examples.slnx -c Release clean on Windows.
• 5. Code standards pass. Add a root Directory.Build.props — there is none today — carrying Nullable, ImplicitUsings, EnforceCodeStyleInBuild, AnalysisLevel, and TreatWarningsAsErrors in Release, so policy lives in one place instead of fifteen csproj files. Then fix the fallout: file-scoped namespaces everywhere (ccd9b35 claimed to do this but GenericHostBuilderExample, AttributeMetadataExample, and the net472 projects still use block scope), drop usings made redundant by ImplicitUsings, remove the one remaining // ReSharper comment, normalize the stray csproj blank lines, and fix the WebFormsExample assembly name bug. Applied as a scripted pass over the project list so the diffs are identical by construction. Verify: zero warnings in Release, dotnet format --verify-no-changes clean.
• 6. VS Code integration. launch.json still has configurations for AspNetCore3Example and AspNetCore3ChildLifetimeScope, neither of which exists anymore, and every surviving one points at a bin/Debug/net6.0/ path for a project that targets net10.0. AspNetCoreChildLifetimeScope and AspNetCoreNoStartupExample do exist and have no configuration at all. Environment variables move out of launch.json and into the per-project launchSettings.json — all eight web projects already have one — referenced from the launch configuration via launchSettingsProfile so there's a single place to set them. Switch to DOTNET_ENVIRONMENT; the ASPNETCORE_-prefixed form is the older pattern. Only the three ASP.NET Core projects actually matter there, since classic ASP.NET reads neither prefix and the .NET Framework entries are inert. settings.json still carries omnisharp.* keys the Roslyn language server ignores, and extensions.json recommends a test explorer for a repo with no tests. Depends on item 4, because the launch paths embed target frameworks. Verify: every configuration in launch.json starts the project it names.
• 7. Navigation. A table in the README — example, what it demonstrates, packages, link to the matching docs page. A short README per example: what it shows, how to run it, link to the doc page, and nothing else. Group Examples.slnx into solution folders by area instead of one flat /src/. Leaving the src/ layout alone; restructuring it churns every inbound docs link for no gain once the table exists. Verify: every src/ directory has a README.
• 8. New examples. DynamicProxy interception, Autofac.Pooling, Autofac.Diagnostics.DotGraph, Autofac.AspNetCore.Multitenant, and a middleware example for More middleware examples Documentation#160. All net10.0, all cross-platform. Verify: each builds and runs.
• 9. Documentation repo follow-up. All ten cross-links into this repo point at /tree/master/... and our default branch is main — GitHub's rename redirect isn't something to rely on. Same pull request adds the middleware section that closes More middleware examples Documentation#160 and links the four new examples from their doc pages.

Middleware examples for autofac/Documentation#160

advanced/pipelines.rst covers the mechanics thoroughly, but its only sample is the Hello World logging lambda, and that issue asks for concrete real-world cases. Scenarios to cover, in priority order:

1. Blanket AOP across every registration — the Hook/Extension point modifying IRegistrationBuilder Autofac#1337 case that issue cites. Wrapping every resolved service via the Registered event or IServiceMiddlewareSource, with no per-registration extension call. This is the one that wasn't obvious, so it's the point.
2. Resolve timing and instrumentation — measuring activation cost per service.
3. Short-circuiting — returning a cached instance without calling next.
4. Ambient parameter injection — pushing a correlation ID or tenant into every activation through ResolveRequestContext.
5. Fail-fast scope validation — service middleware that throws something readable when a service is resolved from the wrong scope.

Coverage gaps deferred

The goal is one example per non-deprecated library. After item 8, these are still uncovered:

Package	Disposition
Autofac.Extras.Moq	Worth doing. xUnit test project — one of the two places tests belong here.
Autofac.Extras.FakeItEasy	Worth doing, same shape as Moq.
Autofac.Extras.AggregateService	Worth doing. Small console app.
Autofac.Mef	Worth doing. Small console app.
Autofac.Mvc5.Owin	Low value, and better as an addition to the existing OWIN self-host example than a new project.
Autofac.SignalR2	Low value. net481, ASP.NET SignalR 2. Legacy, but it is a shipping package.
Autofac.Extras.CommonServiceLocator	Not planning to cover. CSL upstream is abandoned; not formally deprecated, but not worth teaching.
Autofac.ServiceFabric	Not planning to cover. Deliberately deleted in cae30c6; the SF SDK is Windows-only and isn't on GitHub runners, so any example we add here will rot. The tagged history still has the old one.
Autofac.Analyzers, Autofac.AspNetCore, Autofac.Extensions.Hosting, Autofac.Extras.AggregateService.SourceGenerator	Blocked. Unpublished, so an example wouldn't be runnable by anyone reading it.

Separately, there are documented core features with no example anywhere — decorators and composites, keyed services, registration sources, delegate factories, owned instances, native AOT and trimming — and integration/blazor.rst and integration/azurefunctions.rst have docs with no example. That's a real gap against "one example per documented feature," but it's much larger in scope than one-per-library and belongs in its own issue.

[tillig]

Item 1 done, on feature/root-config-refresh

Three commits: the config refresh itself, a repo-wide normalization, and a .git-blame-ignore-revs entry for the latter.

Two things turned up that weren't in the plan.

The pre-commit hooks had never been run across the whole repo. A pre-commit run --all-files autofixed 67 files. Most of that was vendored jQuery and MicrosoftAjax under Scripts/, tool-generated WCF proxies under Service References/, and Web Forms *.designer.cs — all of it tool output that gets rewritten the next time anything regenerates it. Normalizing that is churn we'd pay for repeatedly and it would bury the real diff, so those paths are now excluded at the top level of .pre-commit-config.yaml. That's a deliberate divergence from core, which has no vendored scripts or generated proxies to worry about. With the exclusions in place the normalization came down to 29 files we actually own: final newlines, trailing whitespace, and JSON key ordering, no behavior changes.

That normalization is its own commit and is listed in .git-blame-ignore-revs, same as the file-scoped namespace conversion in ccd9b35.

ISSUE_TEMPLATE.md needed a top-level heading to satisfy MD041, which is now enforced since markdownlint finally has a config. I just added the heading, but the real question is whether this file should exist at all — a root ISSUE_TEMPLATE.md overrides the org-level templates in autofac/.github, and I'd rather this repo just inherit those. Leaving it for now; not going to fold an issue-template policy change into a config cleanup.

One consequence worth flagging: src/ConfigurationExample/autofac.json is now alphabetically sorted, which puts services before type and moves defaultAssembly to the bottom. It reads a little worse as a teaching sample than it did. I decided against excluding it — one file getting a pass from the sorter is a worse precedent than a slightly awkward key order.

Verified with pre-commit run --all-files clean and a Release rebuild of all seven cross-platform projects. The net472 projects can't be built on macOS, so those wait for CI.

[tillig]

#33 is open for item 1 and green. That build is on windows-latest over the whole Examples.slnx, so the six .NET Framework projects came through the normalization clean too — which I couldn't check locally.

One thing CI made obvious that belongs in item 2: every change here builds twice. The push to feature/root-config-refresh and the pull request event each kicked off a full run for the same commit. The org's shared ci.yml has a gate job precisely for this — it skips the push build when a feature branch already has an open PR — and since I've decided to keep CI local to this repo, item 2 needs to bring that logic over rather than just bolting on the format and pre-commit jobs. Otherwise adding two more jobs turns one wasted duplicate run into three.

[tillig]

Two additions from reviewing #33, plus one correction.

The correction: the VS Code work was in my original list of things to fix and I left it out of the checklist above when I wrote it up. It's now item 6, and items 7 through 9 shifted down by one.

DOTNET_ over ASPNETCORE_. DOTNET_ENVIRONMENT is the current pattern and ASPNETCORE_ENVIRONMENT is the legacy prefix, so new and updated examples should use the former. Worth knowing before anyone runs a find-and-replace: there are 16 occurrences of ASPNETCORE_ENVIRONMENT in here and only three are meaningful. The other 13 sit in the .NET Framework projects' launchSettings.json, and classic ASP.NET reads neither prefix, so those are inert VS-generated boilerplate. Changing them would be churn that implies a behavior difference that doesn't exist.

Environment variables belong in launchSettings.json, not launch.json. This is a bigger cleanup than it sounds like, because all eight web projects already have a launchSettings.json setting ASPNETCORE_ENVIRONMENT — so launch.json has been duplicating configuration that already existed, in a file that also happens to have the wrong paths and names two projects we deleted. Pointing the launch configurations at the profiles with launchSettingsProfile means one place to change an environment variable instead of two that can disagree.

Both are folded into item 6.

Also updated item 2 to cover the duplicate-build gate, so the checklist stands on its own without reading the comments.

[tillig]

Item 1 is merged in #33 (00a7954).

Confirmed the merge commit preserved the individual SHAs, so the .git-blame-ignore-revs entry pointing at 39b6373 still resolves on main and blame skips the normalization as intended. A squash merge would have quietly orphaned that hash and left the file pointing at a commit that no longer exists — worth remembering for any future PR that adds a blame-ignore entry.

Item 2 is next: the format and pre-commit jobs plus the duplicate-build gate.

[tillig]

Item 2 is up in #34 and green. The gate does what it's supposed to: the branch-push run skipped all three heavy jobs while the pull request run executed them, so one commit now produces one build instead of two.

Two things came out of it that affect later items.

Item 5 needs LangVersion before it can do anything about nullable. dotnet format converted namespaces in the net10.0 projects only. The other 63 block-scoped files live in net472 and netstandard2.0 projects, which default to C# 7.3, and file-scoped namespaces need C# 10 — so IDE0161 is correctly silent rather than being skipped by accident. The same wall sits in front of nullable reference types, which need C# 8. So Nullable can't just go into Directory.Build.props and apply everywhere; either LangVersion gets set for the .NET Framework projects or they sit out the nullable work. Retargeting to net481 in item 4 does not fix this on its own, because the language default tracks the framework.

dotnet format under-reports on macOS for the .NET Framework projects. Running it against MultitenantExample.WcfService alone produced no diagnostics at all, with only a "warnings were encountered while loading the workspace" note, while the same projects did report diagnostics in a whole-solution run. Windows CI agreed with the solution-level result and passed, so the gate is trustworthy — but local runs on a Mac aren't authoritative for those six projects, and anyone working on items 4 through 6 should expect CI to be the real check.

Also worth recording: the auto-property expansion in #34 is latent in core's .editorconfig, not absent from it. csharp_preserve_single_line_blocks = false didn't fire in core only because 32 of its 34 single-line auto-properties have initializers and the one bare case is an interface indexer. The first bare { get; } written in a class in core will expand the same way. I decided to take the expansion here rather than diverge the config, but that's worth knowing the next time someone is surprised by it.

[tillig]

Item 3 is up in #35 and green. Every package on the net10.0 and netstandard2.0 side is current, and no source changes were needed.

The one thing I expected to hurt didn't. AttributeMetadata 7.0.0 dropped ParameterFilterAttribute, WithKeyAttribute, WithMetadataAttribute and the WithAttributeFilter extension, all of which had been obsolete and pointing at core. The example already used the core Autofac.Features.AttributeFilters equivalents, so it compiled and ran untouched. Anyone updating a real project across that boundary won't be so lucky.

I ran every example rather than just building them, which was worth doing twice over. Multitenant went up a major version and a compile tells you nothing about whether tenant overrides still resolve to the right instances — they do, verified for tenant 1, tenant 2, and the default. And src/ConfigurationExample/autofac.json was alphabetically re-sorted in #33, so this was the first real confirmation that Autofac.Configuration still reads it after defaultAssembly moved to the bottom. It does; both plugins resolve.

Two notes for whoever picks up the remaining items:

AspNetCoreChildLifetimeScope hardcodes UseUrls("http://localhost:5000") and 5001 for its two hosts and ignores ASPNETCORE_URLS. That's fine for what it demonstrates, but it means the port can't be overridden from the environment, which is worth remembering when item 6 wires up launch profiles.

The gate ran two full builds on this PR. That's correct behavior rather than a bug — I pushed the branch before opening the pull request, so at push time there was no open PR to defer to. Pushing after the PR exists, or opening it first, gets the dedupe. Later pushes to the same branch are skipped as intended.