C# BinaryWriter Tutorial

You want to create a binary file that uses a specific data layout for its bytes, using the C# programming language. To solve this problem, the BinaryWriter type is ideal as it provides a stream-based mechanism for imperatively writing data to a file location on the disk.

Example

First, what Microsoft says about BinaryReader is that it "reads primitive data types as binary values in a specific encoding." Primitive types are value types like int, uint, or char. Here we see an example of using the BinaryWriter class, which will create the binary file for the example.

This C# example program uses the BinaryWriter class. It writes an output file.

Program that uses BinaryWriter [C#]

using System.IO;

class Program
{
    static void Main()
    {
	W();
    }

    static void W()
    {
	// 1.
	// Create 12 integers.
	int[] a = new int[]
	{
	    1,
	    4,
	    6,
	    7,
	    11,
	    55,
	    777,
	    23,
	    266,
	    44,
	    82,
	    93
	};
	// 2. Use using statement and File.Open.
	using (BinaryWriter b = new BinaryWriter(File.Open("file.bin", FileMode.Create)))
	{
	    // 3. Use foreach and write all 12 integers.
	    foreach (int i in a)
	    {
		b.Write(i);
	    }
	}
    }
}

Overview. The syntax here can be daunting at first. File.Open returns a stream that the BinaryWriter writes through to. The .NET Framework does the hard part there.

Using the Write method. Use Write on your BinaryWriter to write a value to the file. The Write method is overloaded, which means it handles the exact type you pass it correctly.

File data

So what does the output file look like visually when you inspect it in an editor such as Visual Studio? Dot Net Perls has the answer: it looks like random bytes. This is because the data is not encoded as a text file but instead a more efficient, machine-level representation of numeric data. Don't worry; the file can still be treated as a series of numbers.

Close

Do you need to call the Close method on the BinaryWriter in programs such as the one above? The using statement will cause the Dispose method to be called. In the Dispose implementation, Close is called. So the answer is no—an explicit Close call is not necessary.

Implementation of Dispose [IL]

.method family hidebysig newslot virtual
	instance void  Dispose(bool disposing) cil managed
{
  // Code size       15 (0xf)
  .maxstack  8
  IL_0000:  ldarg.1
  IL_0001:  brfalse.s  IL_000e
  IL_0003:  ldarg.0
  IL_0004:  ldfld      class System.IO.Stream System.IO.BinaryWriter::OutStream
  IL_0009:  callvirt   instance void System.IO.Stream::Close()
  IL_000e:  ret
} // end of method BinaryWriter::Dispose

Note: Interestingly, if you call BinaryWriter's virtual Close implementation, it just calls Dispose. The Dispose call then calls the Stream's Close implementation.

Summary

The BinaryWriter type in the C# programming language, which is found in the System.IO namespace, provides an efficient and easy way to imperatively construct a binary file. Ideal for certain file formats that your programs must support, the BinaryWriter is used in many projects around the world. As an adjunct to the BinaryWriter, please read about the BinaryReader class.