Aspire.Hosting.Yarp 9.4.2-preview.1.25428.12

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher.
This is a prerelease version of Aspire.Hosting.Yarp. 
dotnet add package Aspire.Hosting.Yarp --version 9.4.2-preview.1.25428.12
                    


                    

                
NuGet\Install-Package Aspire.Hosting.Yarp -Version 9.4.2-preview.1.25428.12
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="9.4.2-preview.1.25428.12" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Aspire.Hosting.Yarp" Version="9.4.2-preview.1.25428.12" />
                    


                            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 9.4.2-preview.1.25428.12
                    


                    

                
#r "nuget: Aspire.Hosting.Yarp, 9.4.2-preview.1.25428.12"
#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@9.4.2-preview.1.25428.12
#: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=9.4.2-preview.1.25428.12&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Aspire.Hosting.Yarp&version=9.4.2-preview.1.25428.12&prerelease
                    


                            Install as a Cake Tool

Aspire.Hosting.Yarp library

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

Getting started

Install the package

In your AppHost project, install the .NET 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");
                     });

Configuration API

Core methods

Method Description
AddYarp(string name) Adds a YARP container resource to the application
WithConfiguration(Action<IYarpConfigurationBuilder>) Configures YARP programmatically
WithHostPort(int? port) Sets a specific host port instead of random assignment

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

Custom port configuration

var gateway = builder.AddYarp("gateway")
                     .WithHostPort(8080)  // Use specific port
                     .WithConfiguration(yarp => { /* config */ });

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 (2)

Showing the top 2 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 .NET Aspire using Microservices
Version Downloads Last Updated
9.4.2-preview.1.25428.12 604 9/2/2025
9.4.1-preview.1.25408.4 1,343 8/12/2025
9.4.0-preview.1.25378.8 4,295 7/29/2025
9.3.1-preview.1.25305.6 3,827 6/10/2025
9.3.0-preview.1.25265.20 2,011 5/19/2025