System.IO.Stream Class

Provides a generic view of a sequence of bytes. This is an abstract class.

See Also: Stream

Syntax

[System.Runtime.InteropServices.ComVisible(true)]
public abstract class Stream : MarshalByRefObject, IDisposable

Remarks

Stream is the abstract base class of all streams. A stream is an abstraction of a sequence of bytes, such as a file, an input/output device, an inter-process communication pipe, or a TCP/IP socket. The Stream class and its derived classes provide a generic view of these different types of input and output, and isolate the programmer from the specific details of the operating system and the underlying devices.

Streams involve three fundamental operations:

  • You can read from streams. Reading is the transfer of data from a stream into a data structure, such as an array of bytes.

  • You can write to streams. Writing is the transfer of data from a data structure into a stream.

  • Streams can support seeking. Seeking refers to querying and modifying the current position within a stream. Seek capability depends on the kind of backing store a stream has. For example, network streams have no unified concept of a current position, and therefore typically do not support seeking.

Some of the more commonly used streams that inherit from Stream are FileStream, and MemoryStream.

Depending on the underlying data source or repository, streams might support only some of these capabilities. You can query a stream for its capabilities by using the Stream.CanRead, Stream.CanWrite, and Stream.CanSeek properties of the Stream class.

The Stream.Read(Byte[],Int32,Int32) and Stream.Write(Byte[],Int32,Int32) methods read and write data in a variety of formats. For streams that support seeking, use the Stream.Seek(Int64,SeekOrigin) and Stream.SetLength(Int64) methods and the Stream.Position and Stream.Length properties to query and modify the current position and length of a stream.

Starting with the net_v45, the Stream class includes async methods to simplify asynchronous operations. An async method contains Async in its name, such as Stream.ReadAsync(Byte[],Int32,Int32), Stream.WriteAsync(Byte[],Int32,Int32), Stream.CopyToAsync(Stream), and Stream.FlushAsync(CancellationToken). These methods enable you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a win8_appname_long app or desktop_appname app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the async and await keywords in Visual Basic and C#.

When used in a win8_appname_long app, Stream includes two extension methods: WindowsRuntimeStreamExtensions.AsInputStream(Stream) and WindowsRuntimeStreamExtensions.AsOutputStream(Stream). These methods convert a Stream object to a stream in the wrt. You can also convert a stream in the wrt to a Stream object by using the WindowsRuntimeStreamExtensions.AsStreamForRead(IInputStream) and WindowsRuntimeStreamExtensions.AsStreamForWrite(IOutputStream) methods. For more information, see How to: Convert Between .NET Framework Streams and Windows Runtime Streams

Some stream implementations perform local buffering of the underlying data to improve performance. For such streams, you can use the Stream.Flush or Stream.FlushAsync method to clear any internal buffers and ensure that all data has been written to the underlying data source or repository.

Disposing a Stream object flushes any buffered data, and essentially calls the Stream.Flush method for you. Stream.Dispose also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The BufferedStream class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance.

If you need a stream with no backing store (also known as a bit bucket), use the Stream.Null field to retrieve an instance of a stream that is designed for this purpose.

Thread Safety

All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.

Requirements

Namespace: System.IO
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0, 4.0.0.0

The members of System.IO.Stream are listed below.

See Also: MarshalByRefObject

Protected Constructors

Initializes a new instance of the Stream class.

Public Fields

static readonly
NullStream.

A Stream with no backing store.

Public Properties

[read-only]
abstract
CanReadBoolean.

When overridden in a derived class, gets a value indicating whether the current stream supports reading.

[read-only]
abstract
CanSeekBoolean.

When overridden in a derived class, gets a value indicating whether the current stream supports seeking.

[read-only]
CanTimeoutBoolean.

Gets a value that determines whether the current stream can time out.

[read-only]
abstract
CanWriteBoolean.

When overridden in a derived class, gets a value indicating whether the current stream supports writing.

[read-only]
abstract
LengthInt64.

When overridden in a derived class, gets the length in bytes of the stream.

abstract
PositionInt64.

When overridden in a derived class, gets or sets the position within the current stream.

ReadTimeoutInt32.

Gets or sets a value, in miliseconds, that determines how long the stream will attempt to read before timing out.

WriteTimeoutInt32.

Gets or sets a value, in miliseconds, that determines how long the stream will attempt to write before timing out.

Public Methods

BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) : IAsyncResult

Begins an asynchronous read operation. (Consider using Stream.ReadAsync(Byte[],Int32,Int32) instead; see the Remarks section.)

BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object) : IAsyncResult

Begins an asynchronous write operation. (Consider using Stream.WriteAsync(Byte[],Int32,Int32) instead; see the Remarks section.)

Close()

Closes the current stream and releases any resources (such as sockets and file handles) associated with the current stream. Instead of calling this method, ensure that the stream is properly disposed.

CopyTo(Stream)

Reads the bytes from the current stream and writes them to another stream.

CopyTo(Stream, Int32)

Reads the bytes from the current stream and writes them to another stream, using a specified buffer size.

CopyToAsync(Stream) : Task

Asynchronously reads the bytes from the current stream and writes them to another stream.

CopyToAsync(Stream, Int32) : Task

Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size.

CopyToAsync(Stream, Int32, CancellationToken) : Task

Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size and cancellation token.

Dispose()

Releases all resources used by the Stream.

EndRead(IAsyncResult) : Int32

Waits for the pending asynchronous read to complete. (Consider using Stream.ReadAsync(Byte[],Int32,Int32) instead; see the Remarks section.)

EndWrite(IAsyncResult)

Ends an asynchronous write operation. (Consider using Stream.WriteAsync(Byte[],Int32,Int32) instead; see the Remarks section.)

abstract
Flush()

When overridden in a derived class, clears all buffers for this stream and causes any buffered data to be written to the underlying device.

FlushAsync() : Task

Asynchronously clears all buffers for this stream and causes any buffered data to be written to the underlying device.

FlushAsync(CancellationToken) : Task

Asynchronously clears all buffers for this stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests.

abstract
Read(Byte[], Int32, Int32) : Int32

When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

ReadAsync(Byte[], Int32, Int32) : System.Threading.Tasks.Task<int>

Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

ReadAsync(Byte[], Int32, Int32, CancellationToken) : System.Threading.Tasks.Task<int>

Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.

ReadByte() : Int32

Reads a byte from the stream and advances the position within the stream by one byte, or returns -1 if at the end of the stream.

abstract
Seek(Int64, SeekOrigin) : Int64

When overridden in a derived class, sets the position within the current stream.

abstract
SetLength(Int64)

When overridden in a derived class, sets the length of the current stream.

static
Synchronized(Stream) : Stream

Creates a thread-safe (synchronized) wrapper around the specified Stream object.

abstract
Write(Byte[], Int32, Int32)

When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.

WriteAsync(Byte[], Int32, Int32) : Task

Asynchronously writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.

WriteAsync(Byte[], Int32, Int32, CancellationToken) : Task

Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.

WriteByte(Byte)

Writes a byte to the current position in the stream and advances the position within the stream by one byte.

Protected Methods

CreateWaitHandle() : WaitHandle

Allocates a WaitHandle object.

Dispose(Boolean)

Releases the unmanaged resources used by the Stream and optionally releases the managed resources.

ObjectInvariant()

Provides support for a Contract.

Explicitly Implemented Interface Members

Stream$IDisposable.DisposeImplemented to support the IDisposable interface. [Note: For more information, see IDisposable.Dispose.]