C# uses a more intuitive approach, associating each file with an object of class FileStream. The constructor for FileStream opens the file and manages the underlying handle. The methods of FileStream perform the file I/O.

The stream concept is fundamental to C# I/O. Think of a parade, which "streams" by you, first the clowns, and then the floats, and then a band or two, some horses, a troupe of Customer objects, a BankAccount, and so on. Viewing a file as a stream of bytes (or characters or strings) is much like a parade. You "stream" the data in and out of your program.

The .NET classes used in C# include an abstract Stream base class and several subclasses, for working with files on the disk, over a network, or already sitting as chunks of data in memory. Some stream classes specialize in encrypting and decrypting data, some are provided to help speed up I/O operations that might be slow using one of the other streams, and you're free to extend class Stream with your own subclass if you come up with a great idea for a new stream (although I warn you that extending Stream is arduous). I give you a tour of the stream classes in the later section "Exploring More Streams than Lewis and Clark."

FileStream, the stream class you'll probably use the most, is a basic class. Open a file, close a file, read a block of bytes, and write a block — that's about all you have. But reading and writing files down at the byte level is a lot of work, something I eschew studiously. Fortunately, the .NET class library introduces the notion of "readers" and "writers." Objects of these types greatly simplify file (and other) I/O.

When you create a new reader (of one of several available types), you associate a stream object with it. It's immaterial to the reader whether the stream connects to a file, a block of memory, a network location, or the Mississippi. The reader requests input from the stream, which gets it from — well, wherever. Using writers is quite similar, except that you're sending output to the stream rather than asking for input. The stream sends it to a specified destination. Often that's a file, but not always.

The System.IO namespace contains classes that wrap around FileStream (or other streams) to give you easier access and that warm fuzzy feeling:

One nice thing about reader/writer classes such as StreamReader and StreamWriter is that you can use them with any kind of stream. This makes reading from and writing to a MemoryStream no harder than reading from and writing to the kind of FileStream discussed in earlier sections of this chapter. (I cover MemoryStream later in the chapter.)

See the later section "More Readers and writers" for additional reader/writer pairs.

The following sections provide the FileWrite and FileRead programs, which demonstrate ways to use these classes for text I/O the C# way.

The following FileWrite program reads lines of data from the console and writes them to a file of the user's choosing. This is pseudocode — it isn't meant to compile. I used it only as an example.

// FileWrite -- Write input from the Console into a text file.
using System;
using System.IO;

namespace FileWrite
{
  public class Program
  {
    public static void Main(string[] args)
    {
      // Get a filename from the user -- the while loop lets you
      // keep trying with different filenames until you succeed.
      StreamWriter sw = null;
      string fileName = "";
      while(true)
      {
        try
        {
          // Enter output filename (simply hit Enter to quit).
          Console.Write("Enter filename "
                      + "(Enter blank filename to quit):");
          fileName = Console.ReadLine();
          if (fileName.Length == 0)
          {
            // No filename -- this jumps beyond the while
            // loop to safety. You're done.
            break;
          }

          // I factored out these tasks to simplify the loops a bit.

          // Call a method (below) to set up the StreamWriter.
          sw = PrepareTheStreamWriter(fileName);
          // Read one string at a time, outputting each to the
          // FileStream open for writing.
          ReadAndWriteLines(sw);

          // Done writing, so close the file you just created.
          sw.Close(); // A very important step. Closes the file too.
          sw = null;  // Give it to the garbage collector.
        }
        catch (IOException ioErr)
        {
          // Ooops -- Error occurred during the processing of the
          // file -- tell the user the full name of the file:
          // Tack the name of the default directory to the filename.
          string dir = Directory.GetCurrentDirectory();  // Directory class
          string path = Path.Combine(dir, fileName); // System.IO.Path class
          Console.WriteLine("Error on file {0}", path);

          // Now output the error message in the exception.
          Console.WriteLine(ioErr.Message);
        }
      }

//Wait for user to acknowledge the results.
      Console.WriteLine("Press Enter to terminate...");
      Console.Read();
    }

