Endpoint Routing does not respect AppendTrailingSlash property

[64J0]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Hello, hope you're good.

After creating a Web API based on the official template and trying to set AppendTrailingSlash so that a trailing slash is not added to the route automatically, I noticed that this option does not work.

Expected Behavior

I want to define whether the routes are going to have the trailing slash appended automatically or not per route configuration.

If we can't do this for each route individually, I'd like to at least define this in the global scope.

Steps To Reproduce

• Create a new project using the official template: dotnet new webapi -o SampleAppendTrailingSlash
• Update the Program.cs:

using Microsoft.AspNetCore.Routing;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi().Configure<RouteOptions>(options =>
{
    // vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
    // The route options configuration
    options.AppendTrailingSlash = false;
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

// route without the trailing slash defined
app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

// route with the trailing slash defined
app.MapGet("/weatherforecast/", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecastTrailingSlash");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Exceptions (if any)

fail: Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware[1]
An unhandled exception has occurred while executing the request.
Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException: The request matched multiple endpoints. Matches:

  HTTP: GET /weatherforecast
  HTTP: GET /weatherforecast/
     at Microsoft.AspNetCore.Routing.Matching.DefaultEndpointSelector.ReportAmbiguity(Span`1 candidateState)
     at Microsoft.AspNetCore.Routing.Matching.DefaultEndpointSelector.ProcessFinalCandidates(HttpContext httpContext, Span`1 candidateState)
     at Microsoft.AspNetCore.Routing.Matching.DefaultEndpointSelector.Select(HttpContext httpContext, Span`1 candidateState)
     at Microsoft.AspNetCore.Routing.Matching.DfaMatcher.MatchAsync(HttpContext httpContext)
     at Microsoft.AspNetCore.Routing.EndpointRoutingMiddleware.Invoke(HttpContext httpContext)
     at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)

.NET Version

SDK 9.0.302

Anything else?

Related to giraffe-fsharp/Giraffe#680

[nithyav2017]

I was able to reproduce the issue. The ambiguity is caused by defining two MapGet() routes that differ only by a trailing slash:

app.MapGet("/weatherforecast/", () =>...
app.MapGet("/weatherforecast", () =>...

ASP.NET Core normalizes trailing slashes by default and treats these routes as equivalent for routing purposes, which leads to an AmbiguousMatchException at runtime. To resolve this issue, you can rename one of the routes.

Ex: app.MapGet("/api/weatherforecast/", () =>....

This avoids the conflict and allows both endpoints coexist .

[64J0]

Hello @nithyav2017, thanks for the reply.

My issue is related to ASP.NET Endpoint Routing ignoring the AppendTrailingSlash property, which would control this behavior that you mentioned:

ASP.NET Core normalizes trailing slashes by default and treats these routes as equivalent for routing purposes [...]

In essence, I want to decide per route whether ASP.NET will append the trailing slash or not.

If I can't define it with this granularity level, I'd like to disable it globally.

[MackinnonBuck]

Thanks for reaching out, @64J0.

The XML docs for AppendTrailingSlash state:

Gets or sets a value indicating whether a trailing slash should be appended to the generated URLs.

This does not have an impact on routing, so the behavior you're observing is by design.

If you want to have different endpoints handle each case (trailing slash vs. no trailing slash), the easiest thing is probably to write custom middleware that checks the path manually. However, you can also write a custom MatcherPolicy if you want the routing middleware to handle the distinction.

I've added a Copilot-generated sample below in case that helps.

Step 1: Define marker metadata (attributes)

public interface IRequireTrailingSlashMetadata { }
public interface IForbidTrailingSlashMetadata { }
 
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Delegate, AllowMultiple = false)]
public sealed class RequireTrailingSlashAttribute : Attribute, IRequireTrailingSlashMetadata { }
 
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Delegate, AllowMultiple = false)]
public sealed class ForbidTrailingSlashAttribute : Attribute, IForbidTrailingSlashMetadata { }

Step 2: Implement a MatcherPolicy / EndpointSelectorPolicy

using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing.Matching;
using Microsoft.AspNetCore.Routing;
 
public sealed class TrailingSlashMatcherPolicy : MatcherPolicy, IEndpointSelectorPolicy
{
    // Run late (higher order runs later); choose a number after built-ins you don't want to override.
    public override int Order => 1000;
 
    public bool AppliesToEndpoints(IReadOnlyList<Endpoint> endpoints)
        => endpoints.Any(e =>
            e.Metadata.GetMetadata<IRequireTrailingSlashMetadata>() != null ||
            e.Metadata.GetMetadata<IForbidTrailingSlashMetadata>() != null);
 
    public Task ApplyAsync(HttpContext httpContext, CandidateSet candidates)
    {
        bool hasTrailingSlash = httpContext.Request.Path.HasValue &&
                                httpContext.Request.Path.Value!.Length > 1 &&
                                httpContext.Request.Path.Value!.EndsWith('/');
 
        // First pass: see if any candidate explicitly matches current trailing slash status.
        bool anyRequire = false;
        bool anyForbid  = false;
 
        for (int i = 0; i < candidates.Count; i++)
        {
            if (candidates.IsValidCandidate(i))
            {
                var endpoint = candidates[i].Endpoint;
                if (endpoint.Metadata.GetMetadata<IRequireTrailingSlashMetadata>() != null)
                    anyRequire = true;
                if (endpoint.Metadata.GetMetadata<IForbidTrailingSlashMetadata>() != null)
                    anyForbid = true;
            }
        }
 
        // If neither metadata type appears we do nothing.
        if (!anyRequire && !anyForbid)
            return Task.CompletedTask;
 
        for (int i = 0; i < candidates.Count; i++)
        {
            if (!candidates.IsValidCandidate(i))
                continue;
 
            var endpoint = candidates[i].Endpoint;
            bool requires = endpoint.Metadata.GetMetadata<IRequireTrailingSlashMetadata>() != null;
            bool forbids  = endpoint.Metadata.GetMetadata<IForbidTrailingSlashMetadata>() != null;
 
            if (requires && !hasTrailingSlash)
            {
                candidates.SetValidity(i, false);
            }
            else if (forbids && hasTrailingSlash)
            {
                candidates.SetValidity(i, false);
            }
        }
 
        return Task.CompletedTask;
    }
}

Step 3: Register the policy (in Program.cs)

builder.Services.AddSingleton<MatcherPolicy, TrailingSlashMatcherPolicy>();

Step 4: Map your endpoints with metadata (both use the same pattern "/item")

var app = builder.Build();
 
app.MapGet("/item", () => Results.Text("No trailing slash"))
   .WithMetadata(new ForbidTrailingSlashAttribute());
 
app.MapGet("/item", () => Results.Text("With trailing slash"))
   .WithMetadata(new RequireTrailingSlashAttribute());
 
// Or using attributes directly on minimal API delegates is not possible, so WithMetadata is fine.
 
app.Run();

Behavior:

• GET /item → “No trailing slash”
• GET /item/ → “With trailing slash”
• Other endpoints unaffected.
• Link generation: Both endpoints share the same route pattern. When you use link generation (e.g., Url.Link), routing will pick one arbitrarily (based on endpoint order) unless you also add a custom EndpointName or other disambiguating metadata. If you need link generation to respect the trailing slash, you might define separate endpoint names and call them explicitly.

Notes and caveats:

1. There is still only one logical route pattern; you are differentiating at the endpoint selection stage, not at pattern parsing.
2. This is more complex than just putting a conditional in a single handler. Only do this if distinct handlers are genuinely required (e.g., very different behavior / auth / metadata).
3. Endpoint filters won’t help: they run after an endpoint is already selected.
4. RouteOptions (AppendTrailingSlash, SuppressCheckForUnhandledSecurityMetadata, LowercaseUrls, etc.) do not affect matching semantics—just link generation or other behaviors.
5. Classic IApplicationBuilder.Map("/item", ...) style branching can also distinguish paths, but you asked to avoid pipeline branching; the policy keeps everything inside endpoint routing.

Alternative (lighter) approach if you can accept one handler:

app.MapGet("/item", (HttpContext ctx) =>
{
    bool trailing = ctx.Request.Path.Value!.EndsWith('/');
    return trailing ? "With slash" : "Without slash";
});

But if you want fully separate endpoints without “manual” middleware, the custom MatcherPolicy / EndpointSelectorPolicy is the extensibility point the framework provides.

Summary:

• No configuration knob exists to make trailing slash part of the match in minimal APIs.
• Use either logic inside one handler, a small middleware, or a custom matcher policy (shown above) to disambiguate.
• The matcher policy approach keeps your routing model pure and avoids ad-hoc middleware while still leveraging endpoint routing.

[nithyav2017]

Thanks for the detailed explanation and sample. This really helped to clarify the distinction between link generation and request matching. I had originally focused on URL matching behavior and ambiguity caused by defining two MapGet() routes that differ only by slash. So, It was helpful to confirm that AppendTrailingSlash only affects LinkGenerator, not routing behavior and realized that routing treats trailing slashes as equivalent unless filtered manually.