Custom Endpoints and Endpoint Metadata Standards?

[nquandt]

I've been searching for a few days for guides as to implementing my own Endpoints via an EndpointDataSource implementation. Where I'm struggling the most is finding information on which metadata objects are used for Authorization/Authentication, HttpMethods, Host, etc. As well as there is seemingly only the source code for YARP and this blog to go off of for seeing how to implement EndpointDataSource.

I can see them used in YARP:
EndpointDataSource

Metadata Add

But am wondering if there are any plans to more formally document how someone might go about creating an endpoint implementation.

I understand that in the following example I would miss out on any "minimal api" specific functionality but believe I should be able to augment this RouteEndpoint, (or a custom Endpoint and Matcher? / IRouter?) to plug into other middleware functionality like Auth.

using Microsoft.AspNetCore.Routing.Patterns;


var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Step 1: Create a RequestDelegate (handler)
RequestDelegate handler = async (HttpContext context) =>
{
    await context.Response.WriteAsync("Hello from custom RouteEndpoint!");
};

// Step 2: Create a RouteEndpoint manually
var routeEndpoint = new RouteEndpoint(
    requestDelegate: handler,
    routePattern: RoutePatternFactory.Parse("/"),
    order: 0,
    metadata: new EndpointMetadataCollection(),
    displayName: "Custom RouteEndpoint"
);

// Step 3: Create an EndpointDataSource that holds custom endpoints
var dataSource = new DefaultEndpointDataSource(routeEndpoint); // could create a custom one of these

// Step 4: Register middleware to use custom endpoint resolution
app.UseRouting();

((IEndpointRouteBuilder)app).DataSources.Add(dataSource);

// Step 5: Start the app
app.Run();

Mostly I'm looking for:

How can I know when to do this and with what classes/instances?

if (hosts is not null && hosts.Count != 0)
{
    endpointBuilder.Metadata.Add(new HostAttribute(hosts.ToArray()));
}

Are there any plans to break out the Metadata.Add calls into ConventionBuilders for each concern? So that someone building a library could call

endpointBuilder.ApplyHostsMetadata(hosts);

My goal: register endpoints based on a custom spec. similar to YARP.
My concern: I use yarp's code as a guide but wont be able to know if the Metadata objects ever have breaking changes.
My hope: Explicit docs, guides, or public API's that guide a developer to success by default.

I am willing to collaborate/contribute as I can. If there were any guidance on this I'd be happy to pick it up to build a proposal but I'm starting somewhat in the dark based on all information I could find.

Any discussion is welcome. Thanks

[nquandt]

@Tratcher I was wondering if you had any suggestions regarding the endpointBuilder.Metadata.Add( methods if any standards or documentation exist? Or if you could point me to anyone who could help?

Thanks!

[davidfowl]

There are no docs for the level of detail you are looking at. This is framework author level docs and we don’t prioritize those. We expect 1% of people to create these implementations, that said, if there’s something you are trying to accomplish, we can point you in the right direction.

[nquandt]

I think with that I'll go the route of trying to build out my endpoint registrations by following the patterns in the YARP repo, and if I get stuck I'll come back and provide a flushed out example of what I'm looking to do. Thanks for the insight, I appreciate it!

[davidfowl]

The biggest reason YARP has a custom data source is because routes can change at runtime.