SqlConnection Clase

Definición

Representa una conexión a una base de datos de SQL Server.Represents a connection to a SQL Server database. Esta clase no puede heredarse.This class cannot be inherited.

public ref class SqlConnection sealed : System::Data::Common::DbConnection, ICloneable, IDisposable
public sealed class SqlConnection : System.Data.Common.DbConnection, ICloneable, IDisposable
type SqlConnection = class
    inherit DbConnection
    interface IDbConnection
    interface ICloneable
    interface IDisposable
Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable, IDisposable
Herencia
Implementaciones

Ejemplos

En el ejemplo siguiente se crea un SqlCommand y un SqlConnection.The following example creates a SqlCommand and a SqlConnection. El SqlConnection se abre y se establece como Connection para el SqlCommand.The SqlConnection is opened and set as the Connection for the SqlCommand. A continuación, en el ejemplo se llama a ExecuteNonQuery.The example then calls ExecuteNonQuery. Para ello, se pasa al ExecuteNonQuery una cadena de conexión y una cadena de consulta que es Transact-SQLTransact-SQL instrucción INSERT.To accomplish this, the ExecuteNonQuery is passed a connection string and a query string that is a Transact-SQLTransact-SQL INSERT statement. La conexión se cierra automáticamente cuando el código sale del bloque using.The connection is closed automatically when the code exits the using block.

private static void CreateCommand(string queryString,
    string connectionString)
{
    using (SqlConnection connection = new SqlConnection(
               connectionString))
    {
        SqlCommand command = new SqlCommand(queryString, connection);
        command.Connection.Open();
        command.ExecuteNonQuery();
    }
}
Public Sub CreateCommand(ByVal queryString As String, _
  ByVal connectionString As String)
    Using connection As New SqlConnection(connectionString)
        Dim command As New SqlCommand(queryString, connection)
        command.Connection.Open()
        command.ExecuteNonQuery()
    End Using
End Sub

Comentarios

Un objeto SqlConnection representa una sesión única para un origen de datos de SQL Server.A SqlConnection object represents a unique session to a SQL Server data source. Con un sistema de base de datos cliente/servidor, es equivalente a una conexión de red al servidor.With a client/server database system, it is equivalent to a network connection to the server. SqlConnection se utiliza junto con SqlDataAdapter y SqlCommand para aumentar el rendimiento al conectarse a una base de datos de Microsoft SQL Server.SqlConnection is used together with SqlDataAdapter and SqlCommand to increase performance when connecting to a Microsoft SQL Server database. Para todos los productos de SQL Server de terceros y otros orígenes de datos compatibles con OLE DB, utilice OleDbConnection.For all third-party SQL Server products and other OLE DB-supported data sources, use OleDbConnection.

Cuando se crea una instancia de SqlConnection, todas las propiedades se establecen en sus valores iniciales.When you create an instance of SqlConnection, all properties are set to their initial values. Para obtener una lista de estos valores, vea el constructor SqlConnection.For a list of these values, see the SqlConnection constructor.

Consulte ConnectionString para obtener una lista de las palabras clave en una cadena de conexión.See ConnectionString for a list of the keywords in a connection string.

Si el SqlConnection sale del ámbito, no se cerrará.If the SqlConnection goes out of scope, it won't be closed. Por lo tanto, debe cerrar explícitamente la conexión llamando a Close o Dispose.Therefore, you must explicitly close the connection by calling Close or Dispose. Close y Dispose son funcionalmente equivalentes.Close and Dispose are functionally equivalent. Si el valor Pooling de la agrupación de conexiones se establece en true o yes, la conexión subyacente se devuelve al grupo de conexiones.If the connection pooling value Pooling is set to true or yes, the underlying connection is returned back to the connection pool. Por otro lado, si Pooling se establece en false o no, la conexión subyacente al servidor se cierra realmente.On the other hand, if Pooling is set to false or no, the underlying connection to the server is actually closed.

Nota

Los eventos de inicio y cierre de sesión no se provocarán en el servidor cuando se busque una conexión desde el grupo de conexiones o se devuelva a éste, puesto que la conexión no está cerrada realmente cuando se devuelve al grupo de conexiones.Login and logout events will not be raised on the server when a connection is fetched from or returned to the connection pool, because the connection is not actually closed when it is returned to the connection pool. Para obtener más información, vea Agrupación de conexiones de SQL Server (ADO.NET).For more information, see SQL Server Connection Pooling (ADO.NET).

