Edit

Get started with YARP

YARP is designed as a .NET library that provides core proxy functionality. You can customize the library by adding or replacing modules. YARP is currently provided as a NuGet package and code samples, but a project template and prebuilt executable (.exe) are planned for the future.

YARP is implemented on top of .NET infrastructure and is usable on Windows, Linux, or macOS. You can develop apps with the .NET SDK and your favorite editor: Microsoft Visual Studio or Visual Studio Code.

YARP 2.3.0 supports .NET 8 or later. You can download the .NET SDK from https://dotnet.microsoft.com/download/dotnet/.

This article describes how to create a basic ASP.NET Core app that uses the YARP library.

Create a new project

Start by creating an empty ASP.NET Core app from the command line:

dotnet new web -n MyProxy

Or, build a new ASP.NET Core web app in Visual Studio 2022 by selecting Empty for the project template.

Note

For the complete version of the project implemented in this article, download the Basic YARP Sample on GitHub.

Add the YARP 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.cs 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();

Customize the YARP configuration

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

You can also specify the configuration programmatically. For more information, see YARP extensibility: Configuration providers.

To learn more about the available configuration options, see the RouteConfig and ClusterConfig reference articles.

 {
  "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 your YARP project application

To run your new YARP project:

  • .NET CLI: Run the dotnet run command within the sample's directory, or use the dotnet run --project <path to .csproj file> command.

  • Visual Studio: Start the app by selecting Run on the main menubar.

Related content

  • Last updated on