Add a README per example and an index in the root README

Examples.slnx

@@ -1,14 +1,18 @@
 <Solution>
-  <Folder Name="/src/">
+  <Folder Name="/ASP.NET Core/">
     <Project Path="src/AspNetCoreChildLifetimeScope/AspNetCoreChildLifetimeScope.csproj" />
     <Project Path="src/AspNetCoreExample/AspNetCoreExample.csproj" />
     <Project Path="src/AspNetCoreNoStartupExample/AspNetCoreNoStartupExample.csproj" />
+  </Folder>
+  <Folder Name="/Hosting and Core Features/">
     <Project Path="src/AttributeMetadataExample/AttributeMetadataExample.csproj" />
     <Project Path="src/ConfigurationExample/ConfigurationExample.csproj" />
     <Project Path="src/ConfigurationExampleInterface/ConfigurationExampleInterface.csproj" />
     <Project Path="src/ConfigurationExamplePlugin/ConfigurationExamplePlugin.csproj" />
     <Project Path="src/GenericHostBuilderExample/GenericHostBuilderExample.csproj" />
     <Project Path="src/MultitenantExample.ConsoleApplication/MultitenantExample.ConsoleApplication.csproj" />
+  </Folder>
+  <Folder Name="/NET Framework/">
     <Project Path="src/MultitenantExample.MvcApplication/MultitenantExample.MvcApplication.csproj" />
     <Project Path="src/MultitenantExample.WcfService/MultitenantExample.WcfService.csproj" />
     <Project Path="src/MvcExample/MvcExample.csproj" />

README.md

