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
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.StreamWriter
Public 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
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.StreamWriter
Public 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
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);
new System.IO.StreamWriter : System.IO.Stream * System.Text.Encoding -> System.IO.StreamWriter
Public 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
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.StreamWriter
Public 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
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.StreamWriter
Public 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
.
stream
is not writable.
See also
Applies to
StreamWriter(Stream, Encoding, Int32)
- 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);
new System.IO.StreamWriter : System.IO.Stream * System.Text.Encoding * int -> System.IO.StreamWriter
Public 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 bytes.
Exceptions
stream
or encoding
is null
.
bufferSize
is negative.
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
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);
new System.IO.StreamWriter : string * bool * System.Text.Encoding -> System.IO.StreamWriter
Public 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
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);
new System.IO.StreamWriter : string * System.Text.Encoding * System.IO.FileStreamOptions -> System.IO.StreamWriter
Public 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
.
stream
is not writable.
See also
Applies to
StreamWriter(Stream, Encoding, Int32, Boolean)
- 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.StreamWriter
Public 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 bytes.
- leaveOpen
- Boolean
true
to leave the stream open after the StreamWriter object is disposed; otherwise, false
.
Exceptions
stream
or encoding
is null
.
bufferSize
is negative.
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
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);
new System.IO.StreamWriter : string * bool * System.Text.Encoding * int -> System.IO.StreamWriter
Public 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 bytes.
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 negative.
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.