Para asegurarse de que las conexiones están siempre cerradas, abra la conexión dentro de un bloque using, como se muestra en el siguiente fragmento de código.To ensure that connections are always closed, open the connection inside of a using block, as shown in the following code fragment. Esto garantiza que la conexión se cierra automáticamente cuando el código sale del bloque.Doing so ensures that the connection is automatically closed when the code exits the block.

Using connection As New SqlConnection(connectionString)  
    connection.Open()  
    ' Do work here; connection closed on following line.  
End Using  
  
using (SqlConnection connection = new SqlConnection(connectionString))  
    {  
        connection.Open();  
        // Do work here; connection closed on following line.  
    }  

Nota

Para implementar aplicaciones de alto rendimiento, debe usar la agrupación de conexiones.To deploy high-performance applications, you must use connection pooling. Cuando se usa el proveedor de datos de .NET Framework para SQL Server, no es necesario habilitar la agrupación de conexiones porque el proveedor la administra automáticamente, aunque puede modificar algunos valores de configuración.When you use the .NET Framework Data Provider for SQL Server, you do not have to enable connection pooling because the provider manages this automatically, although you can modify some settings. Para obtener más información, vea Agrupación de conexiones de SQL Server (ADO.NET).For more information, see SQL Server Connection Pooling (ADO.NET).

Si un SqlException se genera mediante el método que ejecuta una SqlCommand, el SqlConnection permanece abierto cuando el nivel de gravedad es 19 o menos.If a SqlException is generated by the method executing a SqlCommand, the SqlConnection remains open when the severity level is 19 or less. Cuando el nivel de gravedad es 20 o superior, el servidor cierra normalmente el SqlConnection.When the severity level is 20 or greater, the server ordinarily closes the SqlConnection. Sin embargo, el usuario puede volver a abrir la conexión y continuar.However, the user can reopen the connection and continue.

Una aplicación que crea una instancia del objeto SqlConnection puede requerir que todos los llamadores directos e indirectos tengan permisos suficientes para el código estableciendo demandas de seguridad declarativas o imperativas.An application that creates an instance of the SqlConnection object can require all direct and indirect callers to have sufficient permission to the code by setting declarative or imperative security demands. SqlConnection realiza peticiones de seguridad mediante el objeto SqlClientPermission.SqlConnection makes security demands using the SqlClientPermission object. Los usuarios pueden comprobar que el código tiene los permisos necesarios mediante el SqlClientPermissionAttribute objeto.Users can verify that their code has sufficient permissions by using the SqlClientPermissionAttribute object. Los usuarios y los administradores también pueden usar la herramienta Caspol. exe (herramienta de la Directiva de seguridad de acceso del código) para modificar la Directiva de seguridad en los niveles de equipo, usuario y empresa.Users and administrators can also use the Caspol.exe (Code Access Security Policy Tool) to modify security policy at the machine, user, and enterprise levels. Para obtener más información, vea Seguridad en .NET.For more information, see Security in .NET. Para ver un ejemplo en el que se muestra cómo usar las demandas de seguridad, vea seguridad de acceso del código y ADO.net.For an example demonstrating how to use security demands, see Code Access Security and ADO.NET.

Para obtener más información sobre el control de mensajes de advertencia e informativos del servidor, vea eventos de conexión.For more information about handling warning and informational messages from the server, see Connection Events. Para obtener más información sobre los errores y los mensajes de error del motor de SQL Server, vea motor de base de datos eventos y errores.For more information about SQL Server engine errors and error messages, see Database Engine Events and Errors.

Precaución

Puede forzar el uso de TCP en lugar de la memoria compartida.You can force TCP instead of shared memory. Puede hacerlo si antepone TCP: al nombre del servidor en la cadena de conexión o si puede usar localhost.You can do that by prefixing tcp: to the server name in the connection string or you can use localhost.

Constructores

SqlConnection()

Inicializa una nueva instancia de la clase SqlConnection.Initializes a new instance of the SqlConnection class.

