IHttpContentFormatter Interface

Namespace
Kampute.HttpClient.Interfaces
Assembly
  • Kampute.HttpClient.dll

Definition

Defines a content format that converts between HTTP content and .NET objects.
public interface IHttpContentFormatter
Implemented by

Remarks

A formatter has a reading side and a writing side. The reading side turns response content into objects: GetReadableMediaTypes(Type) lists the media types the formatter can read into a model type, which HttpRestClient uses to build the Accept header, and CanRead(string, Type) and ReadAsync(HttpContent, Type, CancellationToken) select the formatter for a response and read its content. The writing side turns objects into request content: GetWritableMediaTypes(Type) and CanWrite(string, Type) select the formatter for a payload, and Write(object, string) creates the content.

A formatter can support one side only. A receive-only formatter returns no writable media types and never accepts a payload, and a send-only formatter returns no readable media types and never accepts a response.

Media types are case-insensitive, so implementations compare them ignoring case. Implementations are expected to be thread-safe, because a formatter registered with a client is shared by all its requests.

Methods

CanRead(string, Type)

Determines whether this formatter can read content of the specified media type into the specified model type.
bool CanRead(string mediaType, Type modelType)

Parameters

mediaType string
The media type of the content.
modelType Type
The type of the object to read.

Returns

bool
true if this formatter can read the content; otherwise, false.

CanWrite(string, Type)

Determines whether this formatter can write a payload of the specified type in the specified media type.
bool CanWrite(string mediaType, Type payloadType)

Parameters

mediaType string
The media type of the content to create.
payloadType Type
The type of the payload to write.

Returns

bool
true if this formatter can write the payload; otherwise, false.

GetReadableMediaTypes(Type)

Returns the media types that this formatter can read into the specified model type.
IEnumerable<string> GetReadableMediaTypes(Type modelType)

Parameters

modelType Type
The type of the object to read.

Returns

IEnumerable<string>
The media types that this formatter can read into modelType, in order of preference; empty if there are none.

GetWritableMediaTypes(Type)

Returns the media types in which this formatter can write a payload of the specified type.
IEnumerable<string> GetWritableMediaTypes(Type payloadType)

Parameters

payloadType Type
The type of the payload to write.

Returns

IEnumerable<string>
The media types in which this formatter can write payloadType, in order of preference; empty if there are none.

ReadAsync(HttpContent, Type, CancellationToken)

Asynchronously reads an object of the specified type from HTTP content.
Task<object> ReadAsync(HttpContent content, Type modelType, CancellationToken cancellationToken = default)

Parameters

content HttpContent
The HttpContent to read.
modelType Type
The type of the object to read.
cancellationToken CancellationToken optional
A token for canceling the operation (optional).

Returns

Task<object>
A task that resolves to the object read from content.

Exceptions

ArgumentNullException
Thrown if content or modelType is null.

Write(object, string)

Creates HTTP content that carries the specified payload in the specified media type.
HttpContent Write(object payload, string mediaType)

Parameters

payload object
The object to write.
mediaType string
The media type of the content to create.

Returns

HttpContent
The HttpContent that carries payload.

Exceptions

ArgumentNullException
Thrown if payload or mediaType is null.
NotSupportedException
Thrown if this formatter cannot write payload in mediaType.

See Also