# Valiant endpoints Documentation version: 1. This context contains only this version. Source revision: 34222bb7277ce1a771ae4412d572b56f5eb98237. ## Endpoints Source: https://valiant.staticnorth.dev/endpoints/ # Minimal APIs, organized by feature Valiant Endpoints gives every ASP.NET Core Minimal API endpoint a small class and generates deterministic route registration. Group vertical slices, apply conventions once, exclude features at startup, and bind query shapes that ASP.NET Core does not handle by default. ```csharp using StaticNorth.Valiant.Endpoints; using StaticNorth.Valiant.Endpoints.AspNetCore; [ValiantEndpoint] internal sealed class ListTodosEndpoint : IEndpoint { public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) => builder.MapGet("/", () => Results.Ok()); } ``` ```csharp builder.Services.AddValiantEndpoints(); var app = builder.Build(); app.MapValiantEndpoints(); ``` ## What it covers | Capability | API | | --- | --- | | Generated discovery | `[ValiantEndpoint]`, `[ValiantEndpoint]`, `[ValiantEndpointGroup]` | | Route organization | `IEndpoint`, `IEndpointGroup`, standalone and grouped routes | | Shared policy | Group and endpoint configuration hooks over the returned route builders | | Feature switches | Separate startup predicates for generated groups and endpoints | | Multiple assemblies | Explicit registration and mapping overloads | | Query compatibility | Arrays, nested objects, JSON opt-in, parser, serializer, and structured errors | | Request binding | Opt-in generated `BindAsync`, `[AsParameters]` repair, and complex `[FromQuery]` shims; native ASP.NET Core binding by default | ## Documentation map - [Quick start](https://valiant.staticnorth.dev/endpoints/quick-start) - [Runnable samples](https://valiant.staticnorth.dev/endpoints/samples) - [Groups and conventions](https://valiant.staticnorth.dev/endpoints/guides/groups-conventions) - [Conditional registration](https://valiant.staticnorth.dev/endpoints/guides/conditional-registration) - [Request binding](https://valiant.staticnorth.dev/endpoints/guides/request-binding) - [Query parameter reference](https://valiant.staticnorth.dev/endpoints/reference/query-parameters) - [Registration, generation, and diagnostics](https://valiant.staticnorth.dev/endpoints/reference/registration-generation) The [sample catalog](https://valiant.staticnorth.dev/endpoints/samples) covers every selectable startup in the runnable endpoint-per-class host, including generated binding and intentional conditional exclusions. ## Quick start Source: https://valiant.staticnorth.dev/endpoints/quick-start # Quick start ## 1. Install ```bash dotnet add package StaticNorth.Valiant.Endpoints.AspNetCore ``` This is the consumer package. It includes the shared endpoint contracts and bundles the source generator; do not add separate `StaticNorth.Valiant.Endpoints` or generator references. ## 2. Create an endpoint ```csharp using StaticNorth.Valiant.Endpoints; using StaticNorth.Valiant.Endpoints.AspNetCore; [ValiantEndpoint] internal sealed class HealthEndpoint : IEndpoint { public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) { return builder.MapGet("/health", () => Results.Ok(new { status = "ready" })); } } ``` `[ValiantEndpoint]` makes it a standalone endpoint on the root route builder. ## 3. Register and map ```csharp using StaticNorth.Valiant.Endpoints.AspNetCore.DependencyInjection; builder.Services.AddValiantEndpoints(); var app = builder.Build(); app.MapValiantEndpoints(); app.Run(); ``` Registration discovers generated registrar metadata from the calling and entry assemblies. Mapping resolves those registrars and invokes each generated route plan. ## 4. Put endpoints in a group ```csharp [ValiantEndpointGroup] internal sealed class TodosEndpointGroup : IEndpointGroup { public static RouteGroupBuilder CreateGroup(IEndpointRouteBuilder builder) => builder.MapGroup("/api/todos").WithTags("Todos"); } [ValiantEndpoint] internal sealed class GetTodoEndpoint : IEndpoint { public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) => builder.MapGet("/{id:guid}", (Guid id) => Results.Ok(id)); } ``` Every endpoint group must implement `CreateGroup`; Valiant does not derive group routes from type names. Next: centralize tags, filters, OpenAPI, and naming in [Groups and conventions](https://valiant.staticnorth.dev/endpoints/guides/groups-conventions). ## Conditional registration Source: https://valiant.staticnorth.dev/endpoints/guides/conditional-registration # Conditional registration Configure generated groups and endpoints independently: ```csharp builder.Services.AddValiantEndpoints(options => { options.MapEndpointGroupsWhen = group => group.GroupType != typeof(ExperimentalEndpointGroup) || builder.Environment.IsDevelopment(); options.MapEndpointWhen = endpoint => endpoint.EndpointType != typeof(DeprecatedEndpoint); }); ``` Each predicate receives generated registration metadata while `MapValiantEndpoints()` runs at startup. Both policies allow every generated registration by default. Assigning either property again replaces its previously configured predicate. See the [runnable conditional-registration sample](https://valiant.staticnorth.dev/endpoints/samples#conditional-registration) for allowed and rejected group and standalone endpoint routes. `EndpointGroupRegistration` exposes: - `GroupType`; - generated mapping `Order`. `EndpointRegistration` exposes: - `EndpointType`; - the optional containing `Group`; - generated mapping `Order`; - `IsGrouped`; - the pre-mapping `QueryParameters` snapshot. The query snapshot reports whether binding support was generated, whether runtime binding filters are enabled, and the parsing options known before `IEndpoint.Map(...)` executes. It cannot include route patterns, HTTP methods, tags, authorization, or endpoint-authored `.WithQueryParsingOptions(...)` metadata because those are created during mapping. For a group inferred from referenced generated endpoints, `Order` is the lowest generated child order used to place that group. Previously compiled generated registrars did not carry order metadata, so the compatibility bridge reports `0` for those legacy registrations. ## Exclude a whole group ```csharp options.MapEndpointGroupsWhen = group => group.GroupType != typeof(AdminEndpointGroup); ``` Returning `false` for a group skips: - group creation; - all generated endpoints assigned to that group; - the `ConfigureEndpointGroup` hook. The endpoint predicate is not evaluated for endpoints in an excluded group. ## Exclude individual endpoints ```csharp options.MapEndpointWhen = endpoint => endpoint.EndpointType != typeof(DeleteAccountEndpoint); ``` Returning `false` for an endpoint excludes only that grouped or standalone endpoint. Other endpoints in its group still map normally. ## Combine feature flags, environment, and metadata ```csharp var disabled = new HashSet { typeof(LegacyReportsEndpoint), typeof(PreviewEndpointGroup) }; builder.Services.AddValiantEndpoints(options => { options.MapEndpointGroupsWhen = group => !disabled.Contains(group.GroupType) && (!group.GroupType.Name.StartsWith("Internal", StringComparison.Ordinal) || builder.Environment.IsDevelopment()); options.MapEndpointWhen = endpoint => !disabled.Contains(endpoint.EndpointType) && (!endpoint.EndpointType.Name.StartsWith("Internal", StringComparison.Ordinal) || builder.Environment.IsDevelopment()); }); ``` You can also inspect custom attributes on each `Type`, configuration, license state, or a precomputed feature snapshot. Keep the predicates fast and deterministic because they run synchronously during route construction. ## Configure parsing conditionally Use a separate rule when selected endpoint registrations need different parsing: ```csharp options.ConfigureEndpointWhen( endpoint => endpoint.Group?.GroupType == typeof(SearchEndpointGroup), endpointOptions => endpointOptions.QueryParameters.Parsing = new QueryParsingOptions { SupportedArrayFormats = [QueryArrayFormat.CommaSeparated], SupportedObjectFormats = [QueryObjectFormat.Flat] }); ``` All rule predicates observe the same initial pre-mapping snapshot. Matching actions run in registration order before `MapEndpointWhen` evaluates the final descriptor. Parsing precedence is: 1. Explicit `[ValiantQueryParsing]` properties. 2. Endpoint-authored `.WithQueryParsingOptions(...)`. 3. Conditional registration configuration. 4. Global `ValiantEndpointOptions.QueryParameters.Parsing`. `EnableBinding` remains a compilation-wide generator decision. Set `options.QueryParameters.EnableBinding = true` directly in the `AddValiantEndpoints` setup lambda when generated binding is required. Conditional parsing rules cannot generate or remove `BindAsync` and direct `TryParse` members. ## Migrate from `ShouldMap` Split the old shared predicate by registration kind: ```csharp // Before options.ShouldMap = type => !disabled.Contains(type); // After options.MapEndpointGroupsWhen = group => !disabled.Contains(group.GroupType); options.MapEndpointWhen = endpoint => !disabled.Contains(endpoint.EndpointType); ``` :::warning Startup decision, not request routing The predicates are evaluated once when endpoints are mapped. They do not change routes after startup and are not a substitute for authorization or per-request feature evaluation. ::: :::info Generated registrations only Routes mapped directly with ASP.NET Core are outside Valiant's generated mapping policy. Apply application-specific conditions to those routes directly. ::: ## Groups and conventions Source: https://valiant.staticnorth.dev/endpoints/guides/groups-conventions # Groups and conventions ## Create groups Every endpoint group implements `CreateGroup` and explicitly chooses its route and group-level metadata: ```csharp [ValiantEndpointGroup(Order = 10)] internal sealed class OrdersEndpointGroup : IEndpointGroup { public static RouteGroupBuilder CreateGroup(IEndpointRouteBuilder builder) => builder .MapGroup("/api/orders") .WithTags("Orders") .RequireAuthorization(); } ``` ## Global conventions ```csharp builder.Services.AddValiantEndpoints(options => { options.ConfigureEndpointGroup = (group, registration) => { group.AddEndpointFilter(); group.WithOpenApi(); }; options.ConfigureEndpoint = (endpoint, registration) => endpoint.WithName(registration.EndpointType.Name); }); ``` The generated sequence is: 1. Create the group through its required `CreateGroup` implementation. 2. Associate its `EndpointGroupRegistration`. 3. Run `ConfigureEndpointGroup`. 4. Map each included endpoint and apply Valiant binding and parsing conventions. 5. Run `ConfigureEndpoint` with that endpoint's `EndpointRegistration`. Both hooks are actions over the builders returned by `IEndpointGroup.CreateGroup(...)` and `IEndpoint.Map(...)`. The group hook cannot replace the returned builder. Put route prefixes and nested `MapGroup(...)` calls in the group's `CreateGroup` implementation. `EndpointGroupRegistration` exposes the group type and generated order. `EndpointRegistration` exposes the endpoint type, containing group, generated order, and query-binding snapshot, so global conventions can branch without repeating reflection-based discovery. See the [runnable configuration sample](https://valiant.staticnorth.dev/endpoints/samples#configuration-hooks) for two grouped routes where a group hook adds a shared response header and an endpoint hook adds a second header only to the selected endpoint. ## Migrating the earlier preview hooks The earlier preview exposed three callbacks. Consolidate them as follows: - Move both `ConfigureAllEndpointGroupsBeforeMapping` and `ConfigureAllEndpointGroupsAfterMapping` conventions into `ConfigureEndpointGroup`. - Replace `ConfigureAllEndpointsAfterMapping` with `ConfigureEndpoint`. - Replace callback `Type` parameters with `registration.GroupType` or `registration.EndpointType`. - Move any callback that returned `group.MapGroup(...)` into `IEndpointGroup.CreateGroup(...)`. ## Ordering Set `Order` on endpoint and group marker attributes when one generated mapping must precede another: ```csharp [ValiantEndpoint(Order = -100)] internal sealed class SearchOrdersEndpoint : IEndpoint { /* ... */ } ``` Types with the same order are sorted by type name, keeping generated output deterministic. ## Standalone endpoints `[ValiantEndpoint]` without a group maps directly on the supplied root route builder. The same `ConfigureEndpoint` hook and `MapEndpointWhen` registration policy apply; its registration has `Group == null`. ## Request binding Source: https://valiant.staticnorth.dev/endpoints/guides/request-binding # Request binding Valiant query binding is disabled by default, leaving request parameters to native ASP.NET Core binding. Enable generated binding in the same project as the endpoint declarations with a direct assignment: ```csharp builder.Services.AddValiantEndpoints(options => { options.QueryParameters.EnableBinding = true; }); ``` Changing the literal between `true` and `false` adds or removes generated query binding during the normal rebuild. Helper methods, runtime variables, and a host configuration in another assembly are not compile-time opt-ins. :::caution Compile-time boundary `EnableBinding` is not a fully dynamic runtime switch. Whole-request `BindAsync` and `[AsParameters]` processing can read runtime options, but a generated direct `TryParse(string, out T)` has no `HttpContext`. If the endpoint compilation contains a recognized literal `true`, another host or later runtime override to `false` cannot remove or neutralize that direct parser. Compile the endpoint project with no recognized `true` assignment when `[ValiantQueryParsing]` must be ignored. ::: When enabled, Valiant connects its configurable query parser to generated endpoints in three binding shapes. ## Whole request binding Make the request `partial` and place `[FromQuery]` on query members: ```csharp return builder.MapGet("/cars", static (ListCarsRequest request) => Results.Ok(request.Filter)); public sealed partial record ListCarsRequest { [FromQuery] public CarFilter? Filter { get; init; } } public sealed record CarFilter(int? Year, string? Brand); ``` Valiant emits `BindAsync(HttpContext, ParameterInfo)` on `ListCarsRequest` and parses the full query through the configured policy. If the request is nested inside an endpoint or another type, every containing declaration must also be `partial` so generated code can reopen the complete declaration chain. ## `[AsParameters]` ASP.NET Core first constructs the request; a Valiant endpoint filter then reparses the full query and copies `[FromQuery]` values back: ```csharp return builder.MapGet("/cars", static ([AsParameters] ListCarsRequest request) => Results.Ok(request.Filter)); public sealed record ListCarsRequest { [FromQuery] public CarFilter? Filter { get; init; } } public sealed partial record CarFilter(int? Year, string? Brand); ``` The complex `[FromQuery]` type must be `partial` in this shape. Valiant generates a `TryParse(string, out T)` shim because ASP.NET Core checks property bindability before endpoint filters run. The same containing-type rule applies when that complex type is nested. The Valiant filter runs after native property binding, so it cannot recover from a format that makes ASP.NET Core fail the initial property conversion. For example, comma-separated `?ids=1,2,3` fails before the filter for an `int[] Ids` property. Use generated whole-request binding when every configured format must work without native `[AsParameters]` constraints. ## Direct complex `[FromQuery]` Complex query types used directly also need to be source-declared and `partial` so the generator can add the compatibility parser. ```csharp return builder.MapGet("/cars", static ([FromQuery] CarFilter filter) => Results.Ok(filter)); public sealed partial record CarFilter(int? Year, string? Brand); ``` ASP.NET Core calls the generated `TryParse` method to bind the value. Configure its JSON policy on the endpoint: ```csharp [ValiantEndpoint] [ValiantQueryParsing(JsonValues = JsonQueryValues.Disabled)] public sealed class CarsEndpoint : IEndpoint { public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) => builder.MapGet("/cars", static ([FromQuery] CarFilter filter) => Results.Ok(filter)); } ``` The policy is compiled into the generated method, so direct binding does not use an endpoint filter. When the endpoint project is compiled with `options.QueryParameters.EnableBinding = false`, the attribute is ignored and no Valiant query parser is emitted. A later runtime-only override cannot change an already-generated direct parser; see the compile-time boundary above. When binding is enabled, JSON remains enabled when the attribute is absent or parameterless. Explicit `Disabled` returns HTTP 400. `SupportedArrayFormats` and `SupportedObjectFormats` on the attribute do not affect direct parameters. The attribute does not change a user-authored `TryParse`. Conflicting policies for the same generated parser type report `VLE011`. ## Failure response Generated binders and the Valiant query-binding filter return HTTP 400 with structured `QueryError` entries when values cannot be converted or a client uses a disabled format. Each entry identifies a `Path`, stable `Code`, human-readable `Message`, and `Kind` (`Validation` or `Configuration`). ## Configure accepted formats ```csharp builder.Services.AddValiantEndpoints(options => { options.QueryParameters.EnableBinding = true; options.QueryParameters.Parsing = new QueryParsingOptions { SupportedArrayFormats = [ QueryArrayFormat.RepeatedKeys, QueryArrayFormat.CommaSeparated ], SupportedObjectFormats = [ QueryObjectFormat.Flat, QueryObjectFormat.DotNotation ] }; }); ``` Replace the global parsing rules for whole-request and `[AsParameters]` binding on one endpoint when needed: ```csharp return builder.MapGet("/search", Handle) .WithQueryParsingOptions(new QueryParsingOptions { SupportedObjectFormats = [QueryObjectFormat.Flat], EnableJsonQueryValues = true }); ``` This is a full replacement, not a merge. Other endpoints continue using the global parsing options. When only selected settings differ, use a partial attribute override: ```csharp [ValiantEndpoint] [ValiantQueryParsing( SupportedArrayFormats = [ QueryArrayFormat.RepeatedKeys, QueryArrayFormat.CommaSeparated ], SupportedObjectFormats = [ QueryObjectFormat.Flat, QueryObjectFormat.DotNotation ], JsonValues = JsonQueryValues.Disabled)] public sealed partial class SearchEndpoint : IEndpoint { // ... } ``` Explicit attribute properties win over `.WithQueryParsingOptions(...)`, which wins over global parsing options and then defaults. Omitted or `null` array properties inherit; `[]` disables every format in that category. The array and object properties affect full-query binding only. Explicit `JsonValues` affects full-query binding and generated direct complex `[FromQuery]`; when omitted, full-query binding inherits while direct JSON remains enabled. See the [query parameter reference](https://valiant.staticnorth.dev/endpoints/reference/query-parameters) for all formats and direct parser/serializer APIs. ## Query parameters Source: https://valiant.staticnorth.dev/endpoints/reference/query-parameters # Query parameter parsing and serialization Inbound parsing and outbound serialization use separate options. An API can accept several client conventions while emitting one stable format. Generated endpoint binding is opt-in and disabled by default: ```csharp builder.Services.AddValiantEndpoints(options => { options.QueryParameters.EnableBinding = true; }); ``` The direct literal assignment must be in the same compilation as the endpoints so the source generator can add the binding members. Direct calls to `QueryStringParser` and `QueryStringSerializer` do not require endpoint binding to be enabled. `EnableBinding` is a compile-time opt-in, not a fully dynamic runtime switch. Whole-request `BindAsync` and `[AsParameters]` processing can resolve runtime options, but a generated direct `TryParse(string, out T)` has no `HttpContext`. Once a recognized literal `true` causes that parser to be compiled, another host or runtime override to `false` cannot remove or neutralize it. Compile the endpoint project with no recognized `true` assignment when `[ValiantQueryParsing]` must be ignored. ## Defaults ```csharp var parsing = new QueryParsingOptions { SupportedArrayFormats = [QueryArrayFormat.RepeatedKeys], SupportedObjectFormats = [QueryObjectFormat.Flat], EnableJsonQueryValues = false }; var serialization = new QuerySerializationOptions { ArrayFormat = QueryArrayFormat.RepeatedKeys, ObjectFormat = QueryObjectFormat.Flat }; ``` ## Array formats | Value | Example | | --- | --- | | `RepeatedKeys` | `?ids=1&ids=2&ids=3` | | `CommaSeparated` | `?ids=1,2,3` | | `Brackets` | `?ids[]=1&ids[]=2&ids[]=3` | | `IndexedBrackets` | `?ids[0]=1&ids[1]=2&ids[2]=3` | Enable every accepted inbound format explicitly: ```csharp new QueryParsingOptions { SupportedArrayFormats = [ QueryArrayFormat.RepeatedKeys, QueryArrayFormat.CommaSeparated, QueryArrayFormat.Brackets, QueryArrayFormat.IndexedBrackets ] }; ``` Repeated and bracket values preserve query order; indexed brackets sort by numeric index. Empty items and disabled formats return structured errors. ## Object formats | Value | Example | | --- | --- | | `Flat` | `?brand=tesla&year=2025` | | `DotNotation` | `?filter.brand=tesla&filter.year=2025` | | `DeepObject` | `?filter[brand]=tesla&filter[year]=2025` | Duplicate scalar values use the last value. Flat output cannot preserve nested paths; choose dot notation, deep object, or explicitly enabled JSON for nested serialization. ## JSON query values `QueryStringParser` and generated whole-request binding disable JSON by default. Opt in only for endpoints that intentionally accept URL-encoded JSON objects: ```csharp new QueryParsingOptions { EnableJsonQueryValues = true }; ``` For a single mapped endpoint using generated whole-request or `[AsParameters]` binding, replace the global parsing policy: ```csharp return builder.MapGet("/search", Handle) .WithQueryParsingOptions(new QueryParsingOptions { SupportedObjectFormats = [QueryObjectFormat.Flat], EnableJsonQueryValues = true }); ``` For `[AsParameters]`, the policy is applied after ASP.NET Core has performed native property binding. Formats that fail that initial conversion, such as comma-separated input for an `int[]` property, require generated whole-request binding instead. For a partial source-generated override, place `[ValiantQueryParsing]` on the endpoint class: ```csharp [ValiantEndpoint] [ValiantQueryParsing( SupportedArrayFormats = [ QueryArrayFormat.RepeatedKeys, QueryArrayFormat.CommaSeparated ], SupportedObjectFormats = [ QueryObjectFormat.Flat, QueryObjectFormat.DotNotation ], JsonValues = JsonQueryValues.Disabled)] public sealed partial class SearchEndpoint : IEndpoint { // ... } ``` Precedence is explicit attribute properties, then the last `.WithQueryParsingOptions(...)` call, then global `QueryParameters.Parsing`, then defaults. Omitted or `null` array properties inherit; `[]` accepts no formats in that category. `SupportedArrayFormats` and `SupportedObjectFormats` affect full-query binding only. `JsonValues` affects full-query binding when explicitly named and always controls generated direct complex `[FromQuery]` parsers. For example, direct complex `[FromQuery]` parameters can disable their generated JSON parser with the same attribute: ```csharp [ValiantEndpoint] [ValiantQueryParsing(JsonValues = JsonQueryValues.Disabled)] public sealed class SearchEndpoint : IEndpoint { public static IEndpointConventionBuilder Map(IEndpointRouteBuilder builder) => builder.MapGet("/search", static ([FromQuery] SearchRequest request) => Results.Ok(request)); } ``` When the endpoint project is compiled with `options.QueryParameters.EnableBinding = false`, the whole attribute is ignored and no Valiant query parser is generated. A later runtime-only override cannot change an already-generated direct parser. When binding is enabled, no attribute and `[ValiantQueryParsing]` both leave JSON enabled for the generated direct parser. Explicit `Disabled` returns HTTP 400 without a Valiant direct-query filter. Array and object format properties do not affect direct parameters. User-authored `TryParse` methods remain user-controlled, and conflicting policies for the same generated parser type report `VLE011`. ```http ?filter=%7B%22brand%22%3A%22tesla%22%2C%22year%22%3A2025%7D ``` ## Direct parsing ```csharp var result = QueryStringParser.Parse( "?ids=1,2,3&filter.brand=tesla", new QueryParsingOptions { SupportedArrayFormats = [ QueryArrayFormat.RepeatedKeys, QueryArrayFormat.CommaSeparated ], SupportedObjectFormats = [ QueryObjectFormat.Flat, QueryObjectFormat.DotNotation ] }); if (!result.IsSuccess) { foreach (var error in result.Errors) { Console.WriteLine($"{error.Path} [{error.Code}] {error.Message}"); } } ``` Primitive arrays and `List` support `string`, `int`, `long`, `Guid`, `bool`, `decimal`, and `DateTime`; nullable primitive scalars are supported. Nested object binding supports at least one level. ## Direct serialization ```csharp var result = QueryStringSerializer.Serialize( new { ids = new[] { 1, 2, 3 }, filter = new { brand = "tesla", year = 2025 } }, new QuerySerializationOptions { ArrayFormat = QueryArrayFormat.CommaSeparated, ObjectFormat = QueryObjectFormat.DotNotation }); // ?ids=1,2,3&filter.brand=tesla&filter.year=2025 ``` The serializer URL-encodes keys and values, preserves array order, and skips null values. It never negotiates an output format: one array and one object format are selected explicitly. ## Structured errors `QueryErrorKind.Validation` means the supplied value or target shape is invalid—for example, an invalid `Guid`, empty array element, or unsupported type. `QueryErrorKind.Configuration` means the request used a disabled format or serialization options could not represent the requested shape. ```csharp public sealed class QueryError { public string Path { get; } public string Code { get; } public string Message { get; } public QueryErrorKind Kind { get; } } ``` ## Registration, generation, and diagnostics Source: https://valiant.staticnorth.dev/endpoints/reference/registration-generation # Registration, generation, and diagnostics ## Default discovery `AddValiantEndpoints()` registers generated route registrars from the calling and entry assemblies. `MapValiantEndpoints()` resolves every registered registrar. ## Explicit assemblies Use explicit overloads when endpoints live in feature libraries: ```csharp builder.Services.AddValiantEndpoints( typeof(OrdersEndpoint).Assembly, typeof(BillingEndpoint).Assembly); app.MapValiantEndpoints(); ``` Explicit assembly selection changes registration only. Endpoint mapping always uses the same `MapValiantEndpoints()` entry point, so generated mapping policy and conventions have one consistent execution path. ## Generator scope The incremental generator starts from marker attributes—not an assembly-wide interface scan: - `[ValiantEndpoint]` or `[ValiantEndpoint]` generates endpoint registration; - `[ValiantEndpointGroup]` generates group registration; - partial query request/type declarations receive binders only when query binding is explicitly enabled and they are referenced from generated endpoint methods. The companion analyzer checks only direct `IEndpoint` and `IEndpointGroup` declarations for missing markers. It intentionally avoids indirect and aliased implementation scans to keep IDE analysis bounded. `IEndpointGroup.CreateGroup` is a static abstract interface member. The C# compiler requires every endpoint group type to provide a public static implementation. ## Diagnostics | ID | Meaning | | --- | --- | | `VLE001` | Marked endpoint does not implement `IEndpoint` | | `VLE002` | A declaration implements both endpoint interfaces | | `VLE003` | Endpoint marker was applied to a group | | `VLE004` | Declared group type does not implement `IEndpointGroup` | | `VLE005` | Marked group does not implement `IEndpointGroup` | | `VLE006` | Direct endpoint declaration is missing `[ValiantEndpoint]` | | `VLE007` | Direct group declaration is missing `[ValiantEndpointGroup]` | | `VLE008` | Group marker was applied to an endpoint | | `VLE009` | An endpoint uses more than one endpoint marker form | | `VLE010` | A query type cannot receive the generated binder | `VLE010` covers shapes such as non-partial source types, static types, open generics, or containing types that cannot receive generated members. ## Samples Source: https://valiant.staticnorth.dev/endpoints/samples # Endpoint samples The runnable host has four startup choices. Select one near the top of [`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/Program.cs), then run: ```bash dotnet run --project endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples ``` ```csharp Type? startup; //startup = typeof(Samples.Basic.Startup); //startup = typeof(Samples.Configuration.Startup); //startup = typeof(Samples.ConditionalRegistration.Startup); startup = typeof(Samples.QueryBinding.Startup); ``` Endpoint discovery is assembly-wide. Every attributed endpoint in the sample project contributes generated registration code; the selected startup controls the global options and conventions applied when those registrations are mapped. ## Available startups | Startup | Demonstrates | Source | | --- | --- | --- | | `Basic.Startup` | Default discovery and mapping for a standalone endpoint and an endpoint group | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/Basic) | | `Configuration.Startup` | `ConfigureEndpointGroup`, `ConfigureEndpoint`, and descriptor-based guards using group and endpoint metadata | [`Configuration`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/Configuration) | | `ConditionalRegistration.Startup` | Independent `MapEndpointGroupsWhen` and `MapEndpointWhen` policies, including allowed and rejected registrations | [`ConditionalRegistration`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/ConditionalRegistration) | | `QueryBinding.Startup` | Generated query binding for arrays, objects, JSON values, and supported query formats | [`QueryBinding`](https://github.com/static-north-dev/valiant/tree/main/endpoints/samples/StaticNorth.Valiant.Endpoints.AspNetCore.Samples/QueryBinding) | Every startup registers and maps the generated route plan through `AddValiantEndpoints()` and `MapValiantEndpoints()`. ## Configuration hooks The configuration startup applies one convention to both endpoints in its group and a second convention only to `SelectedEndpoint`: | Route | `X-Valiant-Group` | `X-Valiant-Endpoint` | | --- | --- | --- | | `/configuration/selected` | `ConfigurationEndpointGroup` | `SelectedEndpoint` | | `/configuration/group-only` | `ConfigurationEndpointGroup` | not present | The hook receives the builder returned by the user-authored mapping method and its generated registration descriptor. See [Groups and conventions](https://valiant.staticnorth.dev/endpoints/guides/groups-conventions) for the complete mapping sequence. ## Conditional registration The conditional startup exercises positive and negative cases for both predicates: | Route | Status | Policy demonstrated | | --- | --- | --- | | `/conditional/groups/allowed/hello` | `200` | group allowed | | `/conditional/groups/blocked/hello` | `404` | group rejected | | `/conditional/endpoints/allowed` | `200` | standalone endpoint allowed | | `/conditional/endpoints/blocked` | `404` | standalone endpoint rejected | Rejecting a group skips its child registrations, so `MapEndpointWhen` is not evaluated for those children. These are startup-time registration decisions, not request-time feature checks. See [Conditional registration](https://valiant.staticnorth.dev/endpoints/guides/conditional-registration) for descriptor details and precedence. ## Query binding The query-binding startup opts the compilation into generated binding: ```csharp services.AddValiantEndpoints(options => { options.QueryParameters.EnableBinding = true; }); ``` Its `/query/*` routes cover array and object formats, direct JSON query values, and an endpoint that explicitly disables JSON parsing. See [Request binding](https://valiant.staticnorth.dev/endpoints/guides/request-binding) and the [query parameter reference](https://valiant.staticnorth.dev/endpoints/reference/query-parameters) before choosing a binding shape.