SqlConnection(String)

Inicializa una nueva instancia de la clase SqlConnection, dada una cadena que contiene la cadena de conexión.Initializes a new instance of the SqlConnection class when given a string that contains the connection string.

SqlConnection(String, SqlCredential)

Inicializa una nueva instancia de la clase SqlConnection a la que se proporciona una cadena de conexión que no usa Integrated Security = true y un objeto SqlCredential que contiene el identificador de usuario y la contraseña.Initializes a new instance of the SqlConnection class given a connection string, that does not use Integrated Security = true and a SqlCredential object that contains the user ID and password.

Propiedades

AccessToken

Obtiene o establece el token de acceso para la conexión.Gets or sets the access token for the connection.

CanRaiseEvents

Obtiene un valor que indica si el componente puede generar un evento.Gets a value indicating whether the component can raise an event.

(Heredado de Component)
ClientConnectionId

Identificador de conexión del intento de conexión más reciente, independientemente de si el intento se realizó correctamente o no.The connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.

ColumnEncryptionKeyCacheTtl

Obtiene o establece el período de vida para entradas de clave de cifrado de columnas en la memoria caché de clave de cifrado de columnas para la características Always Encrypted.Gets or sets the time-to-live for column encryption key entries in the column encryption key cache for the Always Encrypted feature. El valor predeterminado es 2 horas.The default value is 2 hours. 0 significa que no hay almacenamiento en caché en absoluto.0 means no caching at all.

ColumnEncryptionQueryMetadataCacheEnabled

Obtiene o establece un valor que indica si el almacenamiento en caché de metadatos de consulta está habilitado (true) o no (false) para consultas parametrizadas que se ejecutan en bases con la función Always Encrypted.Gets or sets a value that indicates whether query metadata caching is enabled (true) or not (false) for parameterized queries running against Always Encrypted enabled databases. El valor predeterminado es true.The default value is true.

ColumnEncryptionTrustedMasterKeyPaths

Le permite establecer una lista de rutas de acceso a clave de confianza para un servidor de base de datos.Allows you to set a list of trusted key paths for a database server. Si durante el procesamiento de una consulta de aplicación, el controlador recibe una ruta de acceso de clave que no se encuentre en la lista, la consulta generará error.If while processing an application query the driver receives a key path that is not on the list, the query will fail. Esta propiedad ofrece protección adicional contra los ataques de seguridad que implican un SQL que está en peligro al ofrecer rutas de acceso de clave falsas, lo que puede provocar la pérdida de las credenciales del almacén de claves.This property provides additional protection against security attacks that involve a compromised SQL Server providing fake key paths, which may lead to leaking key store credentials.

ConnectionString

Obtiene o establece la cadena que se utiliza para abrir una base de datos de SQL Server.Gets or sets the string used to open a SQL Server database.

ConnectionTimeout

Obtiene el tiempo de espera (en segundos) mientras se intenta establecer una conexión antes de que se interrumpa el intento y se genere un error.Gets the time to wait (in seconds) while trying to establish a connection before terminating the attempt and generating an error.

Container

Obtiene IContainer que contiene Component.Gets the IContainer that contains the Component.

(Heredado de Component)
Credential

Obtiene o establece el objeto SqlCredential para esta conexión.Gets or sets the SqlCredential object for this connection.

Credentials
Database

Obtiene el nombre de la base de datos actual o de la que se va a utilizar una vez que se abre la conexión.Gets the name of the current database or the database to be used after a connection is opened.

DataSource

Obtiene el nombre de la instancia de SQL Server con la que se va a establecer la conexión.Gets the name of the instance of SQL Server to which to connect.

DesignMode

Obtiene un valor que indica si Component está actualmente en modo de diseño.Gets a value that indicates whether the Component is currently in design mode.

(Heredado de Component)
Events

Obtiene la lista de controladores de eventos asociados a Component.Gets the list of event handlers that are attached to this Component.

(Heredado de Component)
FireInfoMessageEventOnUserErrors

Obtiene o establece la propiedad FireInfoMessageEventOnUserErrors.Gets or sets the FireInfoMessageEventOnUserErrors property.

PacketSize

