Ocelot.Config 1.1.3

Ocelot.Config

Zero-boilerplate API Gateway for ASP.NET Core microservices, built on top of Ocelot.

Ocelot.Config eliminates the repetitive gateway setup that every microservice project needs. Install the package, write two lines of code, and the gateway automatically discovers your services, reads their controllers, and generates a complete ocelot.json — routes, downstream ports, and JWT protection included.

Features

• One-line setup — AddOcelotConfig() loads ocelot.json (with hot-reload) and registers Ocelot; UseOcelotConfig() mounts the gateway pipeline.
• Automatic route generation at build time — scans all ASP.NET Core Web projects in your solution, parses controller [Route] / [HttpGet] / [HttpPost] ... attributes, and reads the HTTP port from each project's Properties/launchSettings.json.
• Microservice-style routes out of the box — for CRUD controllers it generates plural collection routes (/api/users) plus singular catch-all routes (/api/user/{everything}), the same pattern used by most production gateways.
• JWT protection per route — protected routes get AuthenticationOptions with Bearer; mark routes public via [AllowAnonymous] or the PublicRoutePatterns configuration.
• Never overwrites your work — once ocelot.json exists it is left untouched; regenerate explicitly when needed.
• Full Ocelot power — chain anything Ocelot offers (e.g. AddDelegatingHandler<T>()) because AddOcelotConfig() returns the Ocelot builder.
• Multi-targeted — net8.0, net9.0 and net10.0.

Requirements

• .NET SDK 8.0 or newer (8, 9 or 10)
• An ASP.NET Core project (Microsoft.NET.Sdk.Web) as the gateway
• Ocelot 24.x is bundled with the package

Installation

dotnet add package Ocelot.Config

Quick Start

Replace your gateway Program.cs with:

using Ocelot.Config;

var builder = WebApplication.CreateBuilder(args);

// Loads ocelot.json + registers Ocelot services.
// The package generates ocelot.json automatically on the first build.
builder.AddOcelotConfig()
       .AddDelegatingHandler<MyCustomHandler>(); // optional, Ocelot builder chaining

var app = builder.Build();

// Mounts the Ocelot gateway pipeline.
await app.UseOcelotConfig();

app.Run();

Then simply build the project. The package:

1. Scans the solution for sibling ASP.NET Core Web projects (e.g. your Identity, Order, Payment services),
2. Reads each service's HTTP port from its Properties/launchSettings.json,
3. Parses every *Controller.cs for route attributes,
4. Writes a complete, ready-to-run ocelot.json into your gateway project.

How Route Generation Works

Port discovery

Each Web project's port comes from its Properties/launchSettings.json (http://localhost:<port>), preferring the http profile.

Route rules per controller

Authentication

The generator mirrors ASP.NET Core's own semantics — it reads the same attributes your services use at runtime, so the gateway's security posture always matches the services:

• A route is protected (gets AuthenticationOptions with provider key Bearer) when its action or controller class has an [XxxAuthorize] attribute — e.g. [Authorize], [Authorize(Roles = ...)], or custom attributes like [PermissionAuthorize("USERS_VIEW")]. Any attribute name ending in Authorize is recognized.
• A route with no authorize attribute is public — exactly as it is at runtime in the downstream service.
• [AllowAnonymous] on an action always makes it public (overrides a class-level [Authorize]), matching ASP.NET behavior.
• PublicRoutePatterns in ocelot.generator.json force a route public even if it has an authorize attribute (explicit escape hatch).

Configuration — ocelot.generator.json

Place this optional file in your gateway project to tune the generated ocelot.json:

{
  "BaseUrl": "http://localhost:5050",
  "PublicRoutePatterns": [
    "/auth/login",
    "/auth/forgot-password",
    "/register"
  ],
  "ExtraRoutes": [
    {
      "UpstreamPathTemplate": "/uploads/{everything}",
      "DownstreamPathTemplate": "/uploads/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [{ "Host": "localhost", "Port": 5062 }]
    }
  ]
}

Swagger UI integration (MMLib.SwaggerForOcelot)

If your gateway uses UseSwaggerForOcelotUI(), it requires a SwaggerEndPoints section. Provide it through ocelot.generator.json:

{
  "BaseUrl": "http://localhost:5050",
  "GlobalConfiguration": {
    "SwaggerEndPoints": [
      {
        "Key": "identity",
        "Config": [{ "Name": "Identity API", "Version": "v1", "Url": "http://localhost:5062/swagger/v1/swagger.json" }]
      },
      {
        "Key": "order",
        "Config": [{ "Name": "Order API", "Version": "v1", "Url": "http://localhost:5018/swagger/v1/swagger.json" }]
      }
    ]
  }
}

---

## Regenerating Routes

The generator runs on **every build** and keeps `ocelot.json` in sync automatically:

- **No `ocelot.json` yet** → generated.
- **Previously generated, unchanged by you** → regenerated when services change, so **new endpoints you add to any service appear in the gateway after the next `dotnet run` / `dotnet build`**.
- **Hand-edited** → left alone (your edits are never overwritten), with a build message telling you so.
- **Force regeneration** anytime:

```bash
dotnet build -p:OcelotConfigRegenerate=true

Manual edits are tracked via a sidecar file (ocelot.generated.marker) next to ocelot.json; delete it if you want the generator to manage the file again.

Editing Routes Manually

The generated ocelot.json is standard Ocelot configuration — every Ocelot feature (rate limiting, caching, load balancing, QoS, transformations, etc.) works. Hand-edit it freely; the generator will not overwrite your changes unless you explicitly force regeneration.

Example Generated ocelot.json

{
  "Routes": [
    {
      "UpstreamPathTemplate": "/auth/login",
      "DownstreamPathTemplate": "/auth/login",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [{ "Host": "localhost", "Port": 5062 }]
    },
    {
      "UpstreamPathTemplate": "/api/users",
      "DownstreamPathTemplate": "/api/users",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [{ "Host": "localhost", "Port": 5062 }],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "UpstreamPathTemplate": "/api/user/{everything}",
      "DownstreamPathTemplate": "/api/user/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [{ "Host": "localhost", "Port": 5062 }],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:5050"
  }
}

Release Notes

• 1.1.3 — Attribute-based authentication: routes are protected only when their action/controller has an [XxxAuthorize] attribute ([Authorize], [PermissionAuthorize], custom); no authorize attribute = public, mirroring ASP.NET Core semantics. [AllowAnonymous] and PublicRoutePatterns still force public.
• 1.1.2 — Auto-update: generator runs on every build and keeps ocelot.json in sync (new endpoints appear automatically), while never overwriting hand-edited files.
• 1.1.1 — GlobalConfiguration merge support in ocelot.generator.json (e.g. SwaggerEndPoints for MMLib.SwaggerForOcelot).
• 1.1.0 — Package README added. First versioned release.
• 1.0.x — Development versions (local testing only).

License

Licensed under the MIT License.