System.IO.StreamWriter Class

public class StreamWriter : TextWriter

Base Types

Object
  MarshalByRefObject
    TextWriter
      StreamWriter

This type implements IDisposable.

Assembly

mscorlib

Library

BCL

Summary

Implements a Stream wrapper that writes characters to a stream in a particular encoding.

Description

The StreamWriter class is designed for character output in a particular Encoding, whereas subclasses of Stream are designed for byte input and output.

StreamWriter defaults to using an instance of UTF8Encoding unless specified otherwise. This instance of UTF8Encoding is constructed such that the System.Text.Encoding.GetPreamble method returns the Unicode byte order mark written in UTF-8. The preamble of the encoding is added to a stream when you are not appending to an existing stream. This means any text file you create with StreamWriter has three byte order marks at its beginning. UTF-8 handles all Unicode characters correctly and gives consistent results on localized versions of the operating system.

[Note: By default, StreamWriter is not thread safe. For a thread-safe wrapper, see System.IO.TextWriter.Synchronized(System.IO.TextWriter) .]

See Also

System.IO Namespace

Members

StreamWriter Constructors

StreamWriter(System.String, bool, System.Text.Encoding, int) Constructor
StreamWriter(System.String, bool, System.Text.Encoding) Constructor
StreamWriter(System.String, bool) Constructor
StreamWriter(System.IO.Stream) Constructor
StreamWriter(System.IO.Stream, System.Text.Encoding) Constructor
StreamWriter(System.IO.Stream, System.Text.Encoding, int) Constructor
StreamWriter(System.String) Constructor

StreamWriter Methods

StreamWriter.Close Method
StreamWriter.Dispose Method
StreamWriter.Finalize Method
StreamWriter.Flush Method
StreamWriter.Write(char) Method
StreamWriter.Write(char[]) Method
StreamWriter.Write(char[], int, int) Method
StreamWriter.Write(System.String) Method

StreamWriter Properties

StreamWriter.AutoFlush Property
StreamWriter.BaseStream Property
StreamWriter.Encoding Property


StreamWriter(System.String, bool, System.Text.Encoding, int) Constructor

public StreamWriter(string path, bool append, Encoding encoding, int bufferSize);

Summary

Constructs and initializes a new instance of the StreamWriter class for the specified file on the specified path, using the specified encoding and buffer size.

Parameters

path
A String that specifies the complete file path to write to.
append
A Boolean value that determines whether data is to be appended to the file. If the file exists and append is false , the file is overwritten. If the file exists and append is true , the data is appended to the file. Otherwise, a new file is created.
encoding
A Encoding that specifies the character encoding to use.
bufferSize
A Int32 that specifies the buffer size.

Exceptions

Exception TypeCondition
IOExceptionA general I/O exception occurred, such as trying to access a CD-ROM drive whose tray is open.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
ArgumentExceptionpath is a zero-length string, contains only white space, or contains one or more implementation-specific invalid characters.
ArgumentNullExceptionpath or encoding is null .
System.IO.NotSupportedExceptionpath is in an implementation-specific invalid format.
PathTooLongExceptionThe length of path or the absolute path information for path exceeds the implementation-specific maximum length.
ArgumentOutOfRangeExceptionbufferSize is negative.
SecurityExceptionThe caller does not have the required permission.
UnauthorizedAccessExceptionAccess is denied. The caller does not have the required permission.

Description

If the specified file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file.

This constructor initializes the System.IO.StreamWriter.Encoding property using encoding . For additional information, see System.IO.TextWriter.Encoding.

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path .

]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter(System.String, bool, System.Text.Encoding) Constructor

public StreamWriter(string path, bool append, Encoding encoding);

Summary

Constructs and initializes a new instance of the StreamWriter class for the specified file on the specified path, using the specified encoding and default buffer size.

Parameters

path
A String that specifies the complete file path to write to.
append
A Boolean value that determines whether data is to be appended to the file. If the file exists and append is false , the file is overwritten. If the file exists and append is true , the data is appended to the file. Otherwise, a new file is created.
encoding
A Encoding that specifies the character encoding to use.

Exceptions

