StreamWriter Constructors
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Initializes a new instance of the StreamWriter class.
Overloads
| StreamWriter(Stream) |
Initializes a new instance of the StreamWriter class for the specified stream by using UTF-8 encoding and the default buffer size. |
| StreamWriter(String) |
Initializes a new instance of the StreamWriter class for the specified file by using the default encoding and buffer size. |
| StreamWriter(Stream, Encoding) |
Initializes a new instance of the StreamWriter class for the specified stream by using the specified encoding and the default buffer size. |
| StreamWriter(String, Boolean) |
Initializes a new instance of the StreamWriter class for the specified file by using the default encoding and buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file. |
| StreamWriter(String, FileStreamOptions) |
Initializes a new instance of the StreamWriter class for the specified file, using the default encoding, and configured with the specified FileStreamOptions object. |
| StreamWriter(Stream, Encoding, Int32) |
Initializes a new instance of the StreamWriter class for the specified stream by using the specified encoding and buffer size. |
| StreamWriter(String, Boolean, Encoding) |
Initializes a new instance of the StreamWriter class for the specified file by using the specified encoding and default buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file. |
| StreamWriter(String, Encoding, FileStreamOptions) |
Initializes a new instance of the StreamWriter class for the specified file, using the specified encoding, and configured with the specified FileStreamOptions object. |
| StreamWriter(Stream, Encoding, Int32, Boolean) |
Initializes a new instance of the StreamWriter class for the specified stream by using the specified encoding and buffer size, and optionally leaves the stream open. |
| StreamWriter(String, Boolean, Encoding, Int32) |
Initializes a new instance of the StreamWriter class for the specified file on the specified path, using the specified encoding and buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file. |
StreamWriter(Stream)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified stream by using UTF-8 encoding and the default buffer size.
public:
StreamWriter(System::IO::Stream ^ stream);public StreamWriter(System.IO.Stream stream);new System.IO.StreamWriter : System.IO.Stream -> System.IO.StreamWriterPublic Sub New (stream As Stream)Parameters
- stream
- Stream
The stream to write to.
Exceptions
stream is not writable.
stream is null.
Examples
The following code example demonstrates this constructor.
using System;
using System.IO;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
FileStream fs = null;
try
{
fs = new FileStream(fileName, FileMode.CreateNew);
using (StreamWriter writer = new StreamWriter(fs))
{
writer.Write(textToAdd);
}
}
finally
{
if (fs != null)
fs.Dispose();
}
}
}
}
Imports System.IO
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Dim fs As FileStream = Nothing
Try
fs = New FileStream(fileName, FileMode.CreateNew)
Using writer As StreamWriter = New StreamWriter(fs)
writer.Write(textToAdd)
End Using
Finally
If Not fs Is Nothing Then
fs.Dispose()
End If
End Try
End Sub
End Module
Remarks
This constructor creates a StreamWriter with UTF-8 encoding without a Byte-Order Mark (BOM), so its GetPreamble method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the Encoding.UTF8 property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as StreamWriter. The BaseStream property is initialized using the stream parameter. The position of the stream is not reset.
The StreamWriter object calls Dispose() on the provided Stream object when StreamWriter.Dispose is called.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown.
For a list of common I/O tasks, see Common I/O Tasks.
See also
Applies to
StreamWriter(String)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified file by using the default encoding and buffer size.
public:
StreamWriter(System::String ^ path);public StreamWriter(string path);new System.IO.StreamWriter : string -> System.IO.StreamWriterPublic Sub New (path As String)Parameters
- path
- String
The complete file path to write to. path can be a file name.
Exceptions
Access is denied.
path is an empty string ("").
-or-
path contains the name of a system device (com1, com2, and so on).
path is null.
The specified path is invalid (for example, it is on an unmapped drive).
The specified path, file name, or both exceed the system-defined maximum length.
path includes an incorrect or invalid syntax for file name, directory name, or volume label syntax.
The caller does not have the required permission.
Examples
The following code example demonstrates this constructor.
using System;
using System.IO;
using System.Text;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
using (StreamWriter writer = new StreamWriter(fileName))
{
writer.Write(textToAdd);
}
}
}
}
Imports System.IO
Imports System.Text
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Using writer As StreamWriter = New StreamWriter(fileName)
writer.Write(textToAdd)
End Using
End Sub
End Module
Remarks
This constructor creates a StreamWriter with UTF-8 encoding without a Byte-Order Mark (BOM), so its GetPreamble method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the Encoding.UTF8 property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as StreamWriter(String, Boolean, Encoding).
The path parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. If the file exists, it is overwritten; otherwise, a new file is created.
The path parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown.
For a list of common I/O tasks, see Common I/O Tasks.
See also
Applies to
StreamWriter(Stream, Encoding)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified stream by using the specified encoding and the default buffer size.
public:
StreamWriter(System::IO::Stream ^ stream, System::Text::Encoding ^ encoding);public StreamWriter(System.IO.Stream stream, System.Text.Encoding encoding);public StreamWriter(System.IO.Stream stream, System.Text.Encoding? encoding);new System.IO.StreamWriter : System.IO.Stream * System.Text.Encoding -> System.IO.StreamWriterPublic Sub New (stream As Stream, encoding As Encoding)Parameters
- stream
- Stream
The stream to write to.
- encoding
- Encoding
The character encoding to use.
Exceptions
stream or encoding is null.
stream is not writable.
Examples
The following example demonstrates this constructor.
using System;
using System.IO;
using System.Text;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
FileStream fs = null;
try
{
fs = new FileStream(fileName, FileMode.CreateNew);
using (StreamWriter writer = new StreamWriter(fs, Encoding.Default))
{
writer.Write(textToAdd);
}
}
finally
{
if (fs != null)
fs.Dispose();
}
}
}
}
Imports System.IO
Imports System.Text
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Dim fs As FileStream = Nothing
Try
fs = New FileStream(fileName, FileMode.CreateNew)
Using writer As StreamWriter = New StreamWriter(fs, Encoding.Default)
writer.Write(textToAdd)
End Using
Finally
If Not fs Is Nothing Then
fs.Dispose()
End If
End Try
End Sub
End Module
Remarks
This constructor initializes the Encoding property using the encoding parameter, and the BaseStream property using the stream parameter. The position of the stream is not reset. For additional information, see Encoding.
The StreamWriter object calls Dispose() on the provided Stream object when StreamWriter.Dispose is called.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown.
For a list of common I/O tasks, see Common I/O Tasks.
See also
Applies to
StreamWriter(String, Boolean)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified file by using the default encoding and buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file.
public:
StreamWriter(System::String ^ path, bool append);public StreamWriter(string path, bool append);new System.IO.StreamWriter : string * bool -> System.IO.StreamWriterPublic Sub New (path As String, append As Boolean)Parameters
- path
- String
The complete file path to write to.
- append
- Boolean
true to append data to the file; false to overwrite the file. If the specified file does not exist, this parameter has no effect, and the constructor creates a new file.
Exceptions
Access is denied.
path is empty.
-or-
path contains the name of a system device (com1, com2, and so on).
path is null.
The specified path is invalid (for example, it is on an unmapped drive).
path includes an incorrect or invalid syntax for file name, directory name, or volume label syntax.
The specified path, file name, or both exceed the system-defined maximum length.
The caller does not have the required permission.
Examples
The following code example demonstrates this constructor.
using System;
using System.IO;
using System.Text;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
using (StreamWriter writer = new StreamWriter(fileName, true))
{
writer.Write(textToAdd);
}
}
}
}
Imports System.IO
Imports System.Text
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Using writer As StreamWriter = New StreamWriter(fileName, True)
writer.Write(textToAdd)
End Using
End Sub
End Module
Remarks
This constructor creates a StreamWriter with UTF-8 encoding without a Byte-Order Mark (BOM), so its GetPreamble method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the Encoding.UTF8 property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as StreamWriter(String, Boolean, Encoding).
The path parameter can be a file name, including a file on a Universal Naming Convention (UNC) share.
The path parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown.
For a list of common I/O tasks, see Common I/O Tasks.
See also
Applies to
StreamWriter(String, FileStreamOptions)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified file, using the default encoding, and configured with the specified FileStreamOptions object.
public:
StreamWriter(System::String ^ path, System::IO::FileStreamOptions ^ options);public StreamWriter(string path, System.IO.FileStreamOptions options);new System.IO.StreamWriter : string * System.IO.FileStreamOptions -> System.IO.StreamWriterPublic Sub New (path As String, options As FileStreamOptions)Parameters
- path
- String
The complete file path to write to.
- options
- FileStreamOptions
An object that specifies the configuration options for the underlying FileStream.
Exceptions
options is null
.
path is not writable.
See also
Applies to
StreamWriter(Stream, Encoding, Int32)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified stream by using the specified encoding and buffer size.
public:
StreamWriter(System::IO::Stream ^ stream, System::Text::Encoding ^ encoding, int bufferSize);public StreamWriter(System.IO.Stream stream, System.Text.Encoding encoding, int bufferSize);public StreamWriter(System.IO.Stream stream, System.Text.Encoding? encoding, int bufferSize);new System.IO.StreamWriter : System.IO.Stream * System.Text.Encoding * int -> System.IO.StreamWriterPublic Sub New (stream As Stream, encoding As Encoding, bufferSize As Integer)Parameters
- stream
- Stream
The stream to write to.
- encoding
- Encoding
The character encoding to use.
- bufferSize
- Int32
The buffer size, in characters.
Exceptions
stream or encoding is null.
bufferSize is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.
stream is not writable.
Examples
The following example demonstrates this constructor.
using System;
using System.IO;
using System.Text;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
FileStream fs = null;
try
{
fs = new FileStream(fileName, FileMode.CreateNew);
using (StreamWriter writer = new StreamWriter(fs, Encoding.UTF8, 512))
{
writer.Write(textToAdd);
}
}
finally
{
if (fs != null)
fs.Dispose();
}
}
}
}
Imports System.IO
Imports System.Text
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Dim fs As FileStream = Nothing
Try
fs = New FileStream(fileName, FileMode.CreateNew)
Using writer As StreamWriter = New StreamWriter(fs, Encoding.Default, 512)
writer.Write(textToAdd)
End Using
Finally
If Not fs Is Nothing Then
fs.Dispose()
End If
End Try
End Sub
End Module
Remarks
This constructor initializes the Encoding property using the encoding parameter, and the BaseStream property using the stream parameter. The position of the stream is not reset. For additional information, see Encoding.
The StreamWriter object calls Dispose() on the provided Stream object when StreamWriter.Dispose is called.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown.
For a list of common I/O tasks, see Common I/O Tasks.
See also
Applies to
StreamWriter(String, Boolean, Encoding)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified file by using the specified encoding and default buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file.
public:
StreamWriter(System::String ^ path, bool append, System::Text::Encoding ^ encoding);public StreamWriter(string path, bool append, System.Text.Encoding? encoding);public StreamWriter(string path, bool append, System.Text.Encoding encoding);new System.IO.StreamWriter : string * bool * System.Text.Encoding -> System.IO.StreamWriterPublic Sub New (path As String, append As Boolean, encoding As Encoding)Parameters
- path
- String
The complete file path to write to.
- append
- Boolean
true to append data to the file; false to overwrite the file. If the specified file does not exist, this parameter has no effect, and the constructor creates a new file.
- encoding
- Encoding
The character encoding to use.
Exceptions
Access is denied.
path is empty.
-or-
path contains the name of a system device (com1, com2, and so on).
path is null.
The specified path is invalid (for example, it is on an unmapped drive).
path includes an incorrect or invalid syntax for file name, directory name, or volume label syntax.
The specified path, file name, or both exceed the system-defined maximum length.
The caller does not have the required permission.
Examples
The following example demonstrates this constructor.
using System;
using System.IO;
using System.Text;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
using (StreamWriter writer = new StreamWriter(fileName, true, Encoding.UTF8))
{
writer.Write(textToAdd);
}
}
}
}
Imports System.IO
Imports System.Text
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Using writer As StreamWriter = New StreamWriter(fileName, True, Encoding.UTF8)
writer.Write(textToAdd)
End Using
End Sub
End Module
Remarks
This constructor initializes the Encoding property using the encoding parameter. For additional information, see Encoding.
path can be a file name, including a file on a Universal Naming Convention (UNC) share.
path is not required to be a file stored on disk; it can be any part of a system that supports access via streams.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown.
For a list of common I/O tasks, see Common I/O Tasks.
See also
Applies to
StreamWriter(String, Encoding, FileStreamOptions)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified file, using the specified encoding, and configured with the specified FileStreamOptions object.
public:
StreamWriter(System::String ^ path, System::Text::Encoding ^ encoding, System::IO::FileStreamOptions ^ options);public StreamWriter(string path, System.Text.Encoding? encoding, System.IO.FileStreamOptions options);public StreamWriter(string path, System.Text.Encoding encoding, System.IO.FileStreamOptions options);new System.IO.StreamWriter : string * System.Text.Encoding * System.IO.FileStreamOptions -> System.IO.StreamWriterPublic Sub New (path As String, encoding As Encoding, options As FileStreamOptions)Parameters
- path
- String
The complete file path to write to.
- encoding
- Encoding
The character encoding to use.
- options
- FileStreamOptions
An object that specifies the configuration options for the underlying FileStream.
Exceptions
options is null
.
path is not writable.
See also
Applies to
StreamWriter(Stream, Encoding, Int32, Boolean)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified stream by using the specified encoding and buffer size, and optionally leaves the stream open.
public:
StreamWriter(System::IO::Stream ^ stream, System::Text::Encoding ^ encoding, int bufferSize, bool leaveOpen);public StreamWriter(System.IO.Stream stream, System.Text.Encoding encoding, int bufferSize, bool leaveOpen);public StreamWriter(System.IO.Stream stream, System.Text.Encoding? encoding = default, int bufferSize = -1, bool leaveOpen = false);new System.IO.StreamWriter : System.IO.Stream * System.Text.Encoding * int * bool -> System.IO.StreamWriterPublic Sub New (stream As Stream, encoding As Encoding, bufferSize As Integer, leaveOpen As Boolean)Public Sub New (stream As Stream, Optional encoding As Encoding = Nothing, Optional bufferSize As Integer = -1, Optional leaveOpen As Boolean = false)Parameters
- stream
- Stream
The stream to write to.
- encoding
- Encoding
The character encoding to use.
- bufferSize
- Int32
The buffer size, in characters.
- leaveOpen
- Boolean
true to leave the stream open after the StreamWriter object is disposed; otherwise, false.
Exceptions
stream or encoding is null.
bufferSize is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.
stream is not writable.
Examples
The following example demonstrates this constructor.
using System;
using System.IO;
using System.Text;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
FileStream fs = null;
try
{
fs = new FileStream(fileName, FileMode.CreateNew);
using (StreamWriter writer = new StreamWriter(fs, Encoding.UTF8, 512, false))
{
writer.Write(textToAdd);
}
}
finally
{
if (fs != null)
fs.Dispose();
}
}
}
}
Imports System.IO
Imports System.Text
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Dim fs As FileStream = Nothing
Try
fs = New FileStream(fileName, FileMode.CreateNew)
Using writer As StreamWriter = New StreamWriter(fs, Encoding.Default, 512, False)
writer.Write(textToAdd)
End Using
Finally
If Not fs Is Nothing Then
fs.Dispose()
End If
End Try
End Sub
End Module
Remarks
Unless you set the leaveOpen parameter to true, the StreamWriter object calls Dispose() on the provided Stream object when StreamWriter.Dispose is called.
This constructor initializes the Encoding property by using the encoding parameter, and initializes the BaseStream property by using the stream parameter. The position of the stream is not reset. For additional information, see the Encoding property.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown.
Applies to
StreamWriter(String, Boolean, Encoding, Int32)
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
- Source:
- StreamWriter.cs
Initializes a new instance of the StreamWriter class for the specified file on the specified path, using the specified encoding and buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file.
public:
StreamWriter(System::String ^ path, bool append, System::Text::Encoding ^ encoding, int bufferSize);public StreamWriter(string path, bool append, System.Text.Encoding? encoding, int bufferSize);public StreamWriter(string path, bool append, System.Text.Encoding encoding, int bufferSize);new System.IO.StreamWriter : string * bool * System.Text.Encoding * int -> System.IO.StreamWriterPublic Sub New (path As String, append As Boolean, encoding As Encoding, bufferSize As Integer)Parameters
- path
- String
The complete file path to write to.
- append
- Boolean
true to append data to the file; false to overwrite the file. If the specified file does not exist, this parameter has no effect, and the constructor creates a new file.
- encoding
- Encoding
The character encoding to use.
- bufferSize
- Int32
The buffer size, in characters.
Exceptions
path is an empty string ("").
-or-
path contains the name of a system device (com1, com2, and so on).
path or encoding is null.
bufferSize is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.
path includes an incorrect or invalid syntax for file name, directory name, or volume label syntax.
The caller does not have the required permission.
Access is denied.
The specified path is invalid (for example, it is on an unmapped drive).
The specified path, file name, or both exceed the system-defined maximum length.
Examples
The following example demonstrates this constructor.
using System;
using System.IO;
using System.Text;
namespace ConsoleApplication
{
class Program
{
static void Main(string[] args)
{
string fileName = "test.txt";
string textToAdd = "Example text in file";
using (StreamWriter writer = new StreamWriter(fileName, true, Encoding.UTF8, 512))
{
writer.Write(textToAdd);
}
}
}
}
Imports System.IO
Imports System.Text
Module Module1
Sub Main()
Dim fileName As String = "test.txt"
Dim textToAdd As String = "Example text in file"
Using writer As StreamWriter = New StreamWriter(fileName, True, Encoding.UTF8, 512)
writer.Write(textToAdd)
End Using
End Sub
End Module
Remarks
This constructor initializes the Encoding property using the encoding parameter. For additional information, see Encoding.
path can be a file name, including a file on a Universal Naming Convention (UNC) share.
path is not required to be a file stored on disk; it can be any part of a system that supports access via streams.
Caution
When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown.
For a list of common I/O tasks, see Common I/O Tasks.
