Method MapChunkedUpload
MapChunkedUpload(IEndpointRouteBuilder, string, Delegate, Action<ChunkedUploadEndpointOptions>?)
Maps an upload endpoint that receives a file in chunks and runs a handler with the complete file.
Declaration
[RequiresUnreferencedCode("Chunked uploads build the validator and the handler with RequestDelegateFactory, as MapPost(Delegate) does, which uses reflection on the delegates and their parameters. These types may be trimmed if not directly referenced.")]
[RequiresDynamicCode("Chunked uploads build the validator and the handler with RequestDelegateFactory, as MapPost(Delegate) does, which uses reflection on the delegates and their parameters. These types may be trimmed if not directly referenced.")]
public static RouteGroupBuilder MapChunkedUpload(this IEndpointRouteBuilder endpoints, string pattern, Delegate handler, Action<ChunkedUploadEndpointOptions>? configure = null)Parameters
| Type | Name | Description |
|---|---|---|
| IEndpointRouteBuilder | endpoints | The endpoint route builder. |
| string | pattern | The route pattern of the endpoint. Its uploads are under it, at |
| Delegate | handler | The handler, which runs once all chunks have arrived. It takes an UploadedFile, or an UploadedFile<TCommand> with the app's command, and binds its other parameters as any endpoint does. It returns its result, or an IAsyncEnumerable<T> of items, of a reference type. |
| Action<ChunkedUploadEndpointOptions> | configure | An optional action that configures the options of the endpoint. |
Returns
| Type | Description |
|---|---|
| RouteGroupBuilder | A builder for adding conventions to all the endpoints of the upload, such as rate limits. |
Remarks
The endpoints are POST {pattern}/uploads, which creates an upload, PUT, GET and DELETE on
{pattern}/uploads/{id}, which send a chunk, get the upload's status and abort it, and POST {pattern}/uploads/{id}/complete, which runs
the handler and streams its result or items, with ping records while it runs. Every request needs a session of the user who created the upload,
and the endpoint and route values that it was created with. The validator and the handler bind route values and the query string as any endpoint
does, and take no request body.
The handler runs at most once for an upload, and keeps running when the client disconnects: a repeated completion request attaches to the run, or
gets its outcome once it has ended. Its cancellation token is cancelled when the upload is aborted, when it has run for
IdleExpiry, and when the application stops, which ends the upload with
Interrupted. A handler that fails with a 503, a ServiceUnavailableApiException or an exception
that the app's IApiExceptionHandler maps to one, leaves the upload with all its chunks and its file, so that the client's next completion
request runs it again.
The validator and the handler are built with RequestDelegateFactory, as for MapPost(string, Delegate), which is not supported in
trimmed and Native AOT apps.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The services of chunked uploads are not registered (see AddChunkedUploads<TSessionToken>(IServiceCollection, Action<ChunkedUploadOptions>?)), or the validator or the handler has a signature that is not supported. |
MapChunkedUpload(IEndpointRouteBuilder, string, Delegate, Delegate, Action<ChunkedUploadEndpointOptions>?)
Maps an upload endpoint that receives a file in chunks, with a validator that runs when an upload is created and a handler that runs with the complete file.
Declaration
[RequiresUnreferencedCode("Chunked uploads build the validator and the handler with RequestDelegateFactory, as MapPost(Delegate) does, which uses reflection on the delegates and their parameters. These types may be trimmed if not directly referenced.")]
[RequiresDynamicCode("Chunked uploads build the validator and the handler with RequestDelegateFactory, as MapPost(Delegate) does, which uses reflection on the delegates and their parameters. These types may be trimmed if not directly referenced.")]
public static RouteGroupBuilder MapChunkedUpload(this IEndpointRouteBuilder endpoints, string pattern, Delegate validator, Delegate handler, Action<ChunkedUploadEndpointOptions>? configure = null)Parameters
| Type | Name | Description |
|---|---|---|
| IEndpointRouteBuilder | endpoints | The endpoint route builder. |
| string | pattern | The route pattern of the endpoint. Its uploads are under it, at |
| Delegate | validator | The validator, which runs when an upload is created, before any chunk is sent. It takes an UploadRequest, or an UploadRequest<TCommand> with the app's command, and binds its other parameters as any endpoint does. It returns nothing, and rejects an upload by throwing an ApiException. |
| Delegate | handler | The handler, which runs once all chunks have arrived. It takes an UploadedFile, or an UploadedFile<TCommand> with the app's command, and binds its other parameters as any endpoint does. It returns its result, or an IAsyncEnumerable<T> of items, of a reference type. |
| Action<ChunkedUploadEndpointOptions> | configure | An optional action that configures the options of the endpoint. |
Returns
| Type | Description |
|---|---|
| RouteGroupBuilder | A builder for adding conventions to all the endpoints of the upload, such as rate limits. |
Remarks
The endpoints are POST {pattern}/uploads, which creates an upload, PUT, GET and DELETE on
{pattern}/uploads/{id}, which send a chunk, get the upload's status and abort it, and POST {pattern}/uploads/{id}/complete, which runs
the handler and streams its result or items, with ping records while it runs. Every request needs a session of the user who created the upload,
and the endpoint and route values that it was created with. The validator and the handler bind route values and the query string as any endpoint
does, and take no request body.
The handler runs at most once for an upload, and keeps running when the client disconnects: a repeated completion request attaches to the run, or
gets its outcome once it has ended. Its cancellation token is cancelled when the upload is aborted, when it has run for
IdleExpiry, and when the application stops, which ends the upload with
Interrupted. A handler that fails with a 503, a ServiceUnavailableApiException or an exception
that the app's IApiExceptionHandler maps to one, leaves the upload with all its chunks and its file, so that the client's next completion
request runs it again.
The validator and the handler are built with RequestDelegateFactory, as for MapPost(string, Delegate), which is not supported in
trimmed and Native AOT apps.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The services of chunked uploads are not registered (see AddChunkedUploads<TSessionToken>(IServiceCollection, Action<ChunkedUploadOptions>?)), or the validator or the handler has a signature that is not supported. |