.NET Framework Documentation

BinaryWriter Class

Writes primitive types in binary format to a stream and supports writing strings in a specific encoding.

Syntax

public class BinaryWriter : IDisposable

Introduction

The BinaryWriter class provides methods for writing various data types (like integers, floating-point numbers, booleans, and strings) in a binary format to an underlying stream. This is useful for creating custom file formats or for inter-process communication where precise control over data representation is required. It ensures that data is written in a platform-independent manner.

Constructors

• BinaryWriter(Stream output)

  Initializes a new instance of the BinaryWriter class using the specified stream and a UTF-8 encoding.

  output: Stream
  The stream to write to.

• BinaryWriter(Stream output, Encoding encoding)

  Initializes a new instance of the BinaryWriter class using the specified stream and character encoding.

  output: Stream
  The stream to write to.

  encoding: Encoding
  The character encoding to use.

• BinaryWriter(Stream output, Encoding encoding, bool leaveOpen)

  Initializes a new instance of the BinaryWriter class using the specified stream, character encoding, and a value that indicates whether to leave the stream open after the BinaryWriter object is disposed.

  output: Stream
  The stream to write to.

  encoding: Encoding
  The character encoding to use.

  leaveOpen: bool
true to leave the stream open after the object is disposed; otherwise, false.

Methods

• Write(bool value)

  Writes a Boolean value to the current stream and advances the stream position.

• Write(byte value)

  Writes a byte to the current stream and advances the stream position.

• Write(char ch)

  Writes a Unicode character to the current stream and advances the stream position.

• Write(char[] chars)

  Writes a character array to the current stream and advances the stream position.

• Write(decimal value)

  Writes a decimal value to the current stream and advances the stream position.

• Write(double value)

  Writes an 8-byte unsigned integer to the current stream and advances the stream position.

• Write(short value)

  Writes a 16-bit signed integer to the current stream and advances the stream position.

• Write(int value)

  Writes a 32-bit signed integer to the current stream and advances the stream position.

• Write(long value)

  Writes a 64-bit signed integer to the current stream and advances the stream position.

• Write(sbyte value)

  Writes an 8-bit signed integer to the current stream and advances the stream position.

• Write(float value)

  Writes a 4-byte floating-point value to the current stream and advances the stream position.

• Write(string value)

  Writes a string to the current stream by converting it to a sequence of bytes using the current encoding. The result is preceded by its length, expressed as a variable-length quantity.

• Write(ushort value)

  Writes a 16-bit unsigned integer to the current stream and advances the stream position.

• Write(uint value)

  Writes a 32-bit unsigned integer to the current stream and advances the stream position.

• Write(ulong value)

  Writes a 64-bit unsigned integer to the current stream and advances the stream position.

• Flush()

  Clears all buffers for the current writer and causes any buffered data to be written to the underlying stream.

• Close()

  Closes the current BinaryWriter and the underlying stream.

Example

using System;
using System.IO;
using System.Text;

public class Example
{
    public static void Main()
    {
        string filePath = "data.bin";
        using (FileStream fs = new FileStream(filePath, FileMode.Create))
        using (BinaryWriter writer = new BinaryWriter(fs, Encoding.UTF8))
        {
            writer.Write(123);                     // int
            writer.Write(45.67);                   // double
            writer.Write(true);                    // bool
            writer.Write("Hello, BinaryWriter!");  // string
            writer.Write(new byte[] { 0x01, 0x02, 0x03 }); // byte array
        }
        Console.WriteLine($"Data written to {filePath}");
    }
}

Requirements

Remarks

When you create an instance of BinaryWriter, you can specify an encoding. The default is UTF-8. If you want to write data that can be read by other applications or systems, it's crucial to use a consistent encoding.

The BinaryWriter class does not support seeking. If you need to seek within the stream, you should use a stream that supports seeking, such as FileStream, and call its Seek method before writing.

Remember to dispose of the BinaryWriter instance when you are finished with it, either by calling Close() or by using a using statement, to ensure that all buffered data is flushed and resources are released.