Quickstart: Reading and writing a file (Windows Store apps using C#/VB/C++ and XAML)

Read and write a file using a StorageFile object.

Prerequisites

• Understand async programming for Windows Store apps in C# or Visual Basic

  You can learn how to write asynchronous apps in Quickstart: Using the await operator for asynchronous programming.

• Know how to get the file that you want to read from, write to, or both

  You can learn how to get a file by using a file picker in Quickstart: Accessing files with file pickers.

The file used in the examples

All the code in these examples is taken from the File access sample and depends on the sample's global sampleFile variable. This variable represents the file (sample.txt) that the sample writes to and reads from in the examples.

The File access sample creates the sample.txt file and stores the StorageFile object that is returned, like this:

StorageFolder storageFolder = KnownFolders.DocumentsLibrary;
StorageFile sampleFile = await storageFolder.CreateFileAsync("sample.txt");

Note  Before you can create files in the Documents library, you must declare the necessary capabilities in your app manifest. Learn more about file access and capabilities in File access and permissions and App capability declarations.

Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

Writing to a file

These steps show you how to write to a file if you have a writable file and a StorageFile that represents it.

Writing text to a file

Write text to your file by calling the WriteTextAsync methods of the FileIO class.

The File access sample shows you how to call WriteTextAsync(file, contents) to write some arbitrary text to its sampleFile like this:

C#

VB

Copy

await Windows.Storage.FileIO.WriteTextAsync(sampleFile, "Swift as a shadow");

Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

Writing bytes to a file by using a buffer

1. Get a buffer of the bytes that you want to write to your file.

   For example, the File access sample calls ConvertStringToBinary to get a buffer of bytes based on an arbitrary string, like this:

   C#

   VB

   Copy

   
   var buffer = Windows.Security.Cryptography.CryptographicBuffer.ConvertStringToBinary(
       "What fools these mortals be", Windows.Security.Cryptography.BinaryStringEncoding.Utf8);
   
   
   
   

2. Write the bytes from your buffer to your file by calling the WriteBufferAsync method of the FileIO class.

   The File access sample shows you how to use WriteBufferAsync to write bytes from a buffer to its sampleFile, like this:

   C#

   VB

   Copy

   
   await Windows.Storage.FileIO.WriteBufferAsync(sampleFile, buffer);
   
   
   

   Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

Writing text to a file by using a stream

1. Open a stream over your file by calling the StorageFile.OpenAsync method. It returns a stream of the file's content when the open operation completes.

   The File access sample shows you how to open a stream for a file (sampleFile) by calling the StorageFile.OpenAsync method, like this:

   C#

   VB

   Copy

   
   var stream = await sampleFile.OpenAsync(Windows.Storage.FileAccessMode.ReadWrite);
   
   

   Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

2. Get an output stream by calling the GetOutputStreamAt method from the stream. Put this in a using statement to manage the output stream's lifetime.

   C#

   VB

   Copy

   
   using (var outputStream = stream.GetOutputStreamAt(0))
   {
                   
       // Add code to use the stream to write to your file
    
   }
   
   
   

   Use the following steps to add code within the using statement to write to the output stream.

   1. Write text to the outputStream by creating a new DataWriter object and calling the DataWriter.WriteString method.

      C#

      VB

      Copy

      
          DataWriter dataWriter = new DataWriter(outputStream);
          dataWriter.WriteString("The DataWriter provides method to write to various types, such as DataTimeOffset.");
      
      
      

   2. Save the text to your file and close the stream by calling the writer.StoreAsync and outputStream.FlushAsync methods.

      The File access sample shows you how to save the text to your file and close the stream, like this:

      C#

      VB

      Copy

      
          await dataWriter.StoreAsync();
          await outputStream.FlushAsync(); 
      
      
      

      Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

You can download the File access sample to see these code examples in context inside methods.

Reading from a file

These steps show you how to read from a file if you have a readable file and a StorageFile that represents it. You can get a StorageFile that represents readable files by the StorageFolder.GetFileAsync method.

StorageFolder storageFolder = KnownFolders.DocumentsLibrary;
StorageFile sampleFile = await storageFolder.GetFileAsync("sample.txt");

Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

Reading text from a file

Read text from your file by calling the ReadTextAsync methods of the FileIO class.

The File access sample shows you how to read text from a file by calling ReadTextAsync(file) to read from its sampleFile, like this:

C#

VB

Copy

string text = await Windows.Storage.FileIO.ReadTextAsync(sampleFile);

Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

Reading bytes from a file by using a buffer

Read bytes from your buffer to your file by calling the ReadBufferAsync method of the FileIO class.

The File access sample shows you how to read bytes to a buffer from a file by calling ReadBufferAsync, like this:

C#

VB

Copy

var buffer = await Windows.Storage.FileIO.ReadBufferAsync(sampleFile);

Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

Then use a DataReader object to read the length of the buffer and read the contents of the buffer.

C#

VB

Copy

DataReader dataReader = Windows.Storage.Streams.DataReader.FromBuffer(buffer);
string text = dataReader.ReadString(buffer.Length);

Reading text from a file by using a stream

1. Open a stream for your file by calling the StorageFile.OpenAsync method. It returns a stream of the file's content when the open operation completes.

   The File access sample shows you how to open a stream to a file (sampleFile) by calling the StorageFile.OpenAsync method like this:

   C#

   VB

   Copy

   
   var stream = await sampleFile.OpenAsync(Windows.Storage.FileAccessMode.ReadWrite);
   
   

   Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

2. Get the size of the stream to use later.

   C#

   VB

   Copy

   
   var size = stream.Size;
   
   

3. Get an input stream by calling the GetInputStreamAt method of the stream. Put this in a using statement to manage the input stream's lifetime. Specify 0 when you call GetInputStreamAt to set the position of the inputStream at the beginning of the stream, as shown in the sample.

   C#

   VB

   Copy

   
   using (var inputStream = stream.GetInputStreamAt(0))
   {
       // Add code to use the stream to read your file
       
   }
   
   
   

   Use the following steps to add code within the using statement to read the input stream.

   1. Get a DataReader object by passing the inputStream to the constructor.

      The File access sample shows how to create a DataReader like this:

      C#

      VB

      Copy

      
      DataReader dataReader = new DataReader(inputStream);
      
      

   2. Read the text by calling the DataReader.LoadAsync and DataReader.ReadString methods.

      The File access sample shows you how to read text and make sure the stream isn't empty, like this:

      C#

      VB

      Copy

      
      uint numBytesLoaded = await dataReader.LoadAsync((uint)size);
      string text = dataReader.ReadString(numBytesLoaded);
      
      
      

      Note  Remember to put the async keyword on the method declaration of any method in which you use the await operator. For more information, see Quickstart: Using the await operator for asynchronous programming.

You can download the File access sample to see these code examples in context inside methods.

Summary and next steps

You should now understand how to read and write from a file if you have a StorageFile that represents the file.

To learn about working with image files, see Quickstart: Image and ImageBrush, Quickstart: Imaging, and the XAML image sample.

Related topics

Accessing data and files

Quickstart: Accessing files with file pickers

Guidelines and checklist for file pickers

File access and permissions

File access sample

XAML image sample

Reference

Windows.Storage.StorageFile class

Windows.Storage.Streams.DataReader class

Windows.Storage.Streams.DataWriter class

Build date: 11/29/2012