SqlBulkCopy 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.
Overloads
| SqlBulkCopy(SqlConnection) |
Initializes a new instance of the SqlBulkCopy class using the specified open instance of SqlConnection . |
| SqlBulkCopy(String) |
Initializes and opens a new instance of
SqlConnection
based on the supplied
|
| SqlBulkCopy(String, SqlBulkCopyOptions) |
Initializes and opens a new instance of
SqlConnection
based on the supplied
|
| SqlBulkCopy(SqlConnection, SqlBulkCopyOptions, SqlTransaction) |
Initializes a new instance of the
SqlBulkCopy
class using the supplied existing open instance of
SqlConnection
. The
SqlBulkCopy
instance behaves according to options supplied in the
|
SqlBulkCopy(SqlConnection)
Initializes a new instance of the SqlBulkCopy class using the specified open instance of SqlConnection .
public:
SqlBulkCopy(Microsoft::Data::SqlClient::SqlConnection ^ connection);public SqlBulkCopy (Microsoft.Data.SqlClient.SqlConnection connection);new Microsoft.Data.SqlClient.SqlBulkCopy : Microsoft.Data.SqlClient.SqlConnection -> Microsoft.Data.SqlClient.SqlBulkCopyPublic Sub New (connection As SqlConnection)Parameters
- connection
- SqlConnection
The already open
SqlConnection
instance that will be used to perform the bulk copy operation. If your connection string does not use
Integrated Security = true
, you can use
SqlCredential
to pass the user ID and password more securely than by specifying the user ID and password as text in the connection string.
Examples
The following console application demonstrates how to bulk load data using a connection that is already open. In this example, a SqlDataReader
is used to copy data from the Production.Product table in the SQL Server AdventureWorks database to a similar table in the same database. This example is for demonstration
purposes only. You would not use SqlBulkCopy to move data from one table to another in the same database in a production application.
Note that the source data does not have to be located on SQL Server; you can use any data source that can be read to an IDataReader or loaded to a
DataTable.
Important
This sample will not run unless you have created the work tables as described in Bulk Copy Example Setup.
This code is provided to demonstrate the syntax for using SqlBulkCopy only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a
Transact-SQL INSERT … SELECT statement to copy the data.
using Microsoft.Data.SqlClient;
class Program
{
static void Main()
{
string connectionString = GetConnectionString();
// Open a sourceConnection to the AdventureWorks database.
using (SqlConnection sourceConnection =
new SqlConnection(connectionString))
{
sourceConnection.Open();
// Perform an initial count on the destination table.
SqlCommand commandRowCount = new SqlCommand(
"SELECT COUNT(*) FROM " +
"dbo.BulkCopyDemoMatchingColumns;",
sourceConnection);
long countStart = System.Convert.ToInt32(
commandRowCount.ExecuteScalar());
Console.WriteLine("Starting row count = {0}", countStart);
// Get data from the source table as a SqlDataReader.
SqlCommand commandSourceData = new SqlCommand(
"SELECT ProductID, Name, " +
"ProductNumber " +
"FROM Production.Product;", sourceConnection);
SqlDataReader reader =
commandSourceData.ExecuteReader();
// Open the destination connection. In the real world you would
// not use SqlBulkCopy to move data from one table to the other
// in the same database. This is for demonstration purposes only.
using (SqlConnection destinationConnection =
new SqlConnection(connectionString))
{
destinationConnection.Open();
// Set up the bulk copy object.
// Note that the column positions in the source
// data reader match the column positions in
// the destination table so there is no need to
// map columns.
using (SqlBulkCopy bulkCopy =
new SqlBulkCopy(destinationConnection))
{
bulkCopy.DestinationTableName =
"dbo.BulkCopyDemoMatchingColumns";
try
{
// Write from the source to the destination.
bulkCopy.WriteToServer(reader);
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
finally
{
// Close the SqlDataReader. The SqlBulkCopy
// object is automatically closed at the end
// of the using block.
reader.Close();
}
}
// Perform a final count on the destination
// table to see how many rows were added.
long countEnd = System.Convert.ToInt32(
commandRowCount.ExecuteScalar());
Console.WriteLine("Ending row count = {0}", countEnd);
Console.WriteLine("{0} rows were added.", countEnd - countStart);
Console.WriteLine("Press Enter to finish.");
Console.ReadLine();
}
}
}
private static string GetConnectionString()
// To avoid storing the sourceConnection string in your code,
// you can retrieve it from a configuration file.
{
return "Data Source=(local); " +
" Integrated Security=true;" +
"Initial Catalog=AdventureWorks;";
}
}
Remarks
Because the connection is already open when the SqlBulkCopy instance is initialized, the connection remains open after the SqlBulkCopy instance is closed.
If the connection argument is null, an ArgumentNullException is thrown.
Applies to
SqlBulkCopy(String)
Initializes and opens a new instance of
SqlConnection
based on the supplied
connectionString
. The constructor uses the
SqlConnection
to initialize a new instance of the
SqlBulkCopy
class.
public:
SqlBulkCopy(System::String ^ connectionString);public SqlBulkCopy (string connectionString);new Microsoft.Data.SqlClient.SqlBulkCopy : string -> Microsoft.Data.SqlClient.SqlBulkCopyPublic Sub New (connectionString As String)Parameters
- connectionString
- String
The string defining the connection that will be opened for use by the
SqlBulkCopy
instance.
If your connection string does not use
Integrated Security = true
, you can use
SqlBulkCopy(SqlConnection)
or
SqlBulkCopy(SqlConnection, SqlBulkCopyOptions, SqlTransaction)
and
SqlCredential
to pass the user ID and password more securely than by specifying the user ID and password as text in the connection string.
Exceptions
If connectionString is an empty string, an
ArgumentException
is thrown.
Examples
The following console application demonstrates how to bulk load data by using a connection specified as a string. The connection is automatically closed when the SqlBulkCopy instance is closed. In this example, the source data is first read from a SQL Server table to a SqlDataReader instance. The source data does not have to be located on SQL Server; you can use any data source that can be read to an IDataReader or loaded to a DataTable.
Important
This sample will not run unless you have created the work tables as described in Bulk Copy Example Setup.
This code is provided to demonstrate the syntax for using SqlBulkCopy only. If the source and destination tables are in the same SQL Server instance,
it is easier and faster to use a Transact-SQL INSERT … SELECT statement to copy the data.
using Microsoft.Data.SqlClient;
class Program
{
static void Main()
{
string connectionString = GetConnectionString();
// Open a sourceConnection to the AdventureWorks database.
using (SqlConnection sourceConnection =
new SqlConnection(connectionString))
{
sourceConnection.Open();
// Perform an initial count on the destination table.
SqlCommand commandRowCount = new SqlCommand(
"SELECT COUNT(*) FROM " +
"dbo.BulkCopyDemoMatchingColumns;",
sourceConnection);
long countStart = System.Convert.ToInt32(
commandRowCount.ExecuteScalar());
Console.WriteLine("Starting row count = {0}", countStart);
// Get data from the source table as a SqlDataReader.
SqlCommand commandSourceData = new SqlCommand(
"SELECT ProductID, Name, " +
"ProductNumber " +
"FROM Production.Product;", sourceConnection);
SqlDataReader reader =
commandSourceData.ExecuteReader();
// Set up the bulk copy object using a connection string.
// In the real world you would not use SqlBulkCopy to move
// data from one table to the other in the same database.
using (SqlBulkCopy bulkCopy =
new SqlBulkCopy(connectionString))
{
bulkCopy.DestinationTableName =
"dbo.BulkCopyDemoMatchingColumns";
try
{
// Write from the source to the destination.
bulkCopy.WriteToServer(reader);
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
finally
{
// Close the SqlDataReader. The SqlBulkCopy
// object is automatically closed at the end
// of the using block.
reader.Close();
}
}
// Perform a final count on the destination
// table to see how many rows were added.
long countEnd = System.Convert.ToInt32(
commandRowCount.ExecuteScalar());
Console.WriteLine("Ending row count = {0}", countEnd);
Console.WriteLine("{0} rows were added.", countEnd - countStart);
Console.WriteLine("Press Enter to finish.");
Console.ReadLine();
}
}
private static string GetConnectionString()
// To avoid storing the sourceConnection string in your code,
// you can retrieve it from a configuration file.
{
return "Data Source=(local); " +
" Integrated Security=true;" +
"Initial Catalog=AdventureWorks;";
}
}
Remarks
The connection is automatically closed at the end of the bulk copy operation.
If connectionString is null, an ArgumentNullException is thrown. If connectionString is an empty string, an ArgumentException is thrown.
Applies to
SqlBulkCopy(String, SqlBulkCopyOptions)
Initializes and opens a new instance of
SqlConnection
based on the supplied
connectionString
. The constructor uses that
SqlConnection
to initialize a new instance of the
SqlBulkCopy
class. The
SqlConnection
instance behaves according to options supplied in the
copyOptions
parameter.
public:
SqlBulkCopy(System::String ^ connectionString, Microsoft::Data::SqlClient::SqlBulkCopyOptions copyOptions);public SqlBulkCopy (string connectionString, Microsoft.Data.SqlClient.SqlBulkCopyOptions copyOptions);new Microsoft.Data.SqlClient.SqlBulkCopy : string * Microsoft.Data.SqlClient.SqlBulkCopyOptions -> Microsoft.Data.SqlClient.SqlBulkCopyPublic Sub New (connectionString As String, copyOptions As SqlBulkCopyOptions)Parameters
- connectionString
- String
The string defining the connection that will be opened for use by the
SqlBulkCopy
instance. If your connection string does not use
Integrated Security = true
, you can use
SqlBulkCopy(SqlConnection)
or
SqlBulkCopy(SqlConnection, SqlBulkCopyOptions, SqlTransaction)
and
SqlCredential
to pass the user ID and password more securely than by specifying the user ID and password as text in the connection string.
- copyOptions
- SqlBulkCopyOptions
A combination of values from the SqlBulkCopyOptions enumeration that determines which data source rows are copied to the destination table.
Examples
The following console application demonstrates how to perform a bulk load by using a connection specified as a string. An option is set to use the value in the identity column of the source table when you load the destination table. In this example, the source data is first read from a SQL Server table to a SqlDataReader instance. The source table and destination table each include an Identity column. By default, a new value for the Identity column is generated in the destination table for each row added. In this example, an option is set when the connection is opened that forces the bulk load process to use the Identity values from the source table instead. To see how the option changes the way the bulk load works, run the sample with the dbo.BulkCopyDemoMatchingColumns table empty. All rows load from the source. Then run the sample again without emptying the table. An exception is thrown and the code writes a message to the console notifying you that rows weren't added because of primary key constraint violations.
Important
This sample will not run unless you have created the work tables as described in Bulk Copy Example Setup. This code is provided to
demonstrate the syntax for using SqlBulkCopy only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL INSERT … SELECT statement
to copy the data.
using Microsoft.Data.SqlClient;
class Program
{
static void Main()
{
string connectionString = GetConnectionString();
// Open a sourceConnection to the AdventureWorks database.
using (SqlConnection sourceConnection =
new SqlConnection(connectionString))
{
sourceConnection.Open();
// Perform an initial count on the destination table.
SqlCommand commandRowCount = new SqlCommand(
"SELECT COUNT(*) FROM " +
"dbo.BulkCopyDemoMatchingColumns;",
sourceConnection);
long countStart = System.Convert.ToInt32(
commandRowCount.ExecuteScalar());
Console.WriteLine("Starting row count = {0}", countStart);
// Get data from the source table as a SqlDataReader.
SqlCommand commandSourceData = new SqlCommand(
"SELECT ProductID, Name, " +
"ProductNumber " +
"FROM Production.Product;", sourceConnection);
SqlDataReader reader =
commandSourceData.ExecuteReader();
// Create the SqlBulkCopy object using a connection string
// and the KeepIdentity option.
// In the real world you would not use SqlBulkCopy to move
// data from one table to the other in the same database.
using (SqlBulkCopy bulkCopy =
new SqlBulkCopy(connectionString, SqlBulkCopyOptions.KeepIdentity))
{
bulkCopy.DestinationTableName =
"dbo.BulkCopyDemoMatchingColumns";
try
{
// Write from the source to the destination.
bulkCopy.WriteToServer(reader);
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
finally
{
// Close the SqlDataReader. The SqlBulkCopy
// object is automatically closed at the end
// of the using block.
reader.Close();
}
}
// Perform a final count on the destination
// table to see how many rows were added.
long countEnd = System.Convert.ToInt32(
commandRowCount.ExecuteScalar());
Console.WriteLine("Ending row count = {0}", countEnd);
Console.WriteLine("{0} rows were added.", countEnd - countStart);
Console.WriteLine("Press Enter to finish.");
Console.ReadLine();
}
}
private static string GetConnectionString()
// To avoid storing the sourceConnection string in your code,
// you can retrieve it from a configuration file.
{
return "Data Source=(local); " +
" Integrated Security=true;" +
"Initial Catalog=AdventureWorks;";
}
}
Remarks
You can obtain detailed information about all the bulk copy options in the SqlBulkCopyOptions topic.
Applies to
SqlBulkCopy(SqlConnection, SqlBulkCopyOptions, SqlTransaction)
Initializes a new instance of the
SqlBulkCopy
class using the supplied existing open instance of
SqlConnection
. The
SqlBulkCopy
instance behaves according to options supplied in the
copyOptions
parameter. If a non-null
SqlTransaction
is supplied, the copy operations will be performed within that transaction.
public:
SqlBulkCopy(Microsoft::Data::SqlClient::SqlConnection ^ connection, Microsoft::Data::SqlClient::SqlBulkCopyOptions copyOptions, Microsoft::Data::SqlClient::SqlTransaction ^ externalTransaction);public SqlBulkCopy (Microsoft.Data.SqlClient.SqlConnection connection, Microsoft.Data.SqlClient.SqlBulkCopyOptions copyOptions, Microsoft.Data.SqlClient.SqlTransaction externalTransaction);new Microsoft.Data.SqlClient.SqlBulkCopy : Microsoft.Data.SqlClient.SqlConnection * Microsoft.Data.SqlClient.SqlBulkCopyOptions * Microsoft.Data.SqlClient.SqlTransaction -> Microsoft.Data.SqlClient.SqlBulkCopyPublic Sub New (connection As SqlConnection, copyOptions As SqlBulkCopyOptions, externalTransaction As SqlTransaction)Parameters
- connection
- SqlConnection
The already open
SqlConnection
instance that will be used to perform the bulk copy. If your connection string does not use
Integrated Security = true
, you can use
SqlCredential
to pass the user ID and password more securely than by specifying the user ID and password as text in the connection string.
- copyOptions
- SqlBulkCopyOptions
A combination of values from the SqlBulkCopyOptions enumeration that determines which data source rows are copied to the destination table.
- externalTransaction
- SqlTransaction
An existing SqlTransaction instance under which the bulk copy will occur.
Remarks
If options include UseInternalTransaction and the externalTransaction argument is not null, an InvalidArgumentException is thrown.
For examples demonstrating how to use SqlBulkCopy in a transaction, see Transaction and Bulk Copy Operations.