Exception TypeCondition
IOExceptionA general I/O exception occurred, such as trying to access a CD-ROM drive whose tray is open.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
UnauthorizedAccessExceptionAccess is denied. The caller does not have the required permission.
ArgumentExceptionpath is a zero-length string, contains only white space, or contains one or more implementation-specific invalid characters.
ArgumentNullExceptionpath or encoding is null .
System.IO.NotSupportedExceptionpath is in an implementation-specific invalid format.
PathTooLongExceptionThe length of path or the absolute path information for path exceeds the implementation-specific maximum length.
SecurityExceptionThe caller does not have the required permission.

Description

If the specified file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file.

This constructor initializes the System.IO.StreamWriter.Encoding property using encoding . For additional information, see System.IO.TextWriter.Encoding.

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path .

The default buffer size can typically be around 4 KB.

]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter(System.String, bool) Constructor

public StreamWriter(string path, bool append);

Summary

Constructs and initializes a new instance of the StreamWriter class for the specified file on the specified path, using the default encoding and buffer size.

Parameters

path
A String that specifies the complete file path to write to.
append
A Boolean value that determines whether data is to be appended to the file. If the file exists and append is false , the file is overwritten. If the file exists and append is true , the data is appended to the file. Otherwise, a new file is created.

Exceptions

Exception TypeCondition
IOExceptionA general I/O exception occurs, such as trying to access a CD-ROM drive whose tray is open
DirectoryNotFoundExceptionThe directory information specified in path was not found.
UnauthorizedAccessExceptionAccess to path is denied. The caller does not have the required permission.
ArgumentExceptionpath is a zero-length string, contains only white space, or contains one or more implementation-specific invalid characters.
System.IO.NotSupportedExceptionpath is in an implementation-specific invalid format.
PathTooLongExceptionThe length of path or the absolute path information for path exceeds the implementation-specific maximum length.
ArgumentNullExceptionpath is null .
SecurityExceptionThe caller does not have the required permission.

Description

This constructor initializes the System.IO.StreamWriter.Encoding property to UTF8Encoding whose System.Text.Encoding.GetPreamble method returns an empty byte array. For additional information, see System.IO.TextWriter.Encoding .

If the specified file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file.

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path .

The default buffer size can typically be around 4 KB.

]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter(System.IO.Stream) Constructor

public StreamWriter(Stream stream);

Summary

Constructs and initializes a new instance of the StreamWriter class for the specified stream, using the default encoding and buffer size.

Parameters

stream
The Stream to write to.

Exceptions

Exception TypeCondition
ArgumentExceptionstream does not support writing.
ArgumentNullExceptionstream is null .

Description

This constructor initializes the System.IO.StreamWriter.Encoding property to a UTF8Encoding whose System.Text.Encoding.GetPreamble method returns an empty byte array. For additional information, see System.IO.TextWriter.Encoding . The System.IO.StreamWriter.BaseStream property is initialized using stream .

[Note: The default buffer size can typically be around 4 KB.]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter(System.IO.Stream, System.Text.Encoding) Constructor

public StreamWriter(Stream stream, Encoding encoding);

Summary

Constructs and initializes a new instance of the StreamWriter class for the specified stream, using the specified encoding and the default buffer size.

Parameters

stream
The Stream to write to.
encoding
A Encoding that specifies the character encoding to use.

Exceptions

Exception TypeCondition
ArgumentNullExceptionstream or encoding is null .
ArgumentExceptionstream does not support writing.

Description

This constructor initializes the System.IO.StreamWriter.Encoding property using encoding , and the System.IO.StreamWriter.BaseStream property using stream . For additional information, see System.IO.TextWriter.Encoding.

[Note: The default buffer size can typically be around 4 KB.]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter(System.IO.Stream, System.Text.Encoding, int) Constructor

public StreamWriter(Stream stream, Encoding encoding, int bufferSize);

Summary

Constructs and initializes a new instance of the StreamWriter class for the specified stream, using the specified encoding and buffer size.

Parameters

stream
The Stream to write to.
encoding
A Encoding that specifies the character encoding to use.
bufferSize
A Int32 that specifies the buffer size.

Exceptions

Exception TypeCondition
ArgumentNullExceptionstream or encoding is null .
ArgumentOutOfRangeExceptionbufferSize is negative.
ArgumentExceptionstream does not support writing.

