System.IO.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 System.IO.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 System.IO.Stream are System.IO.FileStream, and System.IO.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 System.IO.Stream class.

The Stream.Read(Byte[], int, int) and Stream.Write(Byte[], int, int) methods read and write data in a variety of formats. For streams that support seeking, use the Stream.Seek(long, SeekOrigin) and Stream.SetLength(long) 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 System.IO.Stream class includes async methods to simplify asynchronous operations. An async method contains Async in its name, such as Stream.ReadAsync(Byte[], int, int), Stream.WriteAsync(Byte[], int, int), Stream.CopyToAsync(Stream), and Stream.FlushAsync(System.Threading.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, System.IO.Stream includes two extension methods: WindowsRuntimeStreamExtensions.AsInputStream(Stream) and WindowsRuntimeStreamExtensions.AsOutputStream(Stream). These methods convert a System.IO.Stream object to a stream in the wrt. You can also convert a stream in the wrt to a System.IO.Stream object by using the WindowsRuntimeStreamExtensions.AsStreamForRead(Windows.Storage.Streams.IInputStream) and WindowsRuntimeStreamExtensions.AsStreamForWrite(Windows.Storage.Streams.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 System.IO.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 System.IO.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.

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

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