Class Endpoint<TRequest, TResponse>

use this base class for defining endpoints that use both request and response dtos.

Inheritance

System.Object

BaseEndpoint

Endpoint<TRequest, TResponse>

Endpoint<TRequest>

Endpoint<TRequest, TResponse, TMapper>

EndpointWithMapper<TRequest, TMapper>

EndpointWithMapping<TRequest, TResponse, TEntity>

EndpointWithoutRequest

EndpointWithoutRequest<TResponse>

RefreshTokenService<TRequest, TResponse>

Implements

IEndpoint

IEventBus

IServiceResolverBase

Inherited Members

BaseEndpoint.Definition

BaseEndpoint.HttpContext

BaseEndpoint.ValidationFailures

BaseEndpoint.Configure()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: FastEndpoints

Assembly: FastEndpoints.dll

Syntax

public abstract class Endpoint<TRequest, TResponse> : BaseEndpoint, IEndpoint, IEventBus, IServiceResolverBase

Type Parameters

Name	Description
TRequest	the type of the request dto
TResponse	the type of the response dto

Properties

BaseURL

the base url of the current request

Declaration

public string BaseURL { get; }

Property Value

Type	Description
System.String

Config

gives access to the configuration. if you need to access this property from within the endpoint Configure() method, make sure to pass in the config to .AddFastEndpoints(config: builder.Configuration)

Declaration

public IConfiguration Config { get; }

Property Value

Type	Description
Microsoft.Extensions.Configuration.IConfiguration

Env

gives access to the hosting environment

Declaration

public IWebHostEnvironment Env { get; }

Property Value

Type	Description
Microsoft.AspNetCore.Hosting.IWebHostEnvironment

Files

the files sent with the request. only populated when content-type is 'multipart/form-data'

Declaration

public IFormFileCollection Files { get; }

Property Value

Type	Description
Microsoft.AspNetCore.Http.IFormFileCollection

Form

the form sent with the request. only populated if content-type is 'application/x-www-form-urlencoded' or 'multipart/form-data'

Declaration

public IFormCollection Form { get; }

Property Value

Type	Description
Microsoft.AspNetCore.Http.IFormCollection

HttpMethod

the http method of the current request

Declaration

public Http HttpMethod { get; }

Property Value

Type	Description
Http

Logger

the logger for the current endpoint type

Declaration

public ILogger Logger { get; }

Property Value

Type	Description
Microsoft.Extensions.Logging.ILogger

Response

the response that is sent to the client.

Declaration

public TResponse Response { get; set; }

Property Value

Type	Description
TResponse

ResponseStarted

get or set whether the response has started. you'd only use this if you're writing to the response stream by yourself.

Declaration

public bool ResponseStarted { get; set; }

Property Value

Type	Description
System.Boolean

User

the current user principal

Declaration

public ClaimsPrincipal User { get; }

Property Value

Type	Description
System.Security.Claims.ClaimsPrincipal

ValidationFailed

use this base class for defining endpoints that use both request and response dtos.

Declaration

public bool ValidationFailed { get; }

Property Value

Type	Description
System.Boolean

Methods

AddError(Expression<Func<TRequest, Object>>, String, String, Severity)

use this base class for defining endpoints that use both request and response dtos.

Declaration

public void AddError(Expression<Func<TRequest, object>> property, string errorMessage, string errorCode = null, Severity severity = Severity.Error)

Parameters

Type	Name	Description
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	property
System.String	errorMessage
System.String	errorCode
FluentValidation.Severity	severity

AddError(String, String, Severity)

use this base class for defining endpoints that use both request and response dtos.

Declaration

public void AddError(string message, string errorCode = null, Severity severity = Severity.Error)

Parameters

Type	Name	Description
System.String	message
System.String	errorCode
FluentValidation.Severity	severity

AllowAnonymous(Http[])

allow unauthenticated requests to this endpoint. optionally specify a set of verbs to allow unauthenticated access with. i.e. if the endpoint is listening to POST, PUT & PATCH and you specify AllowAnonymous(Http.POST), then only PUT & PATCH will require authentication.

Declaration

protected void AllowAnonymous(params Http[] verbs)

Parameters

Type	Name	Description
Http[]	verbs

AllowAnonymous(String[])

allow unauthenticated requests to this endpoint for a specified set of http verbs. i.e. if the endpoint is listening to POST, PUT & PATCH and you specify AllowAnonymous(Http.POST), then only PUT & PATCH will require authentication.

Declaration

protected void AllowAnonymous(string[] verbs)