Obtiene el tamaño en bytes de los paquetes de red utilizados para establecer comunicación con una instancia de SQL Server.Gets the size (in bytes) of network packets used to communicate with an instance of SQL Server.

ServerVersion

Obtiene una cadena que contiene la versión de la instancia de SQL Server a la que se conecta el cliente.Gets a string that contains the version of the instance of SQL Server to which the client is connected.

Site

Obtiene o establece el ISite de Component.Gets or sets the ISite of the Component.

(Heredado de Component)
State

Indica el estado de SqlConnection durante la operación más reciente de la red realizada en la conexión.Indicates the state of the SqlConnection during the most recent network operation performed on the connection.

StatisticsEnabled

Cuando se establece en true, permite la obtención de estadísticas para la conexión actual.When set to true, enables statistics gathering for the current connection.

WorkstationId

Obtiene una cadena que identifica el cliente de bases de datos.Gets a string that identifies the database client.

Métodos

BeginTransaction()

Inicia una transacción de base de datos.Starts a database transaction.

BeginTransaction(IsolationLevel)

Inicia una transacción de base de datos con el nivel de aislamiento especificado.Starts a database transaction with the specified isolation level.

BeginTransaction(IsolationLevel, String)

Inicia una transacción de la base de datos con el nivel de aislamiento y el nombre de transacción especificados.Starts a database transaction with the specified isolation level and transaction name.

BeginTransaction(String)

Inicia una transacción de base de datos con el nombre de transacción especificado.Starts a database transaction with the specified transaction name.

ChangeDatabase(String)

Cambia la base de datos actual de una conexión SqlConnection abierta.Changes the current database for an open SqlConnection.

ChangePassword(String, SqlCredential, SecureString)

Cambia la contraseña de SQL Server para el usuario indicado en el objeto de SqlCredential.Changes the SQL Server password for the user indicated in the SqlCredential object.

ChangePassword(String, String)

Cambia la contraseña de SQL Server para el usuario indicado en la cadena de conexión a la nueva contraseña proporcionada.Changes the SQL Server password for the user indicated in the connection string to the supplied new password.

ClearAllPools()

Vacía la agrupación de conexiones.Empties the connection pool.

ClearPool(SqlConnection)

Vacía la agrupación de conexiones asociada a la conexión especificada.Empties the connection pool associated with the specified connection.

Close()

Cierra la conexión con la base de datos.Closes the connection to the database. Es el método preferido para cerrar cualquier conexión abierta.This is the preferred method of closing any open connection.

CreateCommand()

Crea y devuelve un objeto SqlCommand asociado a la conexión SqlConnection.Creates and returns a SqlCommand object associated with the SqlConnection.

CreateObjRef(Type)

Crea un objeto que contiene toda la información relevante necesaria para generar un proxy utilizado para comunicarse con un objeto remoto.Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.

(Heredado de MarshalByRefObject)
Dispose()

Libera todos los recursos que usa Component.Releases all resources used by the Component.

(Heredado de Component)
Dispose(Boolean)

Libera los recursos no administrados que usa Component y, de forma opcional, libera los recursos administrados.Releases the unmanaged resources used by the Component and optionally releases the managed resources.

(Heredado de Component)
EnlistDistributedTransaction(ITransaction)

Se da de alta en la transacción especificada como una transacción distribuida.Enlists in the specified transaction as a distributed transaction.

EnlistTransaction(Transaction)

Se da de alta en la transacción especificada como una transacción distribuida.Enlists in the specified transaction as a distributed transaction.

Equals(Object)

Determina si el objeto especificado es igual al objeto actual.Determines whether the specified object is equal to the current object.

(Heredado de Object)
GetHashCode()

Sirve como función hash predeterminada.Serves as the default hash function.

(Heredado de Object)
GetLifetimeService()

Recupera el objeto de servicio de duración actual que controla la directiva de duración de esta instancia.Retrieves the current lifetime service object that controls the lifetime policy for this instance.

(Heredado de MarshalByRefObject)
GetSchema()

Devuelve información de esquema para el origen de datos de SqlConnection.Returns schema information for the data source of this SqlConnection. Para obtener más información sobre el esquema, vea Colecciones de esquemas de SQL Server.For more information about scheme, see SQL Server Schema Collections.