Description

This constructor initializes the System.IO.StreamWriter.Encoding property using encoding , and the System.IO.StreamWriter.BaseStream property using stream . For additional information, see System.IO.TextWriter.Encoding.

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter(System.String) Constructor

public StreamWriter(string path);

Summary

Constructs and initializes a new instance of the StreamWriter class for the specified file on the specified path, using the default encoding and buffer size.

Parameters

path
A String that specifies the complete file path to write to.

Exceptions

Exception TypeCondition
IOExceptionpath is in an invalid format or contains invalid characters.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
UnauthorizedAccessExceptionAccess to path is denied.
ArgumentExceptionpath is an empty string ("").
ArgumentNullExceptionpath is null .
PathTooLongExceptionThe length of path or the absolute path information for path exceeds the implementation-specific maximum length.
SecurityExceptionThe caller does not have the required permission.

Description

This constructor initializes the System.IO.StreamWriter.Encoding property to a UTF8Encoding whose System.Text.Encoding.GetPreamble method returns an empty byte array. For additional information, see System.IO.TextWriter.Encoding .

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path .

The default buffer size can typically be around 4 KB.

]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Close Method

public override void Close();

Summary

Closes the current StreamWriter and the underlying stream.

Description

This method calls System.IO.StreamWriter.Flush , writing buffered data to the underlying stream. Following a call to System.IO.StreamWriter.Close, any operations on the current instance might raise exceptions.

[Note: This version of System.IO.StreamWriter.Close is equivalent to System.IO.StreamWriter.Dispose(System.Boolean)(true ).

This method overrides System.IO.Stream.Close.

]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Dispose Method

protected override void Dispose(bool disposing);

Summary

Releases the unmanaged resources used by the StreamWriter and optionally releases the managed resources.

Parameters

disposing
true to release both managed and unmanaged resources; false to release only unmanaged resources.

Description

When the disposing parameter is true , this method releases all resources held by any managed objects that this StreamWriter references. This method invokes the Dispose() method of each referenced object.

[Note: System.IO.StreamWriter.Dispose(System.Boolean) can be called multiple times by other objects. When overriding System.IO.StreamWriter.Dispose(System.Boolean)(Boolean), be careful not to reference objects that have been previously disposed in an earlier call to System.IO.StreamWriter.Dispose(System.Boolean).

This method calls the dispose method of the base class, System.IO.TextWriter.Dispose(System.Boolean)( disposing) .

]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Finalize Method

~StreamWriter();

Summary

Releases resources held by the current instance.

Description

[Note: Application code does not call this method; it is automatically invoked by during garbage collection unless finalization by the garbage collector has been disabled. For more information, see System.GC.SuppressFinalize(System.Object), and System.Object.Finalize.

This method overrides System.Object.Finalize .

]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Flush Method

public override void Flush();

Summary

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

Exceptions

Exception TypeCondition
ObjectDisposedExceptionThe current writer is closed.
IOException An I/O error occurred.

Description

[Note: This method overrides System.IO.TextWriter.Flush.]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Write(char) Method

public override void Write(char value);

Summary

Writes a character to the stream.

Parameters

value
The Char to write to the underlying stream.

Exceptions

Exception TypeCondition
NotSupportedExceptionSystem.IO.StreamWriter.AutoFlush is true or the StreamWriter buffer is full, and the contents of the buffer cannot be written to the underlying fixed size stream because the StreamWriter is at the end the stream.
ObjectDisposedExceptionThe current writer is closed.
IOException An I/O error occurred.

Description

The specified character is written to the underlying stream unless the end of the stream is reached prematurely.

If System.IO.StreamWriter.AutoFlush is true , System.IO.StreamWriter.Flush is invoked automatically.

[Note: This method overrides System.IO.TextWriter.Write(System.Char).]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Write(char[]) Method

public override void Write(char[] buffer);

Summary

Writes a character array to the underlying stream.

Parameters

buffer
A Char array containing the data to write. If buffer is null , nothing is written.

Exceptions

