Class PipeExtensions
Stream extension methods.
public static class PipeExtensions- Inheritance
-
PipeExtensions
- Inherited Members
Methods
AsPrebufferedStreamAsync(PipeReader, CancellationToken)
Exposes a pipe reader as a Stream after asynchronously reading all content so the returned stream can be read synchronously without needlessly blocking a thread while waiting for more data.
public static Task<Stream> AsPrebufferedStreamAsync(this PipeReader pipeReader, CancellationToken cancellationToken = default)Parameters
pipeReaderPipeReaderThe pipe to read from when ReadAsync(byte[], int, int, CancellationToken) is invoked.
cancellationTokenCancellationTokenA cancellation token.
Returns
Remarks
The reader will be completed when the Stream is disposed.
AsStream(IDuplexPipe)
public static Stream AsStream(this IDuplexPipe pipe)Parameters
pipeIDuplexPipeThe pipe to wrap as a stream.
Returns
- Stream
The wrapping stream.
AsStream(IDuplexPipe, bool)
Exposes a full-duplex pipe as a Stream.
public static Stream AsStream(this IDuplexPipe pipe, bool ownsPipe)Parameters
pipeIDuplexPipeThe pipe to wrap as a stream.
ownsPipebooltrue to complete the underlying reader and writer when the Stream is disposed; false to keep them open.
Returns
- Stream
The wrapping stream.
AsStream(PipeReader)
Exposes a pipe reader as a Stream.
[Obsolete("Use PipeReader.AsStream instead.")]
public static Stream AsStream(this PipeReader pipeReader)Parameters
pipeReaderPipeReaderThe pipe to read from when ReadAsync(byte[], int, int, CancellationToken) is invoked.
Returns
- Stream
The wrapping stream.
Remarks
The reader will be completed when the Stream is disposed.
AsStream(PipeWriter)
Exposes a pipe writer as a Stream.
[Obsolete("Use PipeWriter.AsStream instead.")]
public static Stream AsStream(this PipeWriter pipeWriter)Parameters
pipeWriterPipeWriterThe pipe to write to when WriteAsync(byte[], int, int, CancellationToken) is invoked.
Returns
- Stream
The wrapping stream.
Remarks
The writer will be completed when the Stream is disposed.
OnCompleted(PipeReader, Action<Exception?, object?>, object?)
Wraps a PipeReader in another object that will report when Complete(Exception) is called.
public static PipeReader OnCompleted(this PipeReader reader, Action<Exception?, object?> callback, object? state = null)Parameters
readerPipeReaderThe reader to be wrapped.
callbackAction<Exception, object>The callback to invoke when the Complete(Exception) method is called. If this delegate throws an exception it will propagate to the caller of the Complete(Exception) method.
stateobjectAn optional state object to supply to the
callback.
Returns
- PipeReader
The wrapped PipeReader which should be exposed to have its Complete(Exception) method called.
Remarks
If the PipeReader has already been completed, the provided callback may never be invoked.
OnCompleted(PipeWriter, Action<Exception?, object?>, object?)
Wraps a PipeWriter in another object that will report when Complete(Exception) is called.
public static PipeWriter OnCompleted(this PipeWriter reader, Action<Exception?, object?> callback, object? state = null)Parameters
readerPipeWriterThe writer to be wrapped.
callbackAction<Exception, object>The callback to invoke when the Complete(Exception) method is called. If this delegate throws an exception it will propagate to the caller of the Complete(Exception) method.
stateobjectAn optional state object to supply to the
callback.
Returns
- PipeWriter
The wrapped PipeWriter which should be exposed to have its Complete(Exception) method called.
Remarks
If the PipeWriter has already been completed, the provided callback may never be invoked.
ReadSlice(PipeReader, long)
Creates a PipeReader that can read no more than a given number of bytes from an underlying reader.
public static PipeReader ReadSlice(this PipeReader reader, long length)Parameters
readerPipeReaderThe PipeReader to read from.
lengthlongThe number of bytes to read from the parent
reader.
Returns
- PipeReader
A reader that ends after
lengthbytes are read.
UsePipe(Stream, bool, int, PipeOptions?, CancellationToken)
Enables reading and writing to a Stream using PipeWriter and PipeReader.
[Obsolete("Use the UsePipe overload that doesn't take an allowUnwrap parameter instead.")]
public static IDuplexPipe UsePipe(this Stream stream, bool allowUnwrap, int sizeHint = 0, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
streamStreamThe stream to access using a pipe.
allowUnwrapboolObsolete. This value is ignored.
sizeHintintA hint at the size of messages that are commonly transferred. Use 0 for a commonly reasonable default.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA token that may cancel async processes to read from and write to the
stream.
Returns
- IDuplexPipe
An IDuplexPipe instance.
UsePipe(Stream, int, PipeOptions?, CancellationToken)
Enables reading and writing to a Stream using PipeWriter and PipeReader.
public static IDuplexPipe UsePipe(this Stream stream, int sizeHint = 0, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
streamStreamThe stream to access using a pipe.
sizeHintintA hint at the size of messages that are commonly transferred. Use 0 for a commonly reasonable default.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA token that may cancel async processes to read from and write to the
stream.
Returns
- IDuplexPipe
An IDuplexPipe instance.
UsePipe(WebSocket, int, PipeOptions?, CancellationToken)
Enables reading and writing to a WebSocket using PipeWriter and PipeReader.
public static IDuplexPipe UsePipe(this WebSocket webSocket, int sizeHint = 0, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
webSocketWebSocketThe WebSocket to access using a pipe.
sizeHintintA hint at the size of messages that may be transferred. Use 0 for a commonly reasonable default.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA token that may cancel async processes to read from and write to the
webSocket.
Returns
- IDuplexPipe
An IDuplexPipe instance.
UsePipeReader(Stream, int, PipeOptions?, CancellationToken)
Enables efficiently reading a stream using PipeReader.
public static PipeReader UsePipeReader(this Stream stream, int sizeHint = 0, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
streamStreamThe stream to read from using a pipe.
sizeHintintA hint at the size of messages that are commonly transferred. Use 0 for a commonly reasonable default.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA cancellation token that aborts reading from the
stream.
Returns
Remarks
When the caller invokes Complete(Exception) on the result value, this leads to the associated Complete(Exception) to be automatically called as well.
UsePipeReader(WebSocket, int, PipeOptions?, CancellationToken)
Enables efficiently reading a WebSocket using PipeReader.
public static PipeReader UsePipeReader(this WebSocket webSocket, int sizeHint = 0, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
webSocketWebSocketThe web socket to read from using a pipe.
sizeHintintA hint at the size of messages that are commonly transferred. Use 0 for a commonly reasonable default.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA cancellation token that aborts reading from the
webSocket.
Returns
Remarks
Because a PipeReader has no concept of message boundaries, this API should only be used when they are of no consequence, and a steady stream of bytes is all that the reader requires.
UsePipeWriter(Stream, PipeOptions?, CancellationToken)
Enables writing to a stream using PipeWriter.
public static PipeWriter UsePipeWriter(this Stream stream, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
streamStreamThe stream to write to using a pipe. This stream is not closed automatically.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA cancellation token that aborts writing to the
stream.
Returns
UsePipeWriter(WebSocket, PipeOptions?, CancellationToken)
Enables efficiently writing to a WebSocket using a PipeWriter.
public static PipeWriter UsePipeWriter(this WebSocket webSocket, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
webSocketWebSocketThe web socket to write to using a pipe.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA cancellation token that aborts writing to the
webSocket.
Returns
Remarks
Because a PipeWriter has no concept of message boundaries, this API should only be used when the remote party can process a stream of bytes, ignoring where the message boundaries may happen to land. As implemented by this API, message boundaries may only appear at positions where FlushAsync(CancellationToken) or WriteAsync(ReadOnlyMemory<byte>, CancellationToken) are called, but they are not guaranteed to be inserted for each of these calls.
UseStrictPipeReader(Stream, int)
Creates a PipeReader that reads from the specified Stream exactly as told to do so.
It does not close the stream when completed.
[Obsolete("Use PipeReader.Create instead.")]
public static PipeReader UseStrictPipeReader(this Stream stream, int sizeHint = 4096)Parameters
streamStreamThe stream to read from using a pipe.
sizeHintintA hint at the size of messages that are commonly transferred. Use 0 for a commonly reasonable default.
Returns
Remarks
This reader may not be as efficient as the Pipe-based PipeReader returned from UsePipeReader(Stream, int, PipeOptions?, CancellationToken), but its interaction with the underlying Stream is closer to how a Stream would typically be used which can ease migration from streams to pipes.
UseStrictPipeWriter(Stream)
Creates a PipeWriter that writes to an underlying Stream when FlushAsync(CancellationToken) is called rather than asynchronously sometime later.
[Obsolete("Use PipeWriter.Create instead.")]
public static PipeWriter UseStrictPipeWriter(this Stream stream)Parameters
streamStreamThe stream to write to using a pipe.
Returns
Remarks
This writer may not be as efficient as the Pipe-based PipeWriter returned from UsePipeWriter(Stream, PipeOptions?, CancellationToken), but its interaction with the underlying Stream is closer to how a Stream would typically be used which can ease migration from streams to pipes.
UseUtf8TextPipe(WebSocket, int, PipeOptions?, CancellationToken)
Enables reading and writing to a WebSocket using PipeWriter and PipeReader.
IMPORTANT: it is YOUR responsibility to make sure that the messages you write conform to UTF-8.
public static IDuplexPipe UseUtf8TextPipe(this WebSocket webSocket, int sizeHint = 0, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
webSocketWebSocketThe WebSocket to access using a pipe.
sizeHintintA hint at the size of messages that may be transferred. Use 0 for a commonly reasonable default.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA token that may cancel async processes to read from and write to the
webSocket.
Returns
- IDuplexPipe
An IDuplexPipe instance.
UseUtf8TextPipeWriter(WebSocket, PipeOptions?, CancellationToken)
Enables efficiently writing UTF-8 encoded text to a WebSocket using a PipeWriter.
public static PipeWriter UseUtf8TextPipeWriter(this WebSocket webSocket, PipeOptions? pipeOptions = null, CancellationToken cancellationToken = default)Parameters
webSocketWebSocketThe web socket to write to using a pipe.
pipeOptionsPipeOptionsOptional pipe options to use.
cancellationTokenCancellationTokenA cancellation token that aborts writing to the
webSocket.
Returns
Remarks
Although PipeWriter itself takes bytes, it is the caller's responsibility to only write bytes that represent UTF-8 encoded characters.
Because a PipeWriter has no concept of message boundaries, this API should only be used when the remote party can process a stream of bytes, ignoring where the message boundaries may happen to land. As implemented by this API, message boundaries may only appear at positions where FlushAsync(CancellationToken) or WriteAsync(ReadOnlyMemory<byte>, CancellationToken) are called, but they are not guaranteed to be inserted for each of these calls.
Users should be sure to write whole UTF-8 characters to the PipeWriter. In particular, never call FlushAsync(CancellationToken) after writing only a subset of the bytes for any UTF-8 character.