GetSchema(String)

Devuelve información de esquema para el origen de datos de SqlConnection utilizando la cadena especificada para el nombre del esquema.Returns schema information for the data source of this SqlConnection using the specified string for the schema name.

GetSchema(String, String[])

Devuelve información de esquema para el origen de datos de SqlConnection utilizando la cadena especificada para el nombre del esquema y la matriz de cadena determinada para los valores de restricción.Returns schema information for the data source of this SqlConnection using the specified string for the schema name and the specified string array for the restriction values.

GetService(Type)

Devuelve un objeto que representa el servicio suministrado por Component o por Container.Returns an object that represents a service provided by the Component or by its Container.

(Heredado de Component)
GetType()

Obtiene el Type de la instancia actual.Gets the Type of the current instance.

(Heredado de Object)
InitializeLifetimeService()

Obtiene un objeto de servicio de duración para controlar la directiva de duración de esta instancia.Obtains a lifetime service object to control the lifetime policy for this instance.

(Heredado de MarshalByRefObject)
MemberwiseClone()

Crea una copia superficial del Object actual.Creates a shallow copy of the current Object.

(Heredado de Object)
MemberwiseClone(Boolean)

Crea una copia superficial del objeto MarshalByRefObject actual.Creates a shallow copy of the current MarshalByRefObject object.

(Heredado de MarshalByRefObject)
Open()

Abre una conexión de base de datos con los valores de propiedad que especifica ConnectionString.Opens a database connection with the property settings specified by the ConnectionString.

OpenAsync(CancellationToken)

Una versión asincrónica de Open(), que abre una conexión a bases de datos con los valores de propiedad especificados por ConnectionString.An asynchronous version of Open(), which opens a database connection with the property settings specified by the ConnectionString. Token de cancelación que se puede usar para solicitar que se abandone la operación antes de que transcurra el tiempo de espera de la conexión.The cancellation token can be used to request that the operation be abandoned before the connection timeout elapses. Las excepciones se propagarán mediante la tarea devuelta.Exceptions will be propagated via the returned Task. Si el tiempo de espera de conexión transcurre sin conectar correctamente, la tarea devuelta se marcará como error con una excepción.If the connection timeout time elapses without successfully connecting, the returned Task will be marked as faulted with an Exception. La implementación devuelve una tarea sin bloquear el subproceso de llamada para las conexiones agrupadas y no agrupadas.The implementation returns a Task without blocking the calling thread for both pooled and non-pooled connections.

RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)

Registra los proveedores de almacenamiento de claves de cifrado de columnas.Registers the column encryption key store providers.

ResetStatistics()

Si se habilita la obtención de estadísticas, todos los valores se restablecen en cero.If statistics gathering is enabled, all values are reset to zero.

RetrieveStatistics()

Devuelve una colección de pares de nombre y valor de las estadísticas cuando se llama el método.Returns a name value pair collection of statistics at the point in time the method is called.

ToString()

Devuelve una String que contiene el nombre del Component, si existe.Returns a String containing the name of the Component, if any. Este método no se debe invalidar.This method should not be overridden.

(Heredado de Component)

Eventos

Disposed

Se produce cuando el componente se elimina mediante una llamada al método Dispose().Occurs when the component is disposed by a call to the Dispose() method.

(Heredado de Component)
InfoMessage

Se produce cuando SQL Server devuelve un mensaje informativo o de advertencia.Occurs when SQL Server returns a warning or informational message.

StateChange

Se produce cuando cambia el estado de la conexión.Occurs when the state of the connection changes.

Implementaciones de interfaz explícitas

ICloneable.Clone()

Crea un nuevo objeto copiado de la instancia actual.Creates a new object that is a copy of the current instance.

IDbConnection.BeginTransaction()

Inicia una transacción de base de datos.Begins a database transaction.

IDbConnection.BeginTransaction(IsolationLevel)

Inicia una transacción de base de datos con el valor de IsolationLevel especificado.Begins a database transaction with the specified IsolationLevel value.

IDbConnection.CreateCommand()

Crea y devuelve un objeto Command asociado a la conexión.Creates and returns a Command object that is associated with the connection.

Se aplica a

Consulte también: