MhtmlWriter Class

Definition

Namespace: DataStandardizer.File.InternetMessage

Represents a writer of MHTML files (.mht, .mhtml), or any other aggregate documents (RFC 2557), from MhtmlDocument objects.

.NET Standard 1.1:

public sealed class MhtmlWriter : IDisposable

.NET and .NET Standard 2.0 and later:

public sealed class MhtmlWriter : IDisposable, IAsyncDisposable

Remarks

This writes the message of a document as an ImfWriter does, under the same options, so anything that hasn’t changed is written byte for byte, and with the same checks.

Structure. The message as it now is, not as it was when the document was made, is checked as MhtmlDocument describes, under the options of the writer and with no base URI, and a message that it refuses leaves nothing in the output.

Only one operation may be in progress at a time. After a write fails once output has started, a document is incomplete, so the writer cannot continue, and the same goes after any write is canceled.

Constructors

Constructor Notes
MhtmlWriter(Stream messageStream) Creates a writer of documents to a stream. Throws ArgumentNullException: messageStream is null. Throws ArgumentException: messageStream does not support writing.
MhtmlWriter(Stream messageStream, ImfOptions options) Creates a writer of documents to a stream. Throws ArgumentNullException: messageStream or options is null. Throws ArgumentException: messageStream does not support writing. -or- options has no ImfOptions.CharsetResolver, or an ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved.
MhtmlWriter(string messageFilePath) (netstandard2.0+/.NET) Creates a writer of documents to a file. An existing file is overwritten. messageFilePath: The path of the file. The file is opened for asynchronous writing, and is closed when the writer is disposed. Throws ArgumentNullException: messageFilePath is null.
MhtmlWriter(string messageFilePath, ImfOptions options) (netstandard2.0+/.NET) Creates a writer of documents to a file. An existing file is overwritten. messageFilePath: The path of the file. The file is opened for asynchronous writing, and is closed when the writer is disposed. Throws ArgumentNullException: messageFilePath or options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or an ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved.

Properties

Property Signature Notes
BytePosition long BytePosition { get; } Gets the number of bytes written so far. Throws ObjectDisposedException: The writer has been disposed.
Diagnostics IReadOnlyList<ImfDiagnostic> Diagnostics { get; } Gets the problems found so far that did not stop writing. The list is read-only, and grows as the writer finds more. Throws ObjectDisposedException: The writer has been disposed.

Methods

Synchronous

Method Returns Notes
Dispose() void Closes the file the writer opened itself. A caller-supplied stream is left open. May be called more than once. If an operation is in progress, it completes with ObjectDisposedException, and the file is closed once it has finished with it.
Flush() void Flushes the stream, whether the writer opened it or it was supplied by the caller. Throws ObjectDisposedException: The writer has been disposed. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteDocument(MhtmlDocument document, IProgress<ImfWriteProgress>? progress = null) void Writes a whole document. progress: Receives the progress after each field and each block of the body has been handed to the stream, as ImfWriter.WriteMessage describes; or null. Throws ObjectDisposedException: The writer has been disposed, either before this call or during it. Throws ArgumentNullException: document is null. Throws ImfFileException: The document can’t be written. Nothing has been written. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue.

Asynchronous (netstandard2.0+/.NET)

Method Returns Notes
DisposeAsync() ValueTask Closes the file the writer opened itself, asynchronously. A caller-supplied stream is left open. May be called more than once, and shares its state with Dispose. If an operation is in progress, it completes with ObjectDisposedException, and the file is closed once it has finished with it. Returns: A task that completes once any operation in progress has finished, and the file has been closed.
FlushAsync(CancellationToken cancellationToken = default) Task Flushes the stream asynchronously, whether the writer opened it or it was supplied by the caller. Returns: A task that completes once the stream has been flushed. cancellationToken: The token to monitor for cancellation requests. If the flush is canceled, the writer cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the flush is in progress. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. Throws OperationCanceledException: By the task: cancellationToken was canceled.
WriteDocumentAsync(MhtmlDocument document, IProgress<ImfWriteProgress>? progress = null, CancellationToken cancellationToken = default) Task Writes a whole document asynchronously. Returns: A task that completes once the whole document has been handed to the stream. progress: Receives the progress after each field and each block of the body has been handed to the stream, as ImfWriter.WriteMessageAsync describes; or null. cancellationToken: The token to monitor for cancellation requests. If the write is canceled, the writer cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. Throws ArgumentNullException: document is null. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. Throws ImfFileException: By the task: the document can’t be written. Nothing has been written. Throws OperationCanceledException: By the task: cancellationToken was canceled.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. The string file-path constructors, the asynchronous methods, and IAsyncDisposable are available on netstandard2.0, netstandard2.1, and net10.0 only; on netstandard1.1, construct it from a Stream and work synchronously. The nullable reference annotations apply to the netstandard2.1 and net10.0 builds.

See also


This site uses Just the Docs, a documentation theme for Jekyll.