Getting started with YARP

Article
2025-04-03

YARP is designed as a library that provides the core proxy functionality, which you can customize by adding or replacing modules. YARP is currently provided as a NuGet package and code samples. We plan on providing a project template and prebuilt executable (.exe) in the future.

YARP is implemented on top of .NET Core infrastructure and is usable on Windows, Linux or MacOS. Development can be done with the SDK and your favorite editor, Microsoft Visual Studio or Visual Studio Code.

YARP 2.3.0 supports ASP.NET Core 8.0 and newer.

You can download the .NET SDK from https://dotnet.microsoft.com/download/dotnet/.

Create a new project

A complete version of the project built using the steps below can be found at Basic YARP Sample.

Start by creating an empty ASP.NET Core application using the command line:

dotnet new web -n MyProxy

Alternatively, create a new ASP.NET Core web application in Visual Studio 2022, choosing "Empty" for the project template.

Add the package reference

Add a package reference for Yarp.ReverseProxy, version 2.3.0 or later.

dotnet add package Yarp.ReverseProxy

Note

For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.

Add the YARP Middleware

Update the Program file to use the YARP Middleware:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
var app = builder.Build();
app.MapReverseProxy();
app.Run();

Configuration

The configuration for YARP is defined in the appsettings.json file. For more information, see YARP Configuration Files.

The configuration can also be provided programmatically. For more information, see YARP Extensibility Configuration Providers.

Learn more about the available configuration options by looking at RouteConfig and ClusterConfig.

{
 "Logging": {
   "LogLevel": {
     "Default": "Information",
     "Microsoft": "Warning",
     "Microsoft.Hosting.Lifetime": "Information"
   }
 },
 "AllowedHosts": "*",
 "ReverseProxy": {
   "Routes": {
     "route1" : {
       "ClusterId": "cluster1",
       "Match": {
         "Path": "{**catch-all}"
       }
     }
   },
   "Clusters": {
     "cluster1": {
       "Destinations": {
         "destination1": {
           "Address": "https://example.com/"
         }
       }
     }
   }
 }
}

Run the project

When using the .NET CLI, use dotnet run within the sample's directory or dotnet run --project <path to .csproj file>.

In Visual Studio, start the app by clicking the Run button.

Share via