Class Endpoint<TRequest, TResponse>
use this base class for defining endpoints that use both request and response dtos.
Inheritance
Inherited Members
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
|
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>> | members |
|
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
|
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>> | members |
|
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
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
|
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>> | members |
|
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
|
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>> | members |
|
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
|
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>> | members |
|
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
|
System.Linq.Expressions.Expression<System.Func<TRequest, System.Object>> | members |
|
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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
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 |