C# in a Nutshell, Second Edition

Name

Stream

Synopsis

This class is the basic building block of I/O in the .NET Framework. Many types of application use a Stream in one way or another. When calling System.Console.WriteLine( ), you use a TextWriter, which contains a StreamWriter. When you design an ASP.NET application, the System.Web.UI.Page uses a System.Net.Sockets.NetworkStream. In fact, whenever you access a remote database server you are using a NetworkStream.

To determine whether a given Stream can read, write, or seek, check CanRead, CanWrite, or CanSeek, respectively. If your stream can seek, you may seek forward or backward using Seek( ). Length reveals the length of the stream, which can also be set by calling SetLength( ), and Position allows you to check your current position in the stream.

To perform asynchronous I/O, call BeginRead( ) or BeginWrite( ). Notification of an asynchronous operation comes in two ways: either via an System.AsyncCallback delegate callback passed in as part of the BeginRead( )/BeginWrite( ) call, or else by calling the EndRead( ) or EndWrite( ) method explicitly, which blocks the calling thread until the async operation completes.

Streams usually hold on to a precious resource (a network connection or a file handle), which should be freed as soon as it is not needed any more. Because destruction is completely nondeterministic with garbage collection, be sure to call Close( ) at the end of the Stream’s useful lifetime. (Alternatively, wrap the use of the Stream in a using block ...