    // GetWriterForFile -- Create a StreamWriter set up to write
    //    to the specified file.
    private static StreamWriter GetWriterForFile(string fileName)
    {
      StreamWriter sw;
      // Open file for writing in one of these modes:
      //   FileMode.CreateNew to create a file if it
      //      doesn't already exist or throw an
      //      exception if file exists.
      //   FileMode.Append to append to an existing file
      //      or create a new file if it doesn't exist.
      //   FileMode.Create to create a new file or
      //      truncate an existing file.

      //   FileAccess possibilities are:
      //      FileAccess.Read,
      //      FileAccess.Write,
      //      FileAccess.ReadWrite.
      FileStream fs = File.Open(fileName,
                                FileMode.CreateNew,
                                FileAccess.Write);

      // Generate a file stream with UTF8 characters.
      // Second parameter defaults to UTF8, so can be omitted.
      sw = new StreamWriter(fs, System.Text.Encoding.UTF8);
      return sw;
    }

    // WriteFileFromConsole -- Read lines of text from the console
    //    and spit them back out to the file.
    private static void WriteFileFromConsole(StreamWriter sw)
    {
      Console.WriteLine("Enter text; enter blank line to stop");
      while (true)
      {
        // Read next line from Console; quit if line is blank.
        string input = Console.ReadLine();
        if (input.Length == 0)
        {
          break;
        }
        // Write the line just read to output file.
        sw.WriteLine(input);
        // Loop back up to get another line and write it.
      }
    }
  }
}

FileWrite uses the System.IO namespace as well as System. System.IO contains the file I/O classes.

The FileWrite program starts in Main() with a while loop containing a try block. This is common for a file-manipulation program.

The while loop serves two functions:

The FileWrite program reads the name of the file to create from the console. The program terminates by breaking out of the while loop if the user enters an empty filename. The key to the program occurs in the call to a GetWriterForFile() method; you can find the method below Main(). The key lines in GetWriterForFile() are

FileStream fs = File.Open(fileName, FileMode.CreateNew, FileAccess.Write);
// ...
sw = new StreamWriter(fs, System.Text.Encoding.UTF8);

In the first line, the program creates a FileStream object that represents the output file on the disk. The FileStream constructor used here takes three arguments:

In the second noncomment line of the GetWriterForFile() method, the program "wraps" the newly opened FileStream object in a StreamWriter object, sw. The StreamWriter class wraps around the FileStream object to provide a set of text-friendly methods. This StreamWriter is what the method returns.

The first argument to the StreamWriter constructor is the FileStream object. There's the wrapping. The second argument specifies the encoding to use. The default encoding is UTF8.

After setting up its StreamWriter, the FileWrite program begins reading lines of string input from the console (this code is in the WriteFileFromConsole() method, called from Main()). The program quits reading when the user enters a blank line; until then, it gobbles up whatever it's given and spits it into the StreamWriter sw using that class's WriteLine() method.

Finally, the stream is closed with the sw.Close() expression. This is important to do, because it also closes the file. (I have more to say about closing things in the next section.)

class Wrapper
{
  private Wrapped _wrapped;
  public Wrapper(Wrapped w)
  {
    _w = w; // Now Wrapper has a
         reference to Wrapped.
  }
}

void WrapperMethod()
{
  _wrapped.DoSomething();
}

The catch block is like a soccer goalie: It's there to catch any file error that may have occurred in the program. The catch outputs an error message, including the name of the errant file. But it doesn't output just a simple filename — it outputs the entire filename, including the path, for your reading pleasure. It does this by using the Path.Combine() method to tack the current directory name, obtained through the Directory class, onto the front of the filename you entered. (Path is a class designed to manipulate path information. Directory provides properties and methods for working with directories.) Book I gives you the goods on exceptions, including the exceptions to exceptions, the exceptions to those — I give up.

Upon encountering the end of the while loop, either by completing the try block or by being vectored through the catch, the program returns to the top of the while loop to allow the user to write to another file.

A few sample runs of the program appear as follows. My input is boldfaced:

Enter filename (Enter blank filename to quit):TestFile1.txt
Enter text; enter blank line to stop
This is some stuff
So is this
As is this

Enter filename (Enter blank filename to quit):TestFile1.txt
Error on file C:C#ProgramsFileWriteinDebugTestFile1.txt
The file 'C:C#ProgramsFileWriteinDebugTestFile1.txt' already exists.

Enter filename (Enter blank filename to quit):TestFile2.txt
Enter text; enter blank line to stop
I messed up back there. I should have called it
TestFile2.

