HttpContentFormatter Class

Namespace
Kampute.HttpClient.Content.Abstracts
Assembly
  • Kampute.HttpClient.dll

Definition

Provides a base class for content formatters that read and write a fixed set of media types.
public abstract class HttpContentFormatter : IHttpContentFormatter
Inheritance
Implements
Inherited by

Remarks

A derived class passes the media types it reads and the media types it writes to the constructor. A receive-only formatter passes no writable media types and overrides ReadContentAsync(HttpContent, Type, CancellationToken); a send-only formatter passes no readable media types and overrides CreateContent(object, string); a two-way formatter does both. To limit the types a formatter handles, override CanReadType(Type) or CanWriteType(Type). To read media types that are not listed, such as every media type with a structured syntax suffix, override CanReadMediaType(string).

Media types are compared ignoring case. ReadAsync(HttpContent, Type, CancellationToken) and Write(object, string) validate their arguments before they call the overridable members.

Constructors

HttpContentFormatter(IEnumerable<string>, IEnumerable<string>)

Initializes a new instance of the HttpContentFormatter class with the media types it reads and writes.
protected HttpContentFormatter(IEnumerable<string> readableMediaTypes, IEnumerable<string> writableMediaTypes)

Parameters

readableMediaTypes IEnumerable<string>
The media types this formatter reads, in order of preference; empty for a send-only formatter.
writableMediaTypes IEnumerable<string>
The media types this formatter writes, in order of preference; empty for a receive-only formatter.

Exceptions

ArgumentNullException
Thrown if readableMediaTypes or writableMediaTypes is null.

Properties

ReadableMediaTypes

Gets the media types this formatter reads.
public IReadOnlyCollection<string> ReadableMediaTypes { get; }

Property Value

IReadOnlyCollection<string>
The media types this formatter reads, in order of preference.

WritableMediaTypes

Gets the media types this formatter writes.
public IReadOnlyCollection<string> WritableMediaTypes { get; }

Property Value

IReadOnlyCollection<string>
The media types this formatter writes, in order of preference.

Methods

CanRead(string, Type)

Determines whether this formatter can read content of the specified media type into the specified model type.
public virtual 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 CanReadMediaType(string) accepts mediaType and CanReadType(Type) accepts modelType; otherwise, false.

CanReadMediaType(string)

Determines whether this formatter can read content of the specified media type.
protected virtual bool CanReadMediaType(string mediaType)

Parameters

mediaType string
The media type of the content, without parameters.

Returns

bool
true if mediaType is one of the ReadableMediaTypes, ignoring case; otherwise, false.

Remarks

CanRead(string, Type) calls this method with a non-null media type. A media type accepted only by an override is read but not advertised in the Accept header, which lists ReadableMediaTypes.

CanReadType(Type)

Determines whether this formatter can read objects of the specified type.
protected virtual bool CanReadType(Type modelType)

Parameters

modelType Type
The type of the object to read.

Returns

bool
true if this formatter can read objects of modelType; otherwise, false. The default is true.

CanWrite(string, Type)

Determines whether this formatter can write a payload of the specified type in the specified media type.
public virtual 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 mediaType is one of the WritableMediaTypes and CanWriteType(Type) accepts payloadType; otherwise, false.

CanWriteType(Type)

Determines whether this formatter can write payloads of the specified type.
protected virtual bool CanWriteType(Type payloadType)

Parameters

payloadType Type
The type of the payload to write.

Returns

bool
true if this formatter can write payloads of payloadType; otherwise, false. The default is true.

CreateContent(object, string)

When overridden in a derived class, creates HTTP content that carries the specified payload in the specified media type.
protected virtual HttpContent CreateContent(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

NotSupportedException
Thrown by the base implementation, for a formatter that does not write content.

Remarks

Write(object, string) calls this method after it has validated its arguments and checked them with CanWrite(string, Type).

GetReadableMediaTypes(Type)

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

Parameters

modelType Type
The type of the object to read.

Returns

IEnumerable<string>
ReadableMediaTypes if CanReadType(Type) accepts modelType; otherwise, an empty collection.

GetWritableMediaTypes(Type)

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

Parameters

payloadType Type
The type of the payload to write.

Returns

IEnumerable<string>
WritableMediaTypes if CanWriteType(Type) accepts payloadType; otherwise, an empty collection.

HasStructuredSyntaxSuffix(string, string)

Determines whether a media type ends with the specified structured syntax suffix.
protected static bool HasStructuredSyntaxSuffix(string mediaType, string suffix)

Parameters

mediaType string
The media type to check, such as application/vnd.example+json.
suffix string
The suffix, including its plus sign, such as +json.

Returns

bool
true if mediaType has a subtype name before suffix and ends with it, ignoring case; otherwise, false.

Exceptions

ArgumentNullException
Thrown if mediaType or suffix is null.

ReadAsync(HttpContent, Type, CancellationToken)

Asynchronously reads an object of the specified type from HTTP content.
public 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.

ReadContentAsync(HttpContent, Type, CancellationToken)

When overridden in a derived class, asynchronously reads an object of the specified type from HTTP content.
protected virtual Task<object> ReadContentAsync(HttpContent content, Type modelType, CancellationToken cancellationToken)

Parameters

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

Returns

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

Exceptions

NotSupportedException
Thrown by the base implementation, for a formatter that does not read content.

Remarks

ReadAsync(HttpContent, Type, CancellationToken) calls this method after it has validated its arguments.

Write(object, string)

Creates HTTP content that carries the specified payload in the specified media type.
public 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 CanWrite(string, Type) returns false for mediaType and the type of payload.