Object
MarshalByRefObject
TextWriter
StreamWriterThis type implements IDisposable.
mscorlib
BCL
Implements a Stream wrapper that writes characters to a stream in a particular encoding.
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) .]
System.IO Namespace
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
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.
- 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 istrue, 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.
Exception Type Condition IOException A general I/O exception occurred, such as trying to access a CD-ROM drive whose tray is open. DirectoryNotFoundException The directory information specified in path was not found. ArgumentException path is a zero-length string, contains only white space, or contains one or more implementation-specific invalid characters. ArgumentNullException path or encoding is null.System.IO.NotSupportedException path is in an implementation-specific invalid format. PathTooLongException The length of path or the absolute path information for path exceeds the implementation-specific maximum length. ArgumentOutOfRangeException bufferSize is negative. SecurityException The caller does not have the required permission. UnauthorizedAccessException Access is denied. The caller does not have the required permission.
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 .
]
System.IO.StreamWriter Class, System.IO Namespace
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.
- 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 istrue, the data is appended to the file. Otherwise, a new file is created.- encoding
- A Encoding that specifies the character encoding to use.
Exception Type Condition IOException A general I/O exception occurred, such as trying to access a CD-ROM drive whose tray is open. DirectoryNotFoundException The directory information specified in path was not found. UnauthorizedAccessException Access is denied. The caller does not have the required permission. ArgumentException path is a zero-length string, contains only white space, or contains one or more implementation-specific invalid characters. ArgumentNullException path or encoding is null.System.IO.NotSupportedException path is in an implementation-specific invalid format. PathTooLongException The length of path or the absolute path information for path exceeds the implementation-specific maximum length. SecurityException The caller does not have the required permission.
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.
]
System.IO.StreamWriter Class, System.IO Namespace
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.
- 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 istrue, the data is appended to the file. Otherwise, a new file is created.
Exception Type Condition IOException A general I/O exception occurs, such as trying to access a CD-ROM drive whose tray is open DirectoryNotFoundException The directory information specified in path was not found. UnauthorizedAccessException Access to path is denied. The caller does not have the required permission. ArgumentException path is a zero-length string, contains only white space, or contains one or more implementation-specific invalid characters. System.IO.NotSupportedException path is in an implementation-specific invalid format. PathTooLongException The length of path or the absolute path information for path exceeds the implementation-specific maximum length. ArgumentNullException path is null.SecurityException The caller does not have the required permission.
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.
]
System.IO.StreamWriter Class, System.IO Namespace
Constructs and initializes a new instance of the StreamWriter class for the specified stream, using the default encoding and buffer size.
- stream
- The Stream to write to.
Exception Type Condition ArgumentException stream does not support writing. ArgumentNullException stream is null.
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.]
System.IO.StreamWriter Class, System.IO Namespace
Constructs and initializes a new instance of the StreamWriter class for the specified stream, using the specified encoding and the default buffer size.
- stream
- The Stream to write to.
- encoding
- A Encoding that specifies the character encoding to use.
Exception Type Condition ArgumentNullException stream or encoding is null.ArgumentException stream does not support writing.
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.]
System.IO.StreamWriter Class, System.IO Namespace
Constructs and initializes a new instance of the StreamWriter class for the specified stream, using the specified encoding and buffer size.
- stream
- The Stream to write to.
- encoding
- A Encoding that specifies the character encoding to use.
- bufferSize
- A Int32 that specifies the buffer size.
Exception Type Condition ArgumentNullException stream or encoding is null.ArgumentOutOfRangeException bufferSize is negative. ArgumentException stream does not support writing.
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.
System.IO.StreamWriter Class, System.IO Namespace
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.
- path
- A String that specifies the complete file path to write to.
Exception Type Condition IOException path is in an invalid format or contains invalid characters. DirectoryNotFoundException The directory information specified in path was not found. UnauthorizedAccessException Access to path is denied. ArgumentException path is an empty string (""). ArgumentNullException path is null.PathTooLongException The length of path or the absolute path information for path exceeds the implementation-specific maximum length. SecurityException The caller does not have the required permission.
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.
]
System.IO.StreamWriter Class, System.IO Namespace
Closes the current StreamWriter and the underlying stream.
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.
]
System.IO.StreamWriter Class, System.IO Namespace
Releases the unmanaged resources used by the StreamWriter and optionally releases the managed resources.
- disposing
trueto release both managed and unmanaged resources;falseto release only unmanaged resources.
When the disposing parameter istrue, this method releases all resources held by any managed objects that this StreamWriter references. This method invokes theDispose()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).]
System.IO.StreamWriter Class, System.IO Namespace
Releases resources held by the current instance.
[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 .
]
System.IO.StreamWriter Class, System.IO Namespace
Clears all buffers for the current writer and causes any buffered data to be written to the underlying stream.
Exception Type Condition ObjectDisposedException The current writer is closed. IOException An I/O error occurred.
[Note: This method overrides System.IO.TextWriter.Flush.]
System.IO.StreamWriter Class, System.IO Namespace
Writes a character to the stream.
- value
- The Char to write to the underlying stream.
Exception Type Condition NotSupportedException System.IO.StreamWriter.AutoFlush is trueor 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.ObjectDisposedException The current writer is closed. IOException An I/O error occurred.
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).]
System.IO.StreamWriter Class, System.IO Namespace
Writes a character array to the underlying stream.
- buffer
- A Char array containing the data to write. If buffer is
null, nothing is written.
Exception Type Condition NotSupportedException System.IO.StreamWriter.AutoFlush is trueor 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.ObjectDisposedException The current writer is closed. IOException An I/O error occurred.
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).]
System.IO.StreamWriter Class, System.IO Namespace
Writes a sub-array of characters to the underlying stream.
- 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.
Exception Type Condition ArgumentException buffer.Length - index < count. ArgumentNullException buffer is null.ArgumentOutOfRangeException index or count is negative. NotSupportedException System.IO.StreamWriter.AutoFlush is trueor 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.ObjectDisposedException The current writer is closed. IOException An I/O error occurred.
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).]
System.IO.StreamWriter Class, System.IO Namespace
Writes a string to the stream.
- value
- The String to write to the stream. If value is
null, nothing is written.
Exception Type Condition NotSupportedException System.IO.StreamWriter.AutoFlush is trueor 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.ObjectDisposedException The current writer is closed. IOException An I/O error occurred.
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).]
System.IO.StreamWriter Class, System.IO Namespace
public virtual bool AutoFlush { get; set; }
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).
trueto force StreamWriter to flush its buffer; otherwise,false.
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 tofalse, 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
trueforces 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.]
System.IO.StreamWriter Class, System.IO Namespace
public virtual Stream BaseStream { get; }
Gets the underlying stream.
The Stream the current StreamWriter instance is writing to.
[Behaviors: As described above.]
System.IO.StreamWriter Class, System.IO Namespace
public override Encoding Encoding { get; }
Gets the Encoding in which the output is written.
The Encoding specified in the constructor for the current instance, or UTF8Encoding if an encoding was not specified.
[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.]
System.IO.StreamWriter Class, System.IO Namespace