Add transaction section

Author: karinazhou

docs/connect/ado-net/distributed-transactions.md

@@ -0,0 +1,62 @@
+---
+title: "Distributed transactions"
+description: Describes how to perform distributed transactions in ADO.NET.
+ms.date: "11/25/2020"
+ms.prod: sql
+ms.prod_service: connectivity
+ms.technology: connectivity
+ms.topic: conceptual
+author: karinazhou
+ms.author: v-jizho2
+ms.reviewer:
+---
+# Distributed transactions
+
+[!INCLUDE[appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
+
+[!INCLUDE[Driver_ADONET_Download](../../includes/driver_adonet_download.md)]
+
+A transaction is a set of related tasks that either succeeds (commit) or fails (abort) as a unit, among other things. A *distributed transaction* is a transaction that affects several resources. For a distributed transaction to commit, all participants must guarantee that any change to data will be permanent. Changes must persist despite system crashes or other unforeseen events. If even a single participant fails to make this guarantee, the entire transaction fails, and any changes to data within the scope of the transaction are rolled back. 
+
+> [!NOTE]
+> An exception will be thrown if you attempt to commit or roll back a transaction if a `DataReader` is started while the transaction is active.
+
+## Working with System.Transactions
+
+In the .NET Framework and .NET Core, distributed transactions are managed through the API in the <xref:System.Transactions> namespace. The <xref:System.Transactions> API will delegate distributed transaction handling to a transaction monitor such as the Microsoft Distributed Transaction Coordinator (MS DTC) when multiple persistent resource managers are involved. For more information, see [Transaction Fundamentals](/dotnet/framework/data/transactions/transaction-fundamentals).
+
+ADO.NET 2.0 introduced support for enlisting in a distributed transaction using the `EnlistTransaction` method, which enlists a connection in a <xref:System.Transactions.Transaction> instance. In previous versions of ADO.NET, explicit enlistment in distributed transactions was performed using the `EnlistDistributedTransaction` method of a connection to enlist a connection in a <xref:System.EnterpriseServices.ITransaction> instance, which is supported for backwards compatibility. For more information on Enterprise Services transactions, see [Interoperability with Enterprise Services and COM+ Transactions](/dotnet/framework/data/transactions/interoperability-with-enterprise-services-and-com-transactions.md).
+
+When using a <xref:System.Transactions> transaction with the **Microsoft SqlClient Data Provider for SQL Server** against a SQL Server database, a lightweight <xref:System.Transactions.Transaction> will automatically be used. The transaction can then be promoted to a full distributed transaction on an as-needed basis. For more information, see [System.Transactions integration with SQL Server](system-transactions-integration-with-sql-server.md).
+
+## Automatically enlisting in a distributed transaction
+
+Automatic enlistment is the default (and preferred) way of integrating ADO.NET connections with `System.Transactions`. A connection object will automatically enlist in an existing distributed transaction if it determines that a transaction is active, which, in `System.Transaction` terms, means that `Transaction.Current` is not null. Automatic transaction enlistment occurs when the connection is opened. It will not happen after that even if a command is executed inside of a transaction scope. You can disable auto-enlistment in existing transactions by specifying `Enlist=false` as a connection string parameter for a <xref:Microsoft.Data.SqlClient.SqlConnection.ConnectionString%2A?displayProperty=nameWithType>.
+
+## Manually enlisting in a distributed transaction
+
+If auto-enlistment is disabled or you need to enlist a transaction that was started after the connection was opened, you can enlist in an existing distributed transaction using the `EnlistTransaction` method of the <xref:Microsoft.Data.SqlClient.SqlConnection> object for the **Microsoft SqlClient Data Provider for SQL Server**. Enlisting in an existing distributed transaction ensures that, if the transaction is committed or rolled back, modifications made by the code at the data source will be committed or rolled back as well.
+
+Enlisting in distributed transactions is particularly applicable when pooling business objects. If a business object is pooled with an open connection, automatic transaction enlistment only occurs when that connection is opened. If multiple transactions are performed using the pooled business object, the open connection for that object will not automatically enlist in newly initiated transactions. In this case, you can disable automatic transaction enlistment for the connection and enlist the connection in transactions using `EnlistTransaction`.
+
+`EnlistTransaction` takes a single argument of type <xref:System.Transactions.Transaction> that is a reference to the existing transaction. After calling the connection's `EnlistTransaction` method, all modifications made at the data source using the connection are included in the transaction. Passing a null value unenlists the connection from its current distributed transaction enlistment. Note that the connection must be opened before calling `EnlistTransaction`.
+
+> [!NOTE]
+> Once a connection is explicitly enlisted on a transaction, it cannot be un-enlisted or enlisted in another transaction until the first transaction finishes.
+
+> [!CAUTION]
+> `EnlistTransaction` throws an exception if the connection has already begun a transaction using the connection's <xref:Microsoft.Data.SqlClient.SqlConnection.BeginTransaction%2A> method. However, if the transaction is a local transaction started at the data source (for example, executing the BEGIN TRANSACTION statement explicitly using a <xref:Microsoft.Data.SqlClient.SqlCommand>), `EnlistTransaction` will roll back the local transaction and enlist in the existing distributed transaction as requested. You will not receive notice that the local transaction was rolled back, and must manage any local transactions not started using <xref:Microsoft.Data.SqlClient.SqlConnection.BeginTransaction%2A>. If you are using the **Microsoft SqlClient Data Provider for SQL Server** with SQL Server, an attempt to enlist will throw an exception. All other cases will go undetected.  
+
+## Promotable transactions in SQL Server
+
+SQL Server supports promotable transactions in which a local lightweight transaction can be automatically promoted to a distributed transaction only if it is required. A promotable transaction does not invoke the added overhead of a distributed transaction unless the added overhead is required. For more information and a code sample, see [System.Transactions integration with SQL Server](system-transactions-integration-with-sql-server.md).
+
+## Configuring Distributed Transactions
+
+ You may need to enable the MS DTC over the network in order to use distributed transactions. If have the Windows Firewall enabled, you must allow the MS DTC service to use the network or open the MS DTC port.  
+  
+## See also
+
+- [Transactions and concurrency](transactions-and-concurrency.md)
+- [System.Transactions integration with SQL Server](system-transactions-integration-with-sql-server.md)
+- [ADO.NET Overview](/dotnet/framework/data/adonet/)

docs/connect/ado-net/local-transactions.md

@@ -0,0 +1,60 @@
+---
+title: "Local transactions"
+description: Demonstrates how to perform transactions against a database
+ms.date: "11/24/2020"
+ms.prod: sql
+ms.prod_service: connectivity
+ms.technology: connectivity
+ms.topic: conceptual
+author: karinazhou
+ms.author: v-jizho2
+ms.reviewer:
+---
+# Local transactions
+
+[!INCLUDE[appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
+
+[!INCLUDE[Driver_ADONET_Download](../../includes/driver_adonet_download.md)]
+
+Transactions in ADO.NET are used when you want to bind multiple tasks together so that they execute as a single unit of work. For example, imagine that an application performs two tasks. First, it updates a table with order information. Second, it updates a table that contains inventory information, debiting the items ordered. If either task fails, then both updates are rolled back.  
+
+## Determining the transaction type
+
+A transaction is considered to be a local transaction when it is a single-phase transaction and is handled by the database directly. A transaction is considered to be a distributed transaction when it is coordinated by a transaction monitor and uses fail-safe mechanisms (such as two-phase commit) for transaction resolution.
+
+The **Microsoft SqlClient Data Provider for SQL Server** has its own <xref:Microsoft.Data.SqlClient.SqlTransaction> object for performing local transactions in SQL Server databases. Other .NET data providers also provide their own `Transaction` objects. See <xref:System.Data.SqlClient> and <xref:System.Data.OracleClient> for more information. In addition, there is a <xref:System.Data.Common.DbTransaction> class that is available for writing provider-independent code that requires transactions.
+
+> [!NOTE]
+> Transactions are most efficient when they are performed on the server. If you are working with a SQL Server database that makes extensive use of explicit transactions, consider writing them as stored procedures using the Transact-SQL BEGIN TRANSACTION statement.
+
+## Performing a transaction using a single connection 
+
+In ADO.NET, you control transactions with the `Connection` object. You can initiate a local transaction with the `BeginTransaction` method. Once you have begun a transaction, you can enlist a command in that transaction with the `Transaction` property of a `Command` object. You can then commit or roll back modifications made at the data source based on the success or failure of the components of the transaction.
+
+> [!NOTE]
+> The `EnlistDistributedTransaction` method should not be used for a local transaction.
+
+The scope of the transaction is limited to the connection. The following example performs an explicit transaction that consists of two separate commands in the `try` block. The commands execute INSERT statements against the `Production.ScrapReason` table in the AdventureWorks SQL Server sample database, which are committed if no exceptions are thrown. The code in the `catch` block rolls back the transaction if an exception is thrown. If the transaction is aborted or the connection is closed before the transaction has completed, it is automatically rolled back.
+
+## Example  
+
+ Follow these steps to perform a transaction.
+
+1. Call the <xref:Microsoft.Data.SqlClient.SqlConnection.BeginTransaction%2A> method of the <xref:Microsoft.Data.SqlClient.SqlConnection> object to mark the start of the transaction. The <xref:Microsoft.Data.SqlClient.SqlConnection.BeginTransaction%2A> method returns a reference to the transaction. This reference is assigned to the <xref:Microsoft.Data.SqlClient.SqlCommand> objects that are enlisted in the transaction.
+
+2. Assign the `Transaction` object to the <xref:Microsoft.Data.SqlClient.SqlCommand.Transaction%2A> property of the <xref:Microsoft.Data.SqlClient.SqlCommand> to be executed. If a command is executed on a connection with an active transaction, and the `Transaction` object has not been assigned to the `Transaction` property of the `Command` object, an exception is thrown.
+
+3. Execute the required commands.
+
+4. Call the <xref:Microsoft.Data.SqlClient.SqlTransaction.Commit%2A> method of the <xref:Microsoft.Data.SqlClient.SqlTransaction> object to complete the transaction, or call the <xref:Microsoft.Data.SqlClient.SqlTransaction.Rollback%2A> method to end the transaction. If the connection is closed or disposed before either the <xref:Microsoft.Data.SqlClient.SqlTransaction.Commit%2A> or <xref:Microsoft.Data.SqlClient.SqlTransaction.Rollback%2A> methods have been executed, the transaction is rolled back.
+
+The following code example demonstrates transactional logic using **Microsoft SqlClient Data Provider for SQL Server**.
+
+[!code-csharp[SqlTransactionLocal#1](~/../sqlclient/doc/samples/SqlTransactionLocal.cs#1)]
+
+## See also
+
+- [Transactions and concurrency](transactions-and-concurrency.md)
+- [Distributed transactions](distributed-transactions.md)
+- [System.Transactions integration with SQL Server](system-transactions-integration-with-sql-server.md)
+- [ADO.NET Overview](/dotnet/framework/data/adonet/)