Transforms

Introduced: preview2

Introduction

When proxying a request it's common to modify parts of the request or response to adapt to the destination server's requirements or to flow additional data such as the client's original IP address. This process is implemented via Transforms. Types of transforms are defined globally for the application and then individual routes supply the parameters to enable and configure those transforms. The original request objects are not modified by these transforms, only the proxy requests.

Defaults

The following transforms are enabled by default for all routes. They can be configured or disabled as shown later in this document.

• Host - Suppress the incoming request's Host header. The proxy request will default to the host name specified in the destination server address. See RequestHeaderOriginalHost below.
• X-Forwarded-For - Appends the client's IP address to the X-Forwarded-For header. See X-Forwarded below.
• X-Forwarded-Proto - Appends the request's original scheme (http/https) to the X-Forwarded-Proto header. See X-Forwarded below.
• X-Forwarded-Host - Appends the request's original Host to the X-Forwarded-Host header. See X-Forwarded below.
• X-Forwarded-PathBase - Appends the request's original PathBase, if any, to the X-Forwarded-Proto header. See X-Forwarded below.

For example the following incoming request to http://IncomingHost:5000/path:

GET /path HTTP/1.1
Host: IncomingHost:5000
Accept: */*
header1: foo

would be transformed and proxied to the destination server https://DestinationHost:6000/ as follows using these defaults:

GET /path HTTP/1.1
Host: DestinationHost:6000
Accept: */*
header1: foo
X-Forwarded-For: 5.5.5.5
X-Forwarded-Proto: http
X-Forwarded-Host: IncomingHost:5000

Transforms fall into a few categories: request, response, and response trailers. Request and response body transforms are not supported by YARP but you can write middleware to do this. Request trailers are not supported because they are not supported by the underlying HttpClient.

Transforms can be added to routes either through configuration or programmatically.

From Configuration

Transforms can be configured on ProxyRoute.Transforms and can be bound from the Routes sections of the config file. These can be modified and reloaded without restarting the proxy. A transform is configured using one or more key-value string pairs.

Here is an example of common transforms:

{
  "ReverseProxy": {
    "Routes": [
      {
        "RouteId": "route1",
        "ClusterId": "cluster1",
        "Match": {
          "Hosts": [ "localhost" ]
        },
        "Transforms": [
          { "PathPrefix": "/apis" },
          {
            "RequestHeader": "header1",
            "Append": "bar"
          },
          {
            "ResponseHeader": "header2",
            "Append": "bar",
            "When": "Always"
          },
          { "ClientCert": "X-Client-Cert" },
          { "RequestHeadersCopy": "true" },
          { "RequestHeaderOriginalHost": "true" },
          {
            "X-Forwarded": "proto,host,for,pathbase",
            "Append": "true",
            "Prefix": "X-Forwarded-"
          }
        ]
      },
      {
        "RouteId": "route2",
        "ClusterId": "cluster1",
        "Match": {
          "Path": "/api/{plugin}/stuff/{*remainder}"
        },
        "Transforms": [
          { "PathPattern": "/foo/{plugin}/bar/{remainder}" },
          {
            "QueryStringParameter": "q",
            "Append": "plugin"
          }
        ]
      }
    ],
    "Clusters": {
      "cluster1": {
        "Destinations": {
          "cluster1/destination1": {
            "Address": "https://localhost:10001/Path/Base"
          }
        }
      }
    }
  }
}

All configuration entries are treated as case-insensitive, though the destination server may treat the resulting values as case sensitive or insensitive such as the path.

The details for these transforms are covered later in this document.

Developers that want to integrate their custom transforms with the Transforms section of configuration can do so using ITransformFactory described below.

From Code

Transforms can be added to routes programmatically by calling the AddTransforms method.

AddTransforms can be called from Startup.ConfigureServices to provide a callback for configuring transforms. This callback is invoked each time a route is built or rebuilt and allows the developer to inspect the ProxyRoute information and conditionally add transforms for it.

