Aspire.Hosting.Yarp 13.1.0

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Aspire.Hosting.Yarp --version 13.1.0
                    


                    

                
NuGet\Install-Package Aspire.Hosting.Yarp -Version 13.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Aspire.Hosting.Yarp" Version="13.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Aspire.Hosting.Yarp" Version="13.1.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Aspire.Hosting.Yarp" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Aspire.Hosting.Yarp --version 13.1.0
                    


                    

                
#r "nuget: Aspire.Hosting.Yarp, 13.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Aspire.Hosting.Yarp@13.1.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Aspire.Hosting.Yarp&version=13.1.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Aspire.Hosting.Yarp&version=13.1.0
                    


                            Install as a Cake Tool

Aspire.Hosting.Yarp library

Provides extension methods and resource definitions for an Aspire AppHost to configure a YARP reverse proxy instance.

Getting started

Install the package

In your AppHost project, install the Aspire YARP Hosting library with NuGet:

dotnet add package Aspire.Hosting.Yarp

Usage examples

Programmatic configuration

The modern approach uses programmatic configuration with the WithConfiguration method:

var builder = DistributedApplication.CreateBuilder(args);

var backendService = builder.AddProject<Projects.Backend>("backend");
var frontendService = builder.AddProject<Projects.Frontend>("frontend");

var gateway = builder.AddYarp("gateway")
                     .WithConfiguration(yarp =>
                     {
                         // Add a catch-all route for the frontend
                         yarp.AddRoute(frontendService);
                         
                         // Add a route with path prefix for the backend API
                         yarp.AddRoute("/api/{**catch-all}", backendService)
                             .WithTransformPathRemovePrefix("/api");
                     });

var app = builder.Build();
await app.RunAsync();

Configuration with external services

You can also route to external services:

var externalApi = builder.AddExternalService("external-api", "https://api.example.com");

var gateway = builder.AddYarp("gateway")
                     .WithConfiguration(yarp =>
                     {
                         yarp.AddRoute("/external/{**catch-all}", externalApi)
                             .WithTransformPathRemovePrefix("/external");
                     });

Static file serving

YARP can serve static files alongside proxied routes. There are two approaches:

Copy files locally
builder.AddYarp("static")
       .WithStaticFiles("../static");

This will copy files into the container use container files in run mode, and use a bind mount in publish mode.

Copy files via Docker

You can also use a docker file to copy static assets into the yarp container: e.g.

builder.AddYarp("frontend")
       .WithStaticFiles()
       .WithDockerFile("../npmapp");

# Stage 1: Build React app
FROM node:20 AS builder
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

# Stage 2: Copy static files to YARP container
FROM mcr.microsoft.com/dotnet/nightly/yarp:2.3.0-preview.4 AS yarp
WORKDIR /app
COPY --from=builder /app/dist ./wwwroot

Configuration API

Route configuration

The IYarpConfigurationBuilder provides methods to configure routes and clusters:

// Add routes with different targets
yarp.AddRoute(resource);                                    // Catch-all route
yarp.AddRoute("/path/{**catch-all}", resource);            // Specific path route
yarp.AddRoute("/path/{**catch-all}", endpoint);            // Route to specific endpoint
yarp.AddRoute("/path/{**catch-all}", externalService);     // Route to external service

// Add clusters directly
var cluster = yarp.AddCluster(resource);
var route = yarp.AddRoute("/path/{**catch-all}", cluster);

Route matching options

Routes can be configured with various matching criteria:

yarp.AddRoute("/api/{**catch-all}", backendService)
    .WithMatchMethods("GET", "POST")                        // HTTP methods
    .WithMatchHeaders(new RouteHeader("Content-Type", "application/json"))  // Headers
    .WithMatchHosts("api.example.com")                      // Host header
    .WithOrder(1);                                          // Route priority

Transform extensions

YARP provides various transform extensions to modify requests and responses:

Path transforms

route.WithTransformPathSet("/new/path")                     // Set path
     .WithTransformPathPrefix("/prefix")                    // Add prefix
     .WithTransformPathRemovePrefix("/api")                 // Remove prefix
     .WithTransformPathRouteValues("/users/{id}/posts");    // Use route values

Request header transforms

route.WithTransformRequestHeader("X-Forwarded-For", "value")           // Add/set header
     .WithTransformRequestHeaderRouteValue("X-User-Id", "id")          // From route value
     .WithTransformUseOriginalHostHeader(true)                         // Preserve host
     .WithTransformCopyRequestHeaders(false);                          // Copy headers

Response transforms

route.WithTransformResponseHeader("X-Powered-By", "Aspire")            // Add response header
     .WithTransformResponseHeaderRemove("Server")                      // Remove header
     .WithTransformCopyResponseHeaders(true);                          // Copy headers

Query parameter transforms

route.WithTransformQueryValue("version", "1.0")                       // Add query param
     .WithTransformQueryRouteValue("userId", "id")                     // From route value
     .WithTransformQueryRemoveKey("debug");                            // Remove query param

Advanced configuration

Multiple routes to the same service

builder.AddYarp("gateway")
       .WithConfiguration(yarp =>
       {
           // Different routes to the same backend
           yarp.AddRoute("/api/v1/{**catch-all}", backendService)
               .WithTransformPathRemovePrefix("/api/v1");
               
           yarp.AddRoute("/api/v2/{**catch-all}", backendService)
               .WithTransformPathRemovePrefix("/api/v2")
               .WithTransformPathPrefix("/v2");
       });

Additional documentation

Feedback & contributing

https://github.com/dotnet/aspire

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Aspire.Hosting.Yarp:

Package Downloads
NapalmCodes.Aspire.Hosting.Krakend

Aspire hosting component for the high performance KrakenD (https://www.krakend.io/) API Gateway.

GitHub repositories (3)

Showing the top 3 popular GitHub repositories that depend on Aspire.Hosting.Yarp:

Repository Stars
dotnet/eShop
A reference .NET application implementing an eCommerce site
foxminchan/BookWorm
The practical implementation of Aspire using Microservices, AI-Agents
davidfowl/aspire-ssh-deploy
An extension of the docker compose integration for deploying to a docker host via SSH