@@ -4,6 +4,42 @@ Example projects that consume and demonstrate [Autofac](https://autofac.org) fun
 
 [![Build status](https://github.com/autofac/Examples/actions/workflows/ci.yml/badge.svg)](https://github.com/autofac/Examples/actions/workflows/ci.yml)
 
+## The Examples
+
+Each example has its own README with what it shows and how to run it.
+
+### ASP.NET Core
+
+| Example | Demonstrates | Packages |
+| --- | --- | --- |
+| [AspNetCoreExample](src/AspNetCoreExample/README.md) | A `Startup` class whose `ConfigureContainer` takes a `ContainerBuilder` | [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection) |
+| [AspNetCoreNoStartupExample](src/AspNetCoreNoStartupExample/README.md) | The same wiring in the minimal hosting model, with no `Startup` class | [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection) |
+| [AspNetCoreChildLifetimeScope](src/AspNetCoreChildLifetimeScope/README.md) | Two hosts sharing one container, each rooted in its own child scope | [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection) |
+
+### Hosting and core features
+
+| Example | Demonstrates | Packages |
+| --- | --- | --- |
+| [GenericHostBuilderExample](src/GenericHostBuilderExample/README.md) | The generic host without ASP.NET Core, for worker services | [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection) |
+| [ConfigurationExample](src/ConfigurationExample/README.md) | Registering from `autofac.json`, including an unreferenced plugin assembly | [`Autofac.Configuration`](https://github.com/autofac/Autofac.Configuration) |
+| [AttributeMetadataExample](src/AttributeMetadataExample/README.md) | Metadata by string, class, interface, and attribute, then filtering on it | [`Autofac.Extras.AttributeMetadata`](https://github.com/autofac/Autofac.Extras.AttributeMetadata) |
+| [MultitenantExample.ConsoleApplication](src/MultitenantExample.ConsoleApplication/README.md) | Per-tenant overrides with no web request in sight | [`Autofac.Multitenant`](https://github.com/autofac/Autofac.Multitenant) |
+
+### .NET Framework
+
+These target `net481` and need Windows. Most run under IIS Express from Visual Studio.
+
+| Example | Demonstrates | Packages |
+| --- | --- | --- |
+| [MvcExample](src/MvcExample/README.md) | MVC 5 controllers, action filters, and view pages, plus a WCF client | [`Autofac.Mvc5`](https://github.com/autofac/Autofac.Mvc), [`Autofac.Wcf`](https://github.com/autofac/Autofac.Wcf) |
+| [WebFormsExample](src/WebFormsExample/README.md) | Property injection into pages that cannot take constructor arguments | [`Autofac.Web`](https://github.com/autofac/Autofac.Web) |
+| [WcfExample](src/WcfExample/README.md) | A WCF service whose implementation is resolved from the container | [`Autofac.Wcf`](https://github.com/autofac/Autofac.Wcf) |
+| [WebApiExample.OwinSelfHost](src/WebApiExample.OwinSelfHost/README.md) | Web API 2 self-hosted under OWIN instead of IIS | [`Autofac.Owin`](https://github.com/autofac/Autofac.Owin), [`Autofac.WebApi2`](https://github.com/autofac/Autofac.WebApi), [`Autofac.WebApi2.Owin`](https://github.com/autofac/Autofac.WebApi.Owin) |
+| [MultitenantExample.WcfService](src/MultitenantExample.WcfService/README.md) | A WCF service resolving a different implementation per tenant | [`Autofac.Multitenant.Wcf`](https://github.com/autofac/Autofac.Multitenant.Wcf), [`Autofac.Wcf`](https://github.com/autofac/Autofac.Wcf) |
+| [MultitenantExample.MvcApplication](src/MultitenantExample.MvcApplication/README.md) | The client half, carrying tenant identity across the service boundary | [`Autofac.Multitenant`](https://github.com/autofac/Autofac.Multitenant), [`Autofac.Mvc5`](https://github.com/autofac/Autofac.Mvc) |
+
+`ConfigurationExampleInterface` and `ConfigurationExamplePlugin` are supporting libraries for `ConfigurationExample` rather than examples themselves.
+
 ## Reading the Examples
 
 The examples in the repo are always for the latest Autofac versions and libraries. Look at the tags on this repo to see examples for older and/or deprecated functionality.

src/AspNetCoreChildLifetimeScope/README.md

@@ -0,0 +1,9 @@
+# AspNetCoreChildLifetimeScope
+
+Two ASP.NET Core hosts in one process, each rooted in its own child lifetime scope over a shared container, so both reach the same singletons while keeping their own per-application registrations.
+
+Packages: [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection)
+
+Run `dotnet run --project src/AspNetCoreChildLifetimeScope`, then browse to <http://localhost:5000/api/ApplicationA> and <http://localhost:5001/api/ApplicationB>.
+
+See [ASP.NET Core](https://autofac.readthedocs.io/en/latest/integration/aspnetcore.html) for the documentation this example follows.

src/AspNetCoreExample/README.md

@@ -0,0 +1,9 @@
+# AspNetCoreExample
+
+Wiring Autofac into ASP.NET Core through a `Startup` class, where `ConfigureContainer` receives a strongly-typed `ContainerBuilder` and registrations are grouped into a module.
+
+Packages: [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection)
+
+Run `dotnet run --project src/AspNetCoreExample`, then browse to <http://localhost:5000/api/values>.
+
+See [ASP.NET Core](https://autofac.readthedocs.io/en/latest/integration/aspnetcore.html) for the documentation this example follows.

src/AspNetCoreNoStartupExample/README.md

@@ -0,0 +1,9 @@
+# AspNetCoreNoStartupExample
+
+The same wiring as `AspNetCoreExample` using the minimal hosting model, with everything configured inline in `Program.cs` and no `Startup` class. Read the two side by side to see what the `Startup` class does and does not buy you.
+
+Packages: [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection)
+
+Run `dotnet run --project src/AspNetCoreNoStartupExample`, then browse to <http://localhost:5000/api/values>.
+
+See [ASP.NET Core](https://autofac.readthedocs.io/en/latest/integration/aspnetcore.html) for the documentation this example follows.

src/AttributeMetadataExample/README.md

@@ -0,0 +1,9 @@
+# AttributeMetadataExample
+
+Four ways to attach metadata to a registration -- loose strings, a strongly-typed class, an interface, and attributes -- and then filtering on it at the point of injection.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Extras.AttributeMetadata`](https://github.com/autofac/Autofac.Extras.AttributeMetadata)
+
+Run `dotnet run --project src/AttributeMetadataExample`. It writes one line per metadata style.
+
+See [Component Metadata](https://autofac.readthedocs.io/en/latest/advanced/metadata.html) for the documentation this example follows.

src/ConfigurationExample/README.md

@@ -0,0 +1,9 @@
+# ConfigurationExample
+
+Registering components from `autofac.json` rather than in code, including a plugin assembly the application holds no reference to at all.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Configuration`](https://github.com/autofac/Autofac.Configuration)
+
+Run `dotnet run --project src/ConfigurationExample`. It prints the plugins it resolved from configuration.
+
+See [JSON/XML Configuration](https://autofac.readthedocs.io/en/latest/configuration/xml.html) for the documentation this example follows.

src/ConfigurationExampleInterface/README.md

@@ -0,0 +1,5 @@
+# ConfigurationExampleInterface
+
+The shared interface that `ConfigurationExample` and `ConfigurationExamplePlugin` both compile against. It exists so the plugin can be loaded by configuration without the application referencing it directly.
+
+Not a standalone example -- see [ConfigurationExample](../ConfigurationExample/README.md).

src/ConfigurationExamplePlugin/README.md

@@ -0,0 +1,5 @@
+# ConfigurationExamplePlugin
+
+A plugin assembly deliberately not referenced by `ConfigurationExample`. It gets copied into the output folder and loaded by name from `autofac.json`, which is the whole point being demonstrated.
+
+Not a standalone example -- see [ConfigurationExample](../ConfigurationExample/README.md).

src/GenericHostBuilderExample/README.md

@@ -0,0 +1,9 @@
+# GenericHostBuilderExample
+
+Autofac under the generic host, without ASP.NET Core in the picture. This is the shape to copy for a worker service or a console application that wants hosted services and configuration.
+
+Packages: [`Autofac.Extensions.DependencyInjection`](https://github.com/autofac/Autofac.Extensions.DependencyInjection)
+
+Run `dotnet run --project src/GenericHostBuilderExample`. It starts a hosted service and runs until you press Ctrl+C.
+
+See [.NET Core](https://autofac.readthedocs.io/en/latest/integration/netcore.html) for the documentation this example follows.

src/MultitenantExample.ConsoleApplication/README.md

@@ -0,0 +1,9 @@
+# MultitenantExample.ConsoleApplication
+
+Per-tenant registration overrides outside a web application, showing that multitenancy is not tied to a request pipeline. Switch tenants interactively and watch which dependency and lifetime you get.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Multitenant`](https://github.com/autofac/Autofac.Multitenant)
+
+Run `dotnet run --project src/MultitenantExample.ConsoleApplication` and press 1-9 to pick a tenant, or 0 for the default tenant.
+
+See [Multitenant Applications](https://autofac.readthedocs.io/en/latest/advanced/multitenant.html) for the documentation this example follows.

src/MultitenantExample.MvcApplication/README.md

@@ -0,0 +1,9 @@
+# MultitenantExample.MvcApplication
+
+The client half of the multitenant WCF example: a multitenant MVC application that also passes its tenant identity across the service boundary.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Multitenant`](https://github.com/autofac/Autofac.Multitenant), [`Autofac.Multitenant.Wcf`](https://github.com/autofac/Autofac.Multitenant.Wcf), [`Autofac.Mvc5`](https://github.com/autofac/Autofac.Mvc), [`Autofac.Wcf`](https://github.com/autofac/Autofac.Wcf)
+
+Open `Examples.slnx` in Visual Studio on Windows and run the project under IIS Express, with `MultitenantExample.WcfService` running as well.
+
+See [Multitenant Applications](https://autofac.readthedocs.io/en/latest/advanced/multitenant.html) for the documentation this example follows.

src/MultitenantExample.WcfService/README.md

@@ -0,0 +1,9 @@
+# MultitenantExample.WcfService
+
+A WCF service that resolves a different implementation per tenant, including how the tenant is identified from the incoming message.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Multitenant`](https://github.com/autofac/Autofac.Multitenant), [`Autofac.Multitenant.Wcf`](https://github.com/autofac/Autofac.Multitenant.Wcf), [`Autofac.Wcf`](https://github.com/autofac/Autofac.Wcf)
+
+Open `Examples.slnx` in Visual Studio on Windows and run the project under IIS Express. `MultitenantExample.MvcApplication` is its client.
+
+See [Multitenant Applications](https://autofac.readthedocs.io/en/latest/advanced/multitenant.html) for the documentation this example follows.

src/MvcExample/README.md

@@ -0,0 +1,9 @@
+# MvcExample
+
+ASP.NET MVC 5 integration across controllers, action filters, and view pages. It also consumes `WcfExample`, so it doubles as an example of injecting a WCF client proxy.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Mvc5`](https://github.com/autofac/Autofac.Mvc), [`Autofac.Wcf`](https://github.com/autofac/Autofac.Wcf)
+
+Open `Examples.slnx` in Visual Studio on Windows and run the project under IIS Express. `WcfExample` needs to be running for the index page to load.
+
+See [MVC](https://autofac.readthedocs.io/en/latest/integration/mvc.html) for the documentation this example follows.

src/WcfExample/README.md

@@ -0,0 +1,9 @@
+# WcfExample
+
+Hosting a WCF service whose implementation is resolved from Autofac, using the service host factory.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Wcf`](https://github.com/autofac/Autofac.Wcf)
+
+Open `Examples.slnx` in Visual Studio on Windows and run the project under IIS Express. `MvcExample` acts as its client.
+
+See [Windows Communication Foundation (WCF)](https://autofac.readthedocs.io/en/latest/integration/wcf.html) for the documentation this example follows.

src/WebApiExample.OwinSelfHost/README.md

@@ -0,0 +1,9 @@
+# WebApiExample.OwinSelfHost
+
+Web API 2 running under OWIN self-hosting rather than IIS, with Autofac supplying controller dependencies through the OWIN pipeline.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Owin`](https://github.com/autofac/Autofac.Owin), [`Autofac.WebApi2`](https://github.com/autofac/Autofac.WebApi), [`Autofac.WebApi2.Owin`](https://github.com/autofac/Autofac.WebApi.Owin)
+
+Run `dotnet run --project src/WebApiExample.OwinSelfHost` on Windows. It self-hosts on <http://localhost:9123/> and calls itself once on startup.
+
+See [OWIN](https://autofac.readthedocs.io/en/latest/integration/owin.html) for the documentation this example follows.

src/WebFormsExample/README.md

@@ -0,0 +1,9 @@
+# WebFormsExample
+
+Property injection into Web Forms pages, which cannot take constructor dependencies, by way of an HTTP module.
+
+Packages: [`Autofac`](https://github.com/autofac/Autofac), [`Autofac.Web`](https://github.com/autofac/Autofac.Web)
+
+Open `Examples.slnx` in Visual Studio on Windows and run the project under IIS Express.
+
+See [Web Forms](https://autofac.readthedocs.io/en/latest/integration/webforms.html) for the documentation this example follows.