The AddTransforms callback provides a TransformBuilderContext where transforms can be added or configured. Most transforms provide TransformBuilderContext extension methods to make them easier to add. These are extensions documented below with the individual transform descriptions.

The TransformBuilderContext also includes an IServiceProvider for access to any needed services.

services.AddReverseProxy()
    .LoadFromConfig(_configuration.GetSection("ReverseProxy"))
    .AddTransforms(builderContext =>
    {
        // Added to all routes.
        builderContext.AddPathPrefix("/prefix");

        // Conditionally add a transform for routes that require auth.
        if (!string.IsNullOrEmpty(builderContext.Route.AuthorizationPolicy))
        {
            builderContext.AddRequestTransform(async transformContext =>
            {
                transformContext.ProxyRequest.Headers.Add("CustomHeader", "CustomValue");
            });
        }
    });

For more advanced control see ITransformProvider described below.

Request transforms

Request transforms include the request path, query, HTTP version, method, and headers. In code these are represented by the RequestTransformContext object and processed by implementations of the abstract class RequestTransform.

Notes:

• The proxy request scheme (http/https), authority, and path base, are taken from the destination server address (https://localhost:10001/Path/Base in the example above) and should not be modified by transforms.
• The Host header can be overridden by transforms independent of the authority, see RequestHeader below.
• The request's original PathBase property is not used when constructing the proxy request, see X-Forwarded.
• All incoming request headers are copied to the proxy request by default with the exception of the Host header (see Defaults). X-Forwarded headers are also added by default. These behaviors can be configured using the following transforms. Additional request headers can be specified, or request headers can be excluded by setting them to an empty value.

The following are built in transforms identified by their primary config key. These transforms are applied in the order they are specified in the route configuration.

PathPrefix

Key	Value	Required
PathPrefix	A path starting with a '/'	yes

Config:

{ "PathPrefix": "/prefix" }

Code:

proxyRoute = proxyRoute.WithTransformPathPrefix(prefix: "/prefix");

transformBuilderContext.AddPathPrefix(prefix: "/prefix");

Example:
/request/path becomes /prefix/request/path

This will prefix the request path with the given value.

PathRemovePrefix

Key	Value	Required
PathRemovePrefix	A path starting with a '/'	yes

Config:

{ "PathRemovePrefix": "/prefix" }

Code:

proxyRoute = proxyRoute.WithTransformPathRemovePrefix(prefix: "/prefix");

transformBuilderContext.AddPathRemovePrefix(prefix: "/prefix");

Example:
/prefix/request/path becomes /request/path
/prefix2/request/path is not modified

This will remove the matching prefix from the request path. Matches are made on path segment boundaries (/). If the prefix does not match then no changes are made.

PathSet

Key	Value	Required
PathSet	A path starting with a '/'	yes

Config:

{ "PathSet": "/newpath" }

Code:

proxyRoute = proxyRoute.WithTransformPathSet(path: "/newpath");

transformBuilderContext.AddPathSet(path: "/newpath");

Example:
/request/path becomes /newpath

This will set the request path with the given value.

PathPattern

Key	Value	Required
PathPattern	A path template starting with a '/'	yes

Config:

{ "PathPattern": "/my/{plugin}/api/{remainder}" }

Code:

proxyRoute = proxyRoute.WithTransformPathRouteValues(pattern: new PathString("/my/{plugin}/api/{remainder}"));

transformBuilderContext.AddPathRouteValues(pattern: new PathString("/my/{plugin}/api/{remainder}"));

This will set the request path with the given value and replace any {} segments with the associated route value. {} segments without a matching route value are removed. See ASP.NET Core's routing docs for more information about route templates.

Example:

Step	Value
Route definition	/api/{plugin}/stuff/{*remainder}
Request path	/api/v1/stuff/more/stuff
Plugin value	v1
Remainder value	more/stuff
PathPattern	/my/{plugin}/api/{remainder}
Result	/my/v1/api/more/stuff

QueryValueParameter

Key	Value	Required
QueryValueParameter	Name of a query string parameter	yes
Set/Append	Static value	yes

Config:

{
  "QueryValueParameter": "foo",
  "Append": "bar"
}

Code:

proxyRoute = proxyRoute.WithTransformQueryValue(queryKey: "foo", value: "bar", append: true);

transformBuilderContext.AddQueryValue(queryKey: "foo", value: "bar", append: true);

This will add a query string parameter with the name foo and sets it to the static value bar.

Example:

Step	Value
Query	?a=b
QueryValueParameter	foo
Append	remainder
Result	?a=b&foo=remainder

QueryRouteParameter

Key	Value	Required
QueryRouteParameter	Name of a query string parameter	yes
Set/Append	The name of a route value	yes

Config:

{
  "QueryRouteParameter": "foo",
  "Append": "remainder"
}

Code:

proxyRoute = proxyRoute.WithTransformQueryRouteValue(queryKey: "foo", routeValueKey: "remainder", append: true);

transformBuilderContext.AddQueryRouteValue(queryKey: "foo", routeValueKey: "remainder", append: true);

This will add a query string parameter with the name foo and sets it to the value of the associated route value.

Example:

Step	Value
Route definition	/api/{*remainder}
Request path	/api/more/stuff
Remainder value	more/stuff
QueryRouteParameter	foo
Append	remainder
Result	?foo=more/stuff

QueryRemoveParameter

Key	Value	Required
QueryRemoveParameter	Name of a query string parameter	yes

Config:

{ "QueryRemoveParameter": "foo" }

Code:

proxyRoute = proxyRoute.WithTransformQueryRemoveKey(queryKey: "foo");

transformBuilderContext.AddQueryRemoveKey(queryKey: "foo");

This will remove a query string parameter with the name foo if present on the request.

Example:

Step	Value
Request path	?a=b&foo=c
QueryRemoveParameter	foo
Result	?a=b

HttpMethod

Key	Value	Required
HttpMethod	The http method to replace	yes
Set	The new http method	yes

Config:

{
  "HttpMethod": "PUT",
  "Set": "POST",
}

Code:

proxyRoute = proxyRoute.WithTransformHttpMethodChange(fromHttpMethod: HttpMethods.Put, toHttpMethod: HttpMethods.Post);

transformBuilderContext.AddHttpMethodChange(fromHttpMethod: HttpMethods.Put, toHttpMethod: HttpMethods.Post);

This will change PUT requests to POST.

RequestHeadersCopy

Key	Value	Default	Required
RequestHeadersCopy	true/false	true	yes

Config:

{ "RequestHeadersCopy": "false" }

Code:

proxyRoute = proxyRoute.WithTransformCopyRequestHeaders(copy: false);

transformBuilderContext.CopyRequestHeaders = false;

This sets if all incoming request headers are copied to the proxy request. This setting is enabled by default and can by disabled by configuring the transform with a false value. Transforms that reference specific headers will still be run if this is disabled.

RequestHeaderOriginalHost

Key	Value	Default	Required
RequestHeaderOriginalHost	true/false	false	yes

Config:

{ "RequestHeaderOriginalHost": "true" }

proxyRoute = proxyRoute.WithTransformUseOriginalHostHeader(useOriginal: true);

transformBuilderContext.UseOriginalHost = true;

This specifies if the incoming request Host header should be copied to the proxy request. This setting is disabled by default and can be enabled by configuring the transform with a true value. Transforms that directly reference the Host header will override this transform.

RequestHeader

Key	Value	Required
RequestHeader	The header name	yes
Set/Append	The header value	yes

Config:

{
  "RequestHeader": "MyHeader",
  "Set": "MyValue",
}

Code:

proxyRoute = proxyRoute.WithTransformRequestHeader(headerName: "MyHeader", value: "MyValue", append: false);

transformBuilderContext.AddRequestHeader(headerName: "MyHeader", value: "MyValue", append: false);

Example:

MyHeader: MyValue

This sets or appends the value for the named header. Set replaces any existing header. Set a header to empty to remove it (e.g. "Set": ""). Append adds an additional header with the given value.

X-Forwarded

Key	Value	Default	Required
X-Forwarded	A comma separated list containing any of these values: for,proto,host,PathBase	"for,proto,host,PathBase"	yes
Prefix	The header name prefix	"X-Forwarded-"	no
Append	true/false	true	no

Config:

{
  "X-Forwarded": "for,proto,host,PathBase",
  "Prefix": "X-Forwarded-",
  "Append": "true"
}

Code:

proxyRoute = proxyRoute.WithTransformXForwarded(headerPrefix: "X-Forwarded-", useFor: true, useHost: true, useProto: true, usePathBase: true, append: true);

transformBuilderContext.AddXForwarded(headerPrefix: "X-Forwarded-", useFor: true, useHost: true, useProto: true, usePathBase: true, append: true);

Example:

X-Forwarded-For: 5.5.5.5
X-Forwarded-Proto: https
X-Forwarded-Host: IncomingHost:5000
X-Forwarded-PathBase: /path/base

Disable default headers:

{ "X-Forwarded": "" }

transformBuilderContext.UseDefaultForwarders = false;

X-Forwarded-* headers are a common way to forward information to the destination server that may otherwise be obscured by the use of a proxy. The destination server likely needs this information for security checks and to properly generate absolute URIs for links and redirects. There is no standard that defines these headers and implementations vary, check your destination server for support.

This transform is enabled by default even if not specified in the route config.

Set the X-Forwarded value to a comma separated list containing the headers you need to enable. All for headers are enabled by default. All can be disabled by specifying an empty value "".

The Prefix specifies the header name prefix to use for each header. With the default X-Forwarded- prefix the resulting headers will be X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-PathBase.

Append specifies if each header should append to or replace an existing header of the same name. A request traversing multiple proxies may accumulate a list of such headers and the destination server will need to evaluate the list to determine the original value. If append is false and the associated value is not available on the request (e.g. RemoteIpAddress is null), any existing header is still removed to prevent spoofing.

The {Prefix}For header value is taken from HttpContext.Connection.RemoteIpAddress representing the prior caller's IP address. The port is not included. IPv6 addresses do not include the bounding [] brackets.

The {Prefix}Proto header value is taken from HttpContext.Request.Scheme indicating if the prior caller used HTTP or HTTPS.

The {Prefix}Host header value is taken from the incoming request's Host header. This is independent of RequestHeaderOriginalHost specified above. Unicode/IDN hosts are punycode encoded.

The {Prefix}PathBase header value is taken from HttpContext.Request.PathBase. The PathBase property is not used when generating the proxy request so the destination server will need the original value to correctly generate links and directs. The value is in the percent encoded Uri format.

Forwarded

Key	Value	Default	Required
Forwarded	A comma separated list containing any of these values: for,by,proto,host	(none)	yes
ForFormat	Random/RandomAndPort/RandomAndRandomPort/Unknown/UnknownAndPort/UnknownAndRandomPort/Ip/IpAndPort/IpAndRandomPort	Random	no
ByFormat	Random/RandomAndPort/RandomAndRandomPort/Unknown/UnknownAndPort/UnknownAndRandomPort/Ip/IpAndPort/IpAndRandomPort	Random	no
Append	true/false	true	no

Config:

{
  "Forwarded": "by,for,host,proto",
  "ByFormat": "Random",
  "ForFormat": "IpAndPort"
},

Code:

proxyRoute = proxyRoute.WithTransformForwarded(useHost: true, useProto: true, forFormat: NodeFormat.IpAndPort, ByFormat: NodeFormat.Random, append: true);

transformBuilderContext.AddForwarded(useHost: true, useProto: true, forFormat: NodeFormat.IpAndPort, ByFormat: NodeFormat.Random, append: true);

Example:

Forwarded: proto=https;host="localhost:5001";for="[::1]:20173";by=_YQuN68tm6

The Forwarded header is defined by RFC 7239. It consolidates many of the same functions as the unofficial X-Forwarded headers, flowing information to the destination server that would otherwise be obscured by using a proxy.

Enabling this transform will disable the default X-Forwarded transforms as they carry similar information in another format. The X-Forwarded transforms can still be explicitly enabled.

Append: This specifies if the transform should append to or replace an existing Forwarded header. A request traversing multiple proxies may accumulate a list of such headers and the destination server will need to evaluate the list to determine the original value.

Proto: This value is taken from HttpContext.Request.Scheme indicating if the prior caller used HTTP or HTTPS.

Host: This value is taken from the incoming request's Host header. This is independent of RequestHeaderOriginalHost specified above. Unicode/IDN hosts are punycode encoded.

For: This value identifies the prior caller. IP addresses are taken from HttpContext.Connection.RemoteIpAddress. See ByFormat and ForFormat below for details.

By: This value identifies where the proxy received the request. IP addresses are taken from HttpContext.Connection.LocalIpAddress. See ByFormat and ForFormat below for details.

ByFormat and ForFormat:

The RFC allows a variety of formats for the By and For fields. It requires that the default format uses an obfuscated identifier identified here as Random.

Format	Description	Example
Random	An obfuscated identifier that is generated randomly per request. This allows for diagnostic tracing scenarios while limiting the flow of uniquely identifying information for privacy reasons.	by=_YQuN68tm6
RandomAndPort	The Random identifier plus the port.	by="_YQuN68tm6:80"
RandomAndRandomPort	The Random identifier plus another random identifier for the port.	by="_YQuN68tm6:_jDw5Cf3tQ"
Unknown	This can be used when the identity of the preceding entity is not known, but the proxy server still wants to signal that the request was forwarded.	by=unknown
UnknownAndPort	The Unknown identifier plus the port if available.	by="unknown:80"
UnknownAndRandomPort	The Unknown identifier plus random identifier for the port.	by="unknown:_jDw5Cf3tQ"
Ip	An IPv4 address or an IPv6 address including brackets.	by="[::1]"
IpAndPort	The IP address plus the port.	by="[::1]:80"
IpAndRandomPort	The IP address plus random identifier for the port.	by="[::1]:_jDw5Cf3tQ"

ClientCert

Key	Value	Required
ClientCert	The header name	yes

Config:

{ "ClientCert": "X-Client-Cert" }

Code:

proxyRoute = proxyRoute.WithTransformClientCertHeader(headerName: "X-Client-Cert");

transformBuilderContext.AddClientCertHeader(headerName: "X-Client-Cert");

Example:

X-Client-Cert: SSdtIGEgY2VydGlmaWNhdGU...

This transform causes the client certificate taken from HttpContext.Connection.ClientCertificate to be Base64 encoded and set as the value for the given header name. This is needed because client certificates from incoming connections are not used when making connections to the destination server. The destination server may need that certificate to authenticate the client. There is no standard that defines this header and implementations vary, check your destination server for support.

Response and Response Trailers

All response headers and trailers are copied from the proxied response to the outgoing client response by default. Response and response trailer transforms may specify if they should be applied only for successful responses or for all responses.

In code these are implemented as derivations of the abstract classes ResponseTransform and ResponseTrailersTransform.

ResponseHeadersCopy

Key	Value	Default	Required
ResponseHeadersCopy	true/false	true	yes

Config:

{ "ResponseHeadersCopy": "false" }

Code:

proxyRoute = proxyRoute.WithTransformCopyResponseHeaders(copy: false);

transformBuilderContext.CopyResponseHeaders = false;

This sets if all proxy response headers are copied to the client response. This setting is enabled by default and can be disabled by configuring the transform with a false value. Transforms that reference specific headers will still be run if this is disabled.

ResponseHeader

Key	Value	Default	Required
ResponseHeader	The header name	(none)	yes
Set/Append	The header value	(none)	yes
When	Success/Always	Success	no

Config:

{
  "ResponseHeader": "HeaderName",
  "Append": "value",
  "When": "Success"
}

Code:

proxyRoute = proxyRoute.WithTransformResponseHeader(headerName: "HeaderName", value: "value", append: true, always: false);

transformBuilderContext.AddResponseHeader(headerName: "HeaderName", value: "value", append: true, always: false);

Example:

HeaderName: value

This sets or appends the value for the named header. Set replaces any existing header. Set a header to empty to remove it (e.g. "Set": ""). Append adds an additional header with the given value.

When specifies if the response header should be included for successful responses or for all responses. Any response with a status code less than 400 is considered a success.

ResponseTrailersCopy

Key	Value	Default	Required
ResponseTrailersCopy	true/false	true	yes

Config:

{ "ResponseTrailersCopy": "false" }

Code:

proxyRoute = proxyRoute.WithTransformCopyResponseTrailers(copy: false);

transformBuilderContext.CopyResponseTrailers = false;

This sets if all proxy response trailers are copied to the client response. This setting is enabled by default and can be disabled by configuring the transform with a false value. Transforms that reference specific headers will still be run if this is disabled.

ResponseTrailer

Key	Value	Default	Required
ResponseTrailer	The header name	(none)	yes
Set/Append	The header value	(none)	yes
When	Success/Always	Success	no

Config:

{
  "ResponseTrailer": "HeaderName",
  "Append": "value",
  "When": "Success"
}

Code:

proxyRoute = proxyRoute.WithTransformResponseTrailer(headerName: "HeaderName", value: "value", append: true, always: false);

transformBuilderContext.AddResponseTrailer(headerName: "HeaderName", value: "value", append: true, always: false);

Example:

HeaderName: value

Response trailers are headers sent at the end of the response body. Support for trailers is uncommon in HTTP/1.1 implementations but is becoming common in HTTP/2 implementations. Check your client and server for support.

ResponseTrailer follows the same structure and guidance as ResponseHeader.

Extensibility

AddRequestTransform

AddRequestTransform is a TransformBuilderContext extension method that defines a request transform as a Func<RequestTransformContext, ValueTask>. This allows creating a custom request transform without implementing a RequestTransform derived class.

AddResponseTransform

AddResponseTransform is a TransformBuilderContext extension method that defines a response transform as a Func<ResponseTransformContext, ValueTask>. This allows creating a custom response transform without implementing a ResponseTransform derived class.

AddResponseTrailersTransform

AddResponseTrailersTransform is a TransformBuilderContext extension method that defines a response trailers transform as a Func<ResponseTrailersTransformContext, ValueTask>. This allows creating a custom response trailers transform without implementing a ResponseTrailersTransform derived class.

RequestTransform

All request transforms must derive from the abstract base class RequestTransform. These can freely modify the proxy HttpRequestMessage. Avoid reading or modifying the request body as this may disrupt the proxying flow. Consider also adding a parametrized extension method on TransformBuilderContext for discoverability and easy of use.

ResponseTransform

All response transforms must derive from the abstract base class ResponseTransform. These can freely modify the client HttpResponse. Avoid reading or modifying the response body as this may disrupt the proxying flow. Consider also adding a parametrized extension method on TransformBuilderContext for discoverability and easy of use.

ResponseTrailersTransform

All response trailers transforms must derive from the abstract base class ResponseTrailersTransform. These can freely modify the client HttpResponse trailers. These run after the response body and should not attempt to modify the response headers or body. Consider also adding a parametrized extension method on TransformBuilderContext for discoverability and easy of use.

ITransformProvider

ITransformProvider provides the functionality of AddTransforms described above as well as DI integration and validation support.

ITransformProvider's can be registered in DI by calling AddTransforms<T>(). Multiple ITransformProvider implementations can be registered and all will be run.

ITransformProvider has two methods, Validate and Apply. Validate gives you the opportunity to inspect the route for any parameters that are needed to configure a transform, such as custom metadata, and to return validation errors on the context if any needed values are missing or invalid. The Apply method provides the same functionality as AddTransform as discussed above, adding and configuring transforms per route.

services.AddReverseProxy()
    .LoadFromConfig(_configuration.GetSection("ReverseProxy"))
    .AddTransforms<MyTransformProvider>();

    internal class MyTransformProvider : ITransformProvider
    {
        public void Validate(TransformValidationContext context)
        {
            // Check all routes for a custom property and validate the associated
            // transform data.
            string value = null;
            if (context.Route.Metadata?.TryGetValue("CustomMetadata", out value) ?? false)
            {
                if (string.IsNullOrEmpty(value))
                {
                    context.Errors.Add(new ArgumentException(
                        "A non-empty CustomMetadata value is required"));
                }
            }
        }

        public void Apply(TransformBuilderContext transformBuildContext)
        {
            // Check all routes for a custom property and add the associated transform.
            string value = null;
            if (transformBuildContext.Route.Metadata?.TryGetValue("CustomMetadata", out value)
                ?? false)
            {
                if (string.IsNullOrEmpty(value))
                {
                    throw new ArgumentException(
                        "A non-empty CustomMetadata value is required");
                }

                transformBuildContext.AddRequestTransform(transformContext =>
                {
                    transformContext.ProxyRequest.Headers.Add("CustomHeader", value);
                    return default;
                });
            }
        }
    }

ITransformFactory

Developers that want to integrate their custom transforms with the Transforms section of configuration can implement an ITransformFactory. This should be registered in DI using the AddTransformFactory<T>() method. Multiple factories can be registered and all will be used.

ITransformFactory provides two methods, Validate and Build. These process one set of transform values at a time, represented by a IReadOnlyDictionary<string, string>.

The Validate method is called when loading a configuration to verify the contents and report all errors. Any reported errors will prevent the configuration from being applied.

The Build method takes the given configuration and produces the associated transform instances for the route.

services.AddReverseProxy()
    .LoadFromConfig(_configuration.GetSection("ReverseProxy"))
    .AddTransformFactory<MyTransformFactory>();

    internal class MyTransformFactory : ITransformFactory
    {
        public bool Validate(TransformValidationContext context,
            IReadOnlyDictionary<string, string> transformValues)
        {
            if (transformValues.TryGetValue("CustomTransform", out var value))
            {
                if (string.IsNullOrEmpty(value))
                {
                    context.Errors.Add(new ArgumentException(
                        "A non-empty CustomTransform value is required"));
                }

                return true; // Matched
            }
            return false;
        }

        public bool Build(TransformBuilderContext context,
            IReadOnlyDictionary<string, string> transformValues)
        {
            if (transformValues.TryGetValue("CustomTransform", out var value))
            {
                if (string.IsNullOrEmpty(value))
                {
                    throw new ArgumentException(
                        "A non-empty CustomTransform value is required");
                }

                context.AddRequestTransform(transformContext =>
                {
                    transformContext.ProxyRequest.Headers.Add("CustomHeader", value);
                    return default;
                });

                return true; // Matched
            }

            return false;
        }
    }

Validate and Build return true if they've identified the given transform configuration as one that they own. A ITransformFactory may implement multiple transforms. Any ProxyRoute.Transforms entries not handled by any ITransformFactory will be considered configuration errors and prevent the configuration from being applied.

Consider also adding parametrized extension methods on ProxyRoute like WithTransformQueryValue to facilitate programmatic route construction.

        public static ProxyRoute WithTransformQueryValue(this ProxyRoute proxyRoute, string queryKey, string value, bool append = true)
        {
            var type = append ? QueryTransformFactory.AppendKey : QueryTransformFactory.SetKey;
            return proxyRoute.WithTransform(transform =>
            {
                transform[QueryTransformFactory.QueryValueParameterKey] = queryKey;
                transform[type] = value;
            });
        }