Add documentation for DynamicRouteValuesTransformer

[rynowak]

This is a new feature that allows users to migrate IRouter code that dynamically manipulates route values to endpoint routing.

dotnet/aspnetcore#4221

[rynowak]

Summary

DynamicRouteValueTransformer is a new feature in Endpoint Routing that supports create of slug-style routes. Implementing a DynamicRouteValueTransformer allows an application to programmatically select a controller or page to handle the request, usually based on some external data.

Writing a transformer

First, subclass DynamicRouteValueTransformer, and override the TransformAsync method. Inside TransformAsync the transformer should compare route values and details of the request to map the request to an appropriate handler.

Usually this process entails reading some known route value from the current route values, and performing a database lookup to get a new set of values.

The DynamicRouteValueTransformer implementation can access services from dependency injection through the constructor.

Example:

    public class Transformer : DynamicRouteValueTransformer
    {
        private readonly ArticleRepository _respository;

        public Transformer(ArticleRepository repository)
        {
            _respository = repository;
        }

        public override async ValueTask<RouteValueDictionary> TransformAsync(HttpContext httpContext, RouteValueDictionary values)
        {
            var slug = values["article"] as string;

            var article = await _respository.GetArticleBySlug(slug);
            if (article == null)
            {
                return null;
            }

            return new RouteValueDictionary()
            {
                { "page", article.Page },
                { "id", article.Id },
            };
        }
    }

Returning null from TransformAsync will treat the route as a failure (did not match anything).

Returning route values from TransformAsync will perform a further lookup to find matching pages or controllers. The matching logic is similar to how conventional routing selects controllers, by matching the area, action, and controller route values (or area, and page in the case of pages).

Registering a transformer

A DynamicRouteValueTransformer must be registered with the service collection in ConfigureServices using its type name.

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddScoped<ArticleRepository>();
            services.AddScoped<Transformer>();
            services.AddRazorPages();
        }

The service registration can use any lifetime.

Additionally, the transformer needs to be attached to a route inside of UseEndpoints()

Example (using a transformer with pages):

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapRazorPages();
                endpoints.MapDynamicPageRoute<Transformer>("blog/{**article}");
            });

Example (using a transformer with controllers):

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapDynamicControllerRoute<Transformer>("blog/{**article}");
            });

[mkArtakMSFT]

@Rick-Anderson can this be picked up by you?

[Rick-Anderson]

@Rick-Anderson can this be picked up by you?

Yes, assigned to @scottaddie. @scottaddie can probably do this after the high priority 3.0 docs issues are completed.

[Rick-Anderson]

@serpent5 are you interested in writing a sample using the above code? Sometime next year? No hurry.