Enter filename (Enter blank filename to quit):
Press Enter to terminate...

Everything goes smoothly when I enter some random text into TestFile1.txt. When I try to open TestFile1.txt again, however, the program spits out a message, the gist of which is The file already exists, with the filename attached. The path to the file is tortured because the "current directory" is the directory in which Visual Studio put the executable file. Correcting my mistake, I enter an acceptable filename — such as TestFile2.txt — without complaint.

Now that you've seen FileStream and StreamWriter in action, I should point out the more usual way to do stream writing in C# — inside a using statement:

using(<someresource>)
{
  // Use the resource.
}

The using statement is a construct that automates the process of cleaning up after using a stream. On encountering the closing curly brace of the using block, C# manages "flushing" the stream and closing it for you. (To flush a stream is to push any last bytes left over in the stream's buffer out to the associated file before it gets closed. Think of pushing a handle to drain the last water out of your . . . trout stream.) Using using eliminates the common error of forgetting to flush and close a file after writing to it. Don't leave open files lying around.

Without using, you'd need to write:

Stream fileStream = null;
TextWriter writer = null;
try
{
  // Create and use the stream, then ...
}
finally
{
  stream.Flush();
  stream.Close();
  stream = null;
}

Note how I declared the stream and writer above the try block (so they're visible throughout the method). I also declared the fileStream and writer variables using abstract base classes rather than the concrete types FileStream and StreamWriter. That's a good practice. I set them to null so the compiler won't complain about uninitialized variables.

The preferred way to write the key I/O code in the FileWrite example looks more like this:

// Prepare the file stream.
FileStream fs = File.Open(fileName,
                           FileMode.CreateNew,
                           FileAccess.Write);
// Pass the fs variable to the StreamWriter constructor in the using statement.
using (StreamWriter sw = new StreamWriter(fs))
{
// sw exists only within the using block, which is a local scope.

  // Read one string at a time from the console, outputting each to the
  // FileStream open for writing.
  Console.WriteLine("Enter text; enter blank line to stop");
  while (true)
  {
    // Read next line from Console; quit if line is blank.
    string input = Console.ReadLine();
    if (input.Length == 0)
    {
      break;
    }
    // Write the line just read to output file via the stream.
    sw.WriteLine(input);
    // Loop back up to get another line and write it.
  }
}  // sw goes away here, and fs is now closed. So ...
fs = null;  // Make sure you can't try to access fs again.

The items in parentheses after the using keyword are its "resource acquisition" section, where you allocate one or more resources such as streams, readers/writers, fonts, and so on. (If you allocate more than one resource, they have to be of the same type.) Following that section is the enclosing block, bounded by the outer curly braces.

At the top of the preceding example, in the resource-acquisition section, you set up a resource — in this case, create a new StreamWriter wrapped around the already-existing FileStream. Inside the block is where you carry out all your I/O code for the file.

At the end of the using block, C# automatically flushes the StreamWriter, closes it, and closes the FileStream, also flushing any bytes it still contains to the file on disk. Ending the using block also disposes the StreamWriter object — see the warning and the technical discussion coming up.

try
{
  // Allocate the resource and use it here.
}
finally
{
  // Close and dispose of the resource here.
}

using(StreamWriter sw = new StreamWriter(new FileStream(...)) ...

Flushing and closing the writer has flushed and closed the stream as well. If you try to carry out operations on the stream, you get an exception telling you that you can't access a closed object. Notice that in the FileWrite code earlier in this section I nulled the FileStream object, fs, after the using block to ensure that I won't try to use fs again. After that, the FileStream object is handed off to the garbage collector.

Of course, the file you wrote to disk exists. Create and open a new file stream to the file if you need to work with it again.

I don't go into IDisposable in this book, but you should plan to become more familiar with it as your C# powers grow. Implementing it correctly has to do with the kind of indeterminate garbage disposal that I mention briefly in Book II and can be complex. So using is for use with classes and structs that implement IDisposable, something that you can check in Help. It won't help you with just any old kind of object. Note: The intrinsic C# types — int, double, char, and such — do not implement IDisposable. Class TextWriter, the base class for StreamWriter, does implement the interface. In Help, that looks like this:

public abstract class TextWriter : MarshalByRefObject, IDisposable

When in doubt, check Help to see if the classes or structs you plan to use implement IDisposable.