Parameters

Type	Name	Description
System.String[]	verbs

AllowFileUploads(Boolean)

enable file uploads with multipart/form-data content type

Declaration

protected void AllowFileUploads(bool dontAutoBindFormData = false)

Parameters

Type	Name	Description
System.Boolean	dontAutoBindFormData	set 'true' to disable auto binding of form data which enables uploading and reading of large files without buffering to memory/disk. you can access the multipart sections for reading via the FormFileSectionsAsync() method.

AllowFormData()

enable multipart/form-data submissions

Declaration

protected void AllowFormData()

AuthSchemes(String[])

specify which authentication schemes to use for authenticating requests to this endpoint

Declaration

protected void AuthSchemes(params string[] authSchemeNames)

Parameters

Type	Name	Description
System.String[]	authSchemeNames	the authentication scheme names

Claims(String[])

allows access if the claims principal has ANY of the given claim types

Declaration

protected void Claims(params string[] claimTypes)

Parameters

Type	Name	Description
System.String[]	claimTypes	the claim types

ClaimsAll(String[])

allows access if the claims principal has ALL of the given claim types

Declaration

protected void ClaimsAll(params string[] claimTypes)

Parameters

Type	Name	Description
System.String[]	claimTypes	the claim types

CreateScope()

use this base class for defining endpoints that use both request and response dtos.

Declaration

public IServiceScope CreateScope()

Returns

Type	Description
Microsoft.Extensions.DependencyInjection.IServiceScope

CreateTokenWith<TService>(String, Action<UserPrivileges>)

create the access/refresh token pair response with a given refresh-token service.

Declaration

protected Task<TResponse> CreateTokenWith<TService>(string userId, Action<UserPrivileges> userPrivileges)
    where TService : IRefreshTokenService<TResponse>

Parameters

Type	Name	Description
System.String	userId	the id of the user for which the tokens will be generated for
System.Action<UserPrivileges>	userPrivileges	the user priviledges to be embeded in the jwt such as roles/claims/permissions

Returns

Type	Description
System.Threading.Tasks.Task<TResponse>

Type Parameters

Name	Description
TService

Delete(String, Expression<Func<TRequest, Object>>)

specify a DELETE route pattern using a replacement expression.

Declaration

protected void Delete(string routePattern, Expression<Func<TRequest, object>> members)

Parameters

Type	Name	Description
System.String	routePattern	the words prefixed with @ will be replaced by property names of the new expression in the order they are specified. the replacement words do not have to match the request dto property names. /invoice/{@id}/soft-delete
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	members	r => new { r.InvoiceID }

Delete(String[])

specify to listen for DELETE requests on one or more routes.

Declaration

protected void Delete(params string[] routePatterns)

Parameters

Type	Name	Description
System.String[]	routePatterns

Description(Action<RouteHandlerBuilder>, Boolean)

describe openapi metadata for this endpoint. optionaly specify whether or not you want to clear the default Accepts/Produces metadata.

EXAMPLE: b => b.Accepts<Request>("text/plain")

Declaration

protected void Description(Action<RouteHandlerBuilder> builder, bool clearDefaults = false)

Parameters

Type	Name	Description
System.Action<Microsoft.AspNetCore.Builder.RouteHandlerBuilder>	builder	the route handler builder for this endpoint
System.Boolean	clearDefaults	set to true if the defaults should be cleared

DontAutoTag()

if swagger auto tagging based on path segment is enabled, calling this method will prevent a tag from being added to this endpoint.

Declaration

protected void DontAutoTag()

DontCatchExceptions()

use this only if you have your own exception catching middleware. if this method is called in config, an automatic error response will not be sent to the client by the library. all exceptions will be thrown and it would be the responsibility of your exeception catching middleware to handle them.

Declaration

protected void DontCatchExceptions()

DontThrowIfValidationFails()

disable auto validation failure responses (400 bad request with error details) for this endpoint.

HINT: this only applies to request dto validation.

Declaration

protected void DontThrowIfValidationFails()

ExecuteAsync(TRequest, CancellationToken)

the handler method for the endpoint that returns the response dto. this method is called for each request received.

Declaration

public virtual Task<TResponse> ExecuteAsync(TRequest req, CancellationToken ct)

Parameters

Type	Name	Description
TRequest	req	the request dto
System.Threading.CancellationToken	ct	a cancellation token

Returns

Type	Description
System.Threading.Tasks.Task<TResponse>

FormFileSectionsAsync(CancellationToken)

