Create, write, and read a file

Important APIs

• StorageFolder class
• StorageFile class
• FileIO class

Read and write a file using a StorageFile object.

Note

 For a complete sample, see the File access sample.

Prerequisites

• Understand async programming for Universal Windows Platform (UWP) apps

  You can learn how to write asynchronous apps in C# or Visual Basic, see Call asynchronous APIs in C# or Visual Basic. To learn how to write asynchronous apps in C++/WinRT, see Concurrency and asynchronous operations with C++/WinRT. To learn how to write asynchronous apps in C++/CX, see Asynchronous programming in C++/CX.

• 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 Open files and folders with a picker.

Creating a file

Here's how to create a file in the app's local folder. If it already exists, we replace it.

// Create sample file; replace if exists.
Windows.Storage.StorageFolder storageFolder =
    Windows.Storage.ApplicationData.Current.LocalFolder;
Windows.Storage.StorageFile sampleFile =
    await storageFolder.CreateFileAsync("sample.txt",
        Windows.Storage.CreationCollisionOption.ReplaceExisting);

Writing to a file

Here's how to write to a writable file on disk using the StorageFile class. The common first step for each of the ways of writing to a file (unless you're writing to the file immediately after creating it) is to get the file with StorageFolder.GetFileAsync.

Windows.Storage.StorageFolder storageFolder =
    Windows.Storage.ApplicationData.Current.LocalFolder;
Windows.Storage.StorageFile sampleFile =
    await storageFolder.GetFileAsync("sample.txt");

Writing text to a file

Write text to your file by calling the FileIO.WriteTextAsync method.

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

Writing bytes to a file by using a buffer (2 steps)

1. First, call CryptographicBuffer.ConvertStringToBinary to get a buffer of the bytes (based on a string) that you want to write to your file.

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

2. Then write the bytes from your buffer to your file by calling the FileIO.WriteBufferAsync method.

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

Writing text to a file by using a stream (4 steps)

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

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

2. Next, get an output stream by calling the IRandomAccessStream.GetOutputStreamAt method from the stream. If you're using C#, then enclose this in a using statement to manage the output stream's lifetime. If you're using C++/WinRT, then you can control its lifetime by enclosing it in a block, or setting it to nullptr when you're done with it.

   using (var outputStream = stream.GetOutputStreamAt(0))
   {
       // We'll add more code here in the next step.
   }
   stream.Dispose(); // Or use the stream variable (see previous code snippet) with a using statement as well.
   

3. Now add this code (if you're using C#, within the existing using statement) to write to the output stream by creating a new DataWriter object and calling the DataWriter.WriteString method.

   using (var dataWriter = new Windows.Storage.Streams.DataWriter(outputStream))
   {
       dataWriter.WriteString("DataWriter has methods to write to various types, such as DataTimeOffset.");
   }
   

4. Lastly, add this code (if you're using C#, within the inner using statement) to save the text to your file with DataWriter.StoreAsync and close the stream with IOutputStream.FlushAsync.

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

Best practices for writing to a file

For additional details and best practice guidance, see Best practices for writing to files.

Reading from a file

Here's how to read from a file on disk using the StorageFile class. The common first step for each of the ways of reading from a file is to get the file with StorageFolder.GetFileAsync.

Windows.Storage.StorageFolder storageFolder =
    Windows.Storage.ApplicationData.Current.LocalFolder;
Windows.Storage.StorageFile sampleFile =
    await storageFolder.GetFileAsync("sample.txt");

Reading text from a file

Read text from your file by calling the FileIO.ReadTextAsync method.

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

Reading text from a file by using a buffer (2 steps)

1. First, call the FileIO.ReadBufferAsync method.

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

2. Then use a DataReader object to read first the length of the buffer and then its contents.

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

Reading text from a file by using a stream (4 steps)

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

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

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

   ulong size = stream.Size;
   

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

   using (var inputStream = stream.GetInputStreamAt(0))
   {
       // We'll add more code here in the next step.
   }
   

4. Lastly, add this code within the existing using statement to get a DataReader object on the stream then read the text by calling DataReader.LoadAsync and DataReader.ReadString.

   using (var dataReader = new Windows.Storage.Streams.DataReader(inputStream))
   {
       uint numBytesLoaded = await dataReader.LoadAsync((uint)size);
       string text = dataReader.ReadString(numBytesLoaded);
   }
   

See also

• Best practices for writing to files