Exception TypeCondition
NotSupportedExceptionSystem.IO.StreamWriter.AutoFlush is true or the StreamWriter buffer is full, and the contents of the buffer cannot be written to the underlying fixed size stream because the StreamWriter is at the end the stream.
ObjectDisposedExceptionThe current writer is closed.
IOException An I/O error occurred.

Description

The specified characters are written to the underlying stream unless the end of the stream is reached prematurely.

If System.IO.StreamWriter.AutoFlush is true , System.IO.StreamWriter.Flush is invoked automatically.

[Note: This method overrides System.IO.TextWriter.Write(System.Char).]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Write(char[], int, int) Method

public override void Write(char[] buffer, int index, int count);

Summary

Writes a sub-array of characters to the underlying stream.

Parameters

buffer
A Char array containing the data to write.
index
A Int32 that specifies the index into buffer at which to begin writing.
count
A Int32 that specifies the number of characters to read from buffer.

Exceptions

Exception TypeCondition
ArgumentExceptionbuffer.Length - index < count.
ArgumentNullExceptionbuffer is null .
ArgumentOutOfRangeExceptionindex or count is negative.
NotSupportedExceptionSystem.IO.StreamWriter.AutoFlush is true or the StreamWriter buffer is full, and the contents of the buffer cannot be written to the underlying fixed size stream because the StreamWriter is at the end the stream.
ObjectDisposedExceptionThe current writer is closed.
IOExceptionAn I/O error occurred.

Description

The specified characters are written to the underlying stream unless the end of the stream is reached prematurely.

If System.IO.StreamWriter.AutoFlush is true , System.IO.StreamWriter.Flush is invoked automatically.

[Note: This method overrides System.IO.TextWriter.Write(System.Char).]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Write(System.String) Method

public override void Write(string value);

Summary

Writes a string to the stream.

Parameters

value
The String to write to the stream. If value is null , nothing is written.

Exceptions

Exception TypeCondition
NotSupportedExceptionSystem.IO.StreamWriter.AutoFlush is true or the StreamWriter buffer is full, and the contents of the buffer cannot be written to the underlying fixed size stream because the StreamWriter is at the end the stream.
ObjectDisposedExceptionThe current writer is closed.
IOException An I/O error occurred.

Description

The specified String is written to the underlying stream unless the end of the stream is reached prematurely.

If System.IO.StreamWriter.AutoFlush is true , System.IO.StreamWriter.Flush is invoked automatically.

[Note: This method overrides System.IO.TextWriter.Write(System.Char).]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.AutoFlush Property

public virtual bool AutoFlush { get; set; }

Summary

Gets or sets a Boolean value indicating whether the current StreamWriter will flush its buffer to the underlying stream after every call to System.IO.StreamWriter.Write(System.Char).

Property Value

true to force StreamWriter to flush its buffer; otherwise, false .

Description

The StreamWriter will do a limited amount of buffering, both internally and potentially in the encoder from the encoding you passed in. If System.IO.StreamWriter.AutoFlush is set to false , the data will be flushed into the underlying stream only when the buffer is full, or when System.IO.StreamWriter.Dispose(System.Boolean)(true ) or System.IO.StreamWriter.Close is called.

Setting System.IO.StreamWriter.AutoFlush to true forces StreamWriter to flush the buffered data out of the encoder and call System.IO.StreamWriter.Flush on the stream every time System.IO.StreamWriter.Write(System.Char) is called.

[Behaviors: As described above.]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.BaseStream Property

public virtual Stream BaseStream { get; }

Summary

Gets the underlying stream.

Property Value

The Stream the current StreamWriter instance is writing to.

Description

[Behaviors: As described above.]

See Also

System.IO.StreamWriter Class, System.IO Namespace

StreamWriter.Encoding Property

public override Encoding Encoding { get; }

Summary

Gets the Encoding in which the output is written.

Property Value

The Encoding specified in the constructor for the current instance, or UTF8Encoding if an encoding was not specified.

Description

[Note: This property overrides the System.IO.TextWriter.Encoding property.]

[Behaviors: As described above.]

[Usage: This property is required in some XML scenarios where a header must be written containing the encoding used by the StreamWriter. This allows XML code to consume an arbitrary StreamWriter and generate a correct XML header.]

See Also

System.IO.StreamWriter Class, System.IO Namespace