gets a stream of nullable FileMultipartSections from the incoming multipart/form-data without buffering the whole file to memory/disk as done with IFormFile

Declaration

protected async IAsyncEnumerable<FileMultipartSection> FormFileSectionsAsync(CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellation	optional cancellation token

Returns

Type	Description
System.Collections.Generic.IAsyncEnumerable<Microsoft.AspNetCore.WebUtilities.FileMultipartSection>

Get(String, Expression<Func<TRequest, Object>>)

specify a GET route pattern using a replacement expression.

Declaration

protected void Get(string routePattern, Expression<Func<TRequest, object>> members)

Parameters

Type	Name	Description
System.String	routePattern	the words prefixed with @ will be replaced by property names of the new expression in the order they are specified. the replacement words do not have to match the request dto property names. /invoice/{@id}/print/{@pageNum}
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	members	r => new { r.InvoiceID, r.PageNumber }

Get(String[])

specify to listen for GET requests on one or more routes.

Declaration

protected void Get(params string[] routePatterns)

Parameters

Type	Name	Description
System.String[]	routePatterns

Group<TEndpointGroup>()

if this endpoint is part of an endpoint group, specify the type of the Group concrete class where the common configuration for the group is specified.

WARNING: this method can only be called after the endpoint route has been specified.

Declaration

protected sealed override void Group<TEndpointGroup>()
    where TEndpointGroup : Group, new()

Type Parameters

Name	Description
TEndpointGroup	the type of your Group concrete class

Overrides

BaseEndpoint.Group<TEndpointGroup>()

Exceptions

Type	Condition
System.InvalidOperationException	thrown if endpoint route hasn't yet been specified

HandleAsync(TRequest, CancellationToken)

the handler method for the endpoint. this method is called for each request received.

Declaration

public virtual Task HandleAsync(TRequest req, CancellationToken ct)

Parameters

Type	Name	Description
TRequest	req	the request dto
System.Threading.CancellationToken	ct	a cancellation token

Returns

Type	Description
System.Threading.Tasks.Task

Head(String, Expression<Func<TRequest, Object>>)

specify a HEAD route pattern using a replacement expression.

Declaration

protected void Head(string routePattern, Expression<Func<TRequest, object>> members)

Parameters

Type	Name	Description
System.String	routePattern	the words prefixed with @ will be replaced by property names of the new expression in the order they are specified. the replacement words do not have to match the request dto property names. /invoice/{@id}/print/{@pageNum}
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	members	r => new { r.InvoiceID, r.PageNumber }

Head(String[])

specify to listen for HEAD requests on one or more routes.

Declaration

protected void Head(params string[] routePatterns)

Parameters

Type	Name	Description
System.String[]	routePatterns

OnAfterHandle(TRequest, TResponse)

override this method if you'd like to do something after the handler is executed.

Declaration

public virtual void OnAfterHandle(TRequest req, TResponse res)

Parameters

Type	Name	Description
TRequest	req	the request dto
TResponse	res	the response dto that was sent to the client

OnAfterHandleAsync(TRequest, TResponse, CancellationToken)

override this method if you'd like to do something after the handler is executed.

Declaration

public virtual Task OnAfterHandleAsync(TRequest req, TResponse res, CancellationToken ct)

Parameters

Type	Name	Description
TRequest	req	the request dto
TResponse	res	the response dto that was sent to the client
System.Threading.CancellationToken	ct	a cancellation token

Returns

Type	Description
System.Threading.Tasks.Task

OnAfterValidate(TRequest)

override this method if you'd like to do something to the request dto after it gets validated.

Declaration

public virtual void OnAfterValidate(TRequest req)

Parameters

Type	Name	Description
TRequest	req	the request dto

OnAfterValidateAsync(TRequest, CancellationToken)

override this method if you'd like to do something to the request dto after it gets validated.

Declaration

public virtual Task OnAfterValidateAsync(TRequest req, CancellationToken ct)

Parameters

Type	Name	Description
TRequest	req	the request dto
System.Threading.CancellationToken	ct	a cancellation token

Returns

Type	Description
System.Threading.Tasks.Task

OnBeforeHandle(TRequest)

override this method if you'd like to do something to the request dto before the handler is executed.

Declaration

public virtual void OnBeforeHandle(TRequest req)

Parameters

Type	Name	Description
TRequest	req	the request dto

OnBeforeHandleAsync(TRequest, CancellationToken)

override this method if you'd like to do something to the request dto before the handler is executed.

Declaration

public virtual Task OnBeforeHandleAsync(TRequest req, CancellationToken ct)

Parameters

Type	Name	Description
TRequest	req	the request dto
System.Threading.CancellationToken	ct	a cancellation token

Returns

Type	Description
System.Threading.Tasks.Task

OnBeforeValidate(TRequest)

override this method if you'd like to do something to the request dto before it gets validated.

Declaration

public virtual void OnBeforeValidate(TRequest req)

Parameters

Type	Name	Description
TRequest	req	the request dto

OnBeforeValidateAsync(TRequest, CancellationToken)

override this method if you'd like to do something to the request dto before it gets validated.

Declaration

public virtual Task OnBeforeValidateAsync(TRequest req, CancellationToken ct)

Parameters

Type	Name	Description
TRequest	req	the request dto
System.Threading.CancellationToken	ct	a cancellation token

Returns

Type	Description
System.Threading.Tasks.Task

OnValidationFailed()

override this method if you'd like to do something when a validation failure occurs.

Declaration

public virtual void OnValidationFailed()

OnValidationFailedAsync(CancellationToken)

override this method if you'd like to do something when a validation failure occurs.

Declaration

public virtual Task OnValidationFailedAsync(CancellationToken ct)

Parameters

Type	Name	Description
System.Threading.CancellationToken	ct	a cancellation token

Returns

Type	Description
System.Threading.Tasks.Task

Options(Action<RouteHandlerBuilder>)

set endpoint configurations options using an endpoint builder action ///

Declaration

protected void Options(Action<RouteHandlerBuilder> builder)

Parameters

Type	Name	Description
System.Action<Microsoft.AspNetCore.Builder.RouteHandlerBuilder>	builder	the builder for this endpoint

Patch(String, Expression<Func<TRequest, Object>>)

specify a PATCH route pattern using a replacement expression.

Declaration

protected void Patch(string routePattern, Expression<Func<TRequest, object>> members)

Parameters

Type	Name	Description
System.String	routePattern	the words prefixed with @ will be replaced by property names of the new expression in the order they are specified. the replacement words do not have to match the request dto property names. /invoice/{@id}
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	members	r => new { r.InvoiceID }

Patch(String[])

specify to listen for PATCH requests on one or more routes.

Declaration

protected void Patch(params string[] routePatterns)

Parameters

Type	Name	Description
System.String[]	routePatterns

Permissions(String[])

allows access if the claims principal has ANY of the given permissions

Declaration

protected void Permissions(params string[] permissions)

Parameters

Type	Name	Description
System.String[]	permissions	the permissions

PermissionsAll(String[])

allows access if the claims principal has ALL of the given permissions

Declaration

protected void PermissionsAll(params string[] permissions)

Parameters

Type	Name	Description
System.String[]	permissions	the permissions

Policies(String[])

specify one or more authorization policy names you have added to the middleware pipeline during app startup/ service configuration that should be applied to this endpoint.

Declaration

protected void Policies(params string[] policyNames)

Parameters

Type	Name	Description
System.String[]	policyNames	one or more policy names (must have been added to the pipeline on startup)

Policy(Action<AuthorizationPolicyBuilder>)

specify an action for building an authorization requirement which applies only to this endpoint.

Declaration

protected void Policy(Action<AuthorizationPolicyBuilder> policy)

Parameters

Type	Name	Description
System.Action<Microsoft.AspNetCore.Authorization.AuthorizationPolicyBuilder>	policy	the policy builder action

Post(String, Expression<Func<TRequest, Object>>)

specify a POST route pattern using a replacement expression.

Declaration

protected void Post(string routePattern, Expression<Func<TRequest, object>> members)

Parameters

Type	Name	Description
System.String	routePattern	the words prefixed with @ will be replaced by property names of the new expression in the order they are specified. the replacement words do not have to match the request dto property names. /invoice/{@id}/page/{@pageNum}
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	members	r => new { r.InvoiceID, r.PageNumber }

Post(String[])

specify to listen for POST requests on one or more routes.

Declaration

protected void Post(params string[] routePatterns)

Parameters

Type	Name	Description
System.String[]	routePatterns

PostProcessors(IPostProcessor<TRequest, TResponse>[])

configure a collection of post-processors to be executed after the main handler function is done. processors are executed in the order they are defined here.

Declaration

protected void PostProcessors(params IPostProcessor<TRequest, TResponse>[] postProcessors)

Parameters

Type	Name	Description
IPostProcessor<TRequest, TResponse>[]	postProcessors	the post processors to be executed

PreProcessors(IPreProcessor<TRequest>[])

configure a collection of pre-processors to be executed before the main handler function is called. processors are executed in the order they are defined here.

Declaration

protected void PreProcessors(params IPreProcessor<TRequest>[] preProcessors)

Parameters

Type	Name	Description
IPreProcessor<TRequest>[]	preProcessors	the pre processors to be executed

ProcessorState<TState>()

retrieve the common processor state for this endpoint.

Declaration

public TState ProcessorState<TState>()
    where TState : class, new()

Returns

Type	Description
TState

Type Parameters

Name	Description
TState	the type of the processor state

Exceptions

Type	Condition
System.InvalidOperationException	thrown if the requested type of the processor state does not match with what's already stored in the context

PublishAsync<TEvent>(TEvent, Mode, CancellationToken)

use this base class for defining endpoints that use both request and response dtos.

Declaration

public Task PublishAsync<TEvent>(TEvent eventModel, Mode waitMode = Mode.WaitForAll, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
TEvent	eventModel
Mode	waitMode
System.Threading.CancellationToken	cancellation

Returns

Type	Description
System.Threading.Tasks.Task

Type Parameters

Name	Description
TEvent

Put(String, Expression<Func<TRequest, Object>>)

specify a PUT route pattern using a replacement expression.

Declaration

protected void Put(string routePattern, Expression<Func<TRequest, object>> members)

Parameters

Type	Name	Description
System.String	routePattern	the words prefixed with @ will be replaced by property names of the new expression in the order they are specified. the replacement words do not have to match the request dto property names. /invoice/{@id}/page/{@pageNum}
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	members	r => new { r.InvoiceID, r.PageNumber }

Put(String[])

specify to listen for PUT requests on one or more routes.

Declaration

protected void Put(params string[] routePatterns)

Parameters

Type	Name	Description
System.String[]	routePatterns

Query<T>(String, Boolean)

get the value of a given query parameter by specifying the resulting type and query parameter name. NOTE: an automatic validation error is sent to the client when value retrieval is not successful.

Declaration

protected T Query<T>(string paramName, bool isRequired = true)

Parameters

Type	Name	Description
System.String	paramName	query parameter name
System.Boolean	isRequired	set to false for disabling the automatic validation error

Returns

Type	Description
T	the value if retrieval is successful or null if isRequired is set to false

Type Parameters

Name	Description
T	type of the result

RequestBinder(IRequestBinder<TRequest>)

configure custom model binding for this endpoint by supplying an IRequestBinder implementation. by calling this method, you're completely bypassing the built-in model binding and taking things into your own hands for this endpoint.

Declaration

protected void RequestBinder(IRequestBinder<TRequest> binder)

Parameters

Type	Name	Description
IRequestBinder<TRequest>	binder	custom model binder implementation to use for this endpoint

Resolve(Type)

use this base class for defining endpoints that use both request and response dtos.

Declaration

public object Resolve(Type typeOfService)

Parameters

Type	Name	Description
System.Type	typeOfService

Returns

Type	Description
System.Object

Resolve<TService>()

use this base class for defining endpoints that use both request and response dtos.

Declaration

public TService Resolve<TService>()
    where TService : class

Returns

Type	Description
TService

Type Parameters

Name	Description
TService

ResponseCache(Int32, ResponseCacheLocation, Boolean, String, String[])

specify response caching settings for this endpoint

Declaration

protected void ResponseCache(int durationSeconds, ResponseCacheLocation location = ResponseCacheLocation.Any, bool noStore = false, string varyByHeader = null, string[] varyByQueryKeys = null)

Parameters

Type	Name	Description
System.Int32	durationSeconds	the duration in seconds for which the response is cached
Microsoft.AspNetCore.Mvc.ResponseCacheLocation	location	the location where the data from a particular URL must be cached
System.Boolean	noStore	specify whether the data should be stored or not
System.String	varyByHeader	the value for the Vary response header
System.String[]	varyByQueryKeys	the query keys to vary by

ResponseInterceptor(IResponseInterceptor)

configure a response interceptor to be called before the SendAsync response is sent to the browser. this will override any globally configured interceptor. if you return a response to the browser, then the rest of the SendAsync method will be skipped.

Declaration

protected void ResponseInterceptor(IResponseInterceptor responseInterceptor)

Parameters

Type	Name	Description
IResponseInterceptor	responseInterceptor	the response interceptor to be executed

Roles(String[])

allows access if the claims principal has ANY of the given roles

Declaration

protected void Roles(params string[] rolesNames)

Parameters

Type	Name	Description
System.String[]	rolesNames	one or more roles that has access

Route<T>(String, Boolean)

get the value of a given route parameter by specifying the resulting type and param name. NOTE: an automatic validation error is sent to the client when value retrieval is not successful.

Declaration

protected T Route<T>(string paramName, bool isRequired = true)

Parameters

Type	Name	Description
System.String	paramName	route parameter name
System.Boolean	isRequired	set to false for disabling the automatic validation error

Returns

Type	Description
T	the value if retrieval is successful or null if isRequired is set to false

Type Parameters

Name	Description
T	type of the result

RoutePrefixOverride(String)

specify an override route prefix for this endpoint if a global route prefix is enabled. this is ignored if a global route prefix is not configured. global prefix can be ignored by setting string.Empty

Declaration

protected void RoutePrefixOverride(string routePrefix)

Parameters

Type	Name	Description
System.String	routePrefix	route prefix value

Routes(String[])

specify one or more route patterns this endpoint should be listening for

Declaration

protected void Routes(params string[] patterns)

Parameters

Type	Name	Description
System.String[]	patterns

SendAsync(TResponse, Int32, CancellationToken)

send the supplied response dto serialized as json to the client.

Declaration

protected Task SendAsync(TResponse response, int statusCode = 200, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
TResponse	response	the object to serialize to json
System.Int32	statusCode	optional custom http status code
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendBytesAsync(Byte[], String, String, Nullable<DateTimeOffset>, Boolean, CancellationToken)

send a byte array to the client

Declaration

protected Task SendBytesAsync(byte[] bytes, string fileName = null, string contentType = "application/octet-stream", DateTimeOffset? lastModified = null, bool enableRangeProcessing = false, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Byte[]	bytes	the bytes to send
System.String	fileName
System.String	contentType	optional content type to set on the http response
System.Nullable<System.DateTimeOffset>	lastModified	optional last modified date-time-offset for the data stream
System.Boolean	enableRangeProcessing	optional switch for enabling range processing
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendCreatedAtAsync(String, Object, TResponse, Boolean, CancellationToken)

send a 201 created response with a location header containing where the resource can be retrieved from.

WARNING: this method is only supported on single verb/route endpoints. it will not produce a `Location` header if used in a multi verb or multi route endpoint.

Declaration

protected Task SendCreatedAtAsync(string endpointName, object routeValues, TResponse responseBody, bool generateAbsoluteUrl = false, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.String	endpointName	the name of the endpoint to use for link generation (openapi route id)
System.Object	routeValues	a route values object with key/value pairs of route information
TResponse	responseBody	the content to be serialized in the response body
System.Boolean	generateAbsoluteUrl	set to true for generating a absolute url instead of relative url for the location header
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendCreatedAtAsync<TEndpoint>(Object, TResponse, Nullable<Http>, Nullable<Int32>, Boolean, CancellationToken)

send a 201 created response with a location header containing where the resource can be retrieved from.

HINT: if pointing to an endpoint with multiple verbs, make sure to specify the 'verb' argument and if pointing to a multi route endpoint, specify the 'routeNumber' argument.

WARNING: this overload will not add a location header if you've set a custom endpoint name using .WithName() method. use the other overload that accepts a string endpoint name instead.

Declaration

protected Task SendCreatedAtAsync<TEndpoint>(object routeValues, TResponse responseBody, Http? verb = null, int? routeNumber = null, bool generateAbsoluteUrl = false, CancellationToken cancellation = default(CancellationToken))
    where TEndpoint : IEndpoint

Parameters

Type	Name	Description
System.Object	routeValues	a route values object with key/value pairs of route information
TResponse	responseBody	the content to be serialized in the response body
System.Nullable<Http>	verb	only useful when pointing to a multi verb endpoint
System.Nullable<System.Int32>	routeNumber	only useful when pointing to a multi route endpoint
System.Boolean	generateAbsoluteUrl	set to true for generating a absolute url instead of relative url for the location header
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

Type Parameters

Name	Description
TEndpoint	the type of the endpoint where the resource can be retrieved from

SendEmptyJsonObject(CancellationToken)

send an empty json object in the body

Declaration

protected Task SendEmptyJsonObject(CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendErrorsAsync(Int32, CancellationToken)

send a 400 bad request with error details of the current validation failures

Declaration

protected Task SendErrorsAsync(int statusCode = 400, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Int32	statusCode	the status code for the error response
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendEventStreamAsync<T>(String, IAsyncEnumerable<T>, CancellationToken)

start a "server-sent-events" data stream for the client asynchronously without blocking any threads

Declaration

protected Task SendEventStreamAsync<T>(string eventName, IAsyncEnumerable<T> eventStream, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.String	eventName	the name of the event stream
System.Collections.Generic.IAsyncEnumerable<T>	eventStream	an IAsyncEnumerable that is the source of the data
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used.

Returns

Type	Description
System.Threading.Tasks.Task

Type Parameters

Name	Description
T	the type of the objects being sent in the event stream

SendFileAsync(FileInfo, String, Nullable<DateTimeOffset>, Boolean, CancellationToken)

send a file to the client

Declaration

protected Task SendFileAsync(FileInfo fileInfo, string contentType = "application/octet-stream", DateTimeOffset? lastModified = null, bool enableRangeProcessing = false, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.IO.FileInfo	fileInfo
System.String	contentType	optional content type to set on the http response
System.Nullable<System.DateTimeOffset>	lastModified	optional last modified date-time-offset for the data stream
System.Boolean	enableRangeProcessing	optional switch for enabling range processing
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendForbiddenAsync(CancellationToken)

send a 403 unauthorized response

Declaration

protected Task SendForbiddenAsync(CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendHeadersAsync(Action<IHeaderDictionary>, Int32, CancellationToken)

send headers in response to a HEAD request

Declaration

protected Task SendHeadersAsync(Action<IHeaderDictionary> headers, int statusCode = 200, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Action<Microsoft.AspNetCore.Http.IHeaderDictionary>	headers	an action to be performed on the headers dictionary of the response
System.Int32	statusCode	optional custom http status code
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used.

Returns

Type	Description
System.Threading.Tasks.Task

SendInterceptedAsync(Object, Int32, CancellationToken)

sends an object serialized as json to the client. if a response interceptor has been defined, then that will be executed before the normal response is sent.

Declaration

protected async Task SendInterceptedAsync(object response, int statusCode = 200, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Object	response	the object to serialize to json
System.Int32	statusCode	optional custom http status code
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

Exceptions

Type	Condition
System.InvalidOperationException	will throw if an interceptor has not been defined against the endpoint or globally

SendNoContentAsync(CancellationToken)

send a 204 no content response

Declaration

protected Task SendNoContentAsync(CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendNotFoundAsync(CancellationToken)

send a 404 not found response

Declaration

protected Task SendNotFoundAsync(CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendOkAsync(TResponse, CancellationToken)

send an http 200 ok response with the supplied response dto serialized as json to the client.

Declaration

protected Task SendOkAsync(TResponse response, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
TResponse	response	the object to serialize to json
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendOkAsync(CancellationToken)

send an http 200 ok response without any body

Declaration

protected Task SendOkAsync(CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendRedirectAsync(String, Boolean, CancellationToken)

send a 301/302 redirect response

Declaration

protected Task SendRedirectAsync(string location, bool isPermanant = false, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.String	location	the location to redirect to
System.Boolean	isPermanant	set to true for a 302 redirect. 301 is the default.
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendStreamAsync(Stream, String, Nullable<Int64>, String, Nullable<DateTimeOffset>, Boolean, CancellationToken)

send the contents of a stream to the client

Declaration

protected Task SendStreamAsync(Stream stream, string fileName = null, long? fileLengthBytes = null, string contentType = "application/octet-stream", DateTimeOffset? lastModified = null, bool enableRangeProcessing = false, CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.IO.Stream	stream	the stream to read the data from
System.String	fileName	and optional file name to set in the content-disposition header
System.Nullable<System.Int64>	fileLengthBytes	optional total size of the file/stream
System.String	contentType	optional content type to set on the http response
System.Nullable<System.DateTimeOffset>	lastModified	optional last modified date-time-offset for the data stream
System.Boolean	enableRangeProcessing	optional switch for enabling range processing
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendStringAsync(String, Int32, String, CancellationToken)

send the supplied string content to the client.

Declaration

protected Task SendStringAsync(string content, int statusCode = 200, string contentType = "text/plain", CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.String	content	the string to write to the response body
System.Int32	statusCode	optional custom http status code
System.String	contentType	optional content type header value
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SendUnauthorizedAsync(CancellationToken)

send a 401 unauthorized response

Declaration

protected Task SendUnauthorizedAsync(CancellationToken cancellation = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellation	optional cancellation token. if not specified, the HttpContext.RequestAborted token is used

Returns

Type	Description
System.Threading.Tasks.Task

SerializerContext<TContext>(TContext)

specify the json serializer context if code generation for request/response dtos is being used

Declaration

protected void SerializerContext<TContext>(TContext serializerContext)
    where TContext : JsonSerializerContext

Parameters

Type	Name	Description
TContext	serializerContext

Type Parameters

Name	Description
TContext	the type of the json serializer context for this endpoint

Summary(EndpointSummary)

provide a summary/description for this endpoint to be used in swagger/ openapi

Declaration

protected void Summary(EndpointSummary endpointSummary)

Parameters

Type	Name	Description
EndpointSummary	endpointSummary	an endpoint summary instance

Summary(Action<EndpointSummary<TRequest>>)

provide a summary/description for this endpoint to be used in swagger/ openapi

Declaration

protected void Summary(Action<EndpointSummary<TRequest>> endpointSummary)

Parameters

Type	Name	Description
System.Action<EndpointSummary<TRequest>>	endpointSummary	an action that sets values of an endpoint summary object

Summary(Action<EndpointSummary>)

provide a summary/description for this endpoint to be used in swagger/ openapi

Declaration

protected void Summary(Action<EndpointSummary> endpointSummary)

Parameters

Type	Name	Description
System.Action<EndpointSummary>	endpointSummary	an action that sets values of an endpoint summary object

Tags(String[])

specify one or more string tags for this endpoint so they can be used in the exclusion filter during registration.

HINT: these tags have nothing to do with swagger tags!

Declaration

protected void Tags(params string[] endpointTags)

Parameters

Type	Name	Description
System.String[]	endpointTags	the tag values to associate with this endpoint

Throttle(Int32, Double, String)

rate limit requests to this endpoint based on a request http header sent by the client.

Declaration

protected void Throttle(int hitLimit, double durationSeconds, string headerName = null)

Parameters

Type	Name	Description
System.Int32	hitLimit	how many requests are allowed within the given duration
System.Double	durationSeconds	the frequency in seconds where the accrued hit count should be reset
System.String	headerName	the name of the request header used to uniquely identify clients. header name can also be configured globally using app.UseFastEndpoints(c=> c.ThrottleOptions...) not specifying a header name will first look for 'X-Forwarded-For' header and if not present, will use HttpContext.Connection.RemoteIpAddress.

ThrowError(Expression<Func<TRequest, Object>>, String)

use this base class for defining endpoints that use both request and response dtos.

Declaration

public void ThrowError(Expression<Func<TRequest, object>> property, string errorMessage)

Parameters

Type	Name	Description
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>>	property
System.String	errorMessage

ThrowError(String)

use this base class for defining endpoints that use both request and response dtos.

Declaration

public void ThrowError(string message)

Parameters

Type	Name	Description
System.String	message

ThrowIfAnyErrors()

use this base class for defining endpoints that use both request and response dtos.

Declaration

public void ThrowIfAnyErrors()

TryResolve(Type)

use this base class for defining endpoints that use both request and response dtos.

Declaration

public object TryResolve(Type typeOfService)

Parameters

Type	Name	Description
System.Type	typeOfService

Returns

Type	Description
System.Object

TryResolve<TService>()

use this base class for defining endpoints that use both request and response dtos.

Declaration

public TService TryResolve<TService>()
    where TService : class

Returns

Type	Description
TService

Type Parameters

Name	Description
TService

Validator<TValidator>()

specify the validator that should be used for this endpoint.

TIP: you only need to call this method if you have more than one validator for the same request dto in the solution or if you just want to be explicit about what validator is used by the endpoint.

Declaration

protected void Validator<TValidator>()
    where TValidator : IValidator

Type Parameters

Name	Description
TValidator	the type of the validator

Verbs(Http[])

specify one or more http method verbs this endpoint should be accepting requests for

Declaration

protected void Verbs(params Http[] methods)

Parameters

Type	Name	Description
Http[]	methods

Verbs(String[])

specify one or more http method verbs this endpoint should be accepting requests for

Declaration

public sealed override void Verbs(params string[] methods)

Parameters

Type	Name	Description
System.String[]	methods

Overrides

BaseEndpoint.Verbs(String[])

Version(Int32, Nullable<Int32>)

specify the version of the endpoint if versioning is enabled

Declaration

protected void Version(int version, int? deprecateAt = null)

Parameters

Type	Name	Description
System.Int32	version	the version of this endpoint
System.Nullable<System.Int32>	deprecateAt	the version group number starting at which this endpoint should not be included in swagger document

Implements

IEndpoint

IEventBus

IServiceResolverBase