Method UploadAsync

UploadAsync<TResult>(InterpolatedApiPathHandler, UploadSource, ReadOnlySpan<(string Name, object? Value)>, object?, UploadOptions?, CancellationToken)

Uploads a file in chunks to an upload endpoint of the service and returns the result of the endpoint's handler.

Declaration

protected Task<TResult> UploadAsync<TResult>(InterpolatedApiPathHandler path, UploadSource source, ReadOnlySpan<(string Name, object? Value)> query = default, object? command = null, UploadOptions? options = null, CancellationToken cancellationToken = default) where TResult : notnull

Parameters

Type	Name	Description
InterpolatedApiPathHandler	path	The path of the upload endpoint, relative to the base address. It cannot have a query string.
UploadSource	source	The file to upload.
ReadOnlySpan<(string Name, object Value)>	query	The query string parameters of the requests that create and complete the upload, which the endpoint's validator and handler bind. Parameters with a null value are left out.
object	command	The app's command, which the request that creates the upload sends to the endpoint, serialized as JSON with SerializerOptions. Default is null, which sends none.
UploadOptions	options	The options of the upload. Default is null, which uses the defaults of UploadOptions.
CancellationToken	cancellationToken	A token to cancel the upload, which aborts it on the service.

Returns

Type	Description
Task<TResult>

Type Parameters

Name	Description
TResult	The type of the handler's result.

Remarks

The upload is created with a POST to {path}/uploads, which runs the endpoint's validator. The creation has a random idempotency key (see IdempotencyKey), the same each time it is made, so a creation made again after its response was lost gets the upload that it created. Its chunks are then sent, and the upload is completed with a POST to {path}/uploads/{id}/complete, which runs the handler and streams its result. Every request is created with CreateRequest(HttpMethod, InterpolatedApiPathHandler, ReadOnlySpan<(string Name, object? Value)>) and sent with SendAsync<TResponse>(HttpRequestMessage, object?, CancellationToken) or SendStreamingAsync<TItem>(HttpRequestMessage, object?, CancellationToken), like any request of the client.

A request that fails for a reason that may not last (see IsTransient(Exception)), with a 408 (Request Timeout) or with a 429 (Too Many Requests) that has a RetryAfter is made again after a wait: the RetryAfter of the failure if it has one, and otherwise 1 second after the first failure, doubling up to 30 seconds, each reduced by up to half at random. Failures are retried until no request of the upload has succeeded for RetryTimeout. A chunk is sent again from the buffer it was read into, without reading the source again.

The handler runs once, and keeps running when the connection drops. When the completion's stream ends early or sends nothing for CompletionIdleTimeout, the completion is made again, which waits for the run in progress or returns its outcome. When the service answers the completion with Incomplete, the chunks that its status lists as missing are read and sent again, and the upload is completed again, up to five times.

When the upload is cancelled, the source fails to read, a progress report throws (see Progress), or a request fails for another reason or for longer than the retry timeout, the upload is aborted with a DELETE request to {path}/uploads/{id}, which has a timeout of 10 seconds, and the exception is thrown: once the abort has ended for a failure, and right away for a cancellation, while the abort goes on. An upload that can't be aborted, such as one whose creation got no response, or whose failure is a 401, 412 or 428, or a 404 with NotFound, is left for the service to remove when it expires.

Exceptions

Type	Condition
ArgumentException	`path` has a query string or a fragment, is not valid or leads outside the base address.
IOException	The source failed to read, such as for a file that changed, or ended before its length.
FormatException	The completion streamed no result or more than one, or a response of the service is not valid for the protocol.
JsonException	The handler's result is null, or a response of the service is not valid JSON for its type, such as a missing or null value where the type does not allow one.
OperationCanceledException	`cancellationToken` was cancelled, also when the upload failed for another reason at the same time, whose exception is then the inner exception.
HttpRequestException	An error occurred while sending the request or reading the response.
BadRequestApiException	A 400 (Bad Request) response was returned.
UnauthorizedApiException	A 401 (Unauthorized) response was returned.
ForbiddenApiException	A 403 (Forbidden) response was returned.
NotFoundApiException	A 404 (Not Found) response was returned.
ConflictApiException	A 409 (Conflict) response was returned.
UserChangedApiException	A 412 (Precondition Failed) response was returned.
ContentTooLargeApiException	A 413 (Content Too Large) response was returned.
UnsupportedMediaTypeApiException	A 415 (Unsupported Media Type) response was returned.
ValidationApiException	A 422 (Unprocessable Content) response was returned.
UserRequiredApiException	A 428 (Precondition Required) response was returned.
TooManyRequestsApiException	A 429 (Too Many Requests) response was returned.
ServerErrorApiException	A 500 (Internal Server Error) response was returned.
ServiceUnavailableApiException	A 503 (Service Unavailable) response was returned.
ApiException	Any other error response or a `3xx` response was returned. Redirects are not followed, except on browser platforms (see Location).
TaskCanceledException	The request did not complete within its timeout (see RequestTimeout and SetRequestTimeout(HttpRequestMessage, TimeSpan)). The inner exception is a TimeoutException.
InvalidOperationException	RequestTimeout is zero, or negative other than InfiniteTimeSpan.

Search Results for