System.Data [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00] 1.0.3300.0 1.0.5000.0 2.0.0.0 Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details. System.Data.Common.DbConnection System.ICloneable System.ComponentModel.DefaultEvent("InfoMessage")

An object represents a unique connection to a data source. With a client/server database system, it is equivalent to a network connection to the server. Depending on the functionality supported by the native OLE DB provider, some methods or properties of an object may not be available.

When you create an instance of , all properties are set to their initial values. For a list of these values, see the constructor.

You can open more than one DataReader on a single . If the OLE DB provider you use does not support more than one DataReader on a single connection, the provider implicitly opens an additional connection for each.

If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling or Dispose, or by using the object within a Using statement.

To deploy high-performance applications, you must use connection pooling. When you use the .NET Framework Data Provider for OLE DB, you do not have to enable connection pooling because the provider manages this automatically. For more information about how to use connection pooling with the .NET Framework Data Provider for OLE DB, see Understanding Connection Pooling.

If a fatal (for example, a SQL Server severity level of 20 or greater) is generated by the method executing an , the might be closed. However, the user can reopen the connection and continue.

An application that creates an instance of the object can require all direct and indirect callers to have sufficient permission to the code by setting declarative or imperative security demands. makes security demands using the object. Users can verify that their code has sufficient permissions by using the object. Users and administrators can also use the Code Access Security Policy Tool (Caspol.exe) to modify security policy at the computer, user, and enterprise levels. For more information, see Code Access Security and ADO.NET.

For more information about handling warning and informational messages from the data server, see Working with Connection Events.

The object does not support setting or retrieving dynamic properties specific to an OLE DB provider. Only properties that can be passed in the connection string for the OLE DB provider are supported.

Represents an open connection to a data source.

- Constructor

  When a new instance of is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property.

  Properties

  Initial value

  empty string ("")

  15

  empty string ("")

  empty string ("")

  You can change the value for these properties only by using the property.

  Initializes a new instance of the class.

  1.0.5000.0
  2.0.0.0
- Constructor

  When a new instance of is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property.

  Properties

  Initial value

  15

  empty string ("")

  empty string ("")

  You can change the value for these properties only by using the property.

  Initializes a new instance of the class with the specified connection string.

  The connection used to open the database.
  1.0.5000.0
  2.0.0.0
- Method
  2.0.0.0
  System.Data.Common.DbTransaction `` To be added. To be added. To be added. To be added.
- Method
  System.Data.OleDb.OleDbTransaction

  You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for OLE DB transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source.

  Starts a database transaction with the current value.

  An object representing the new transaction.

  1.0.5000.0
  2.0.0.0
- Method
  System.Data.OleDb.OleDbTransaction ``

  You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for OLE DB transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source.

  If you do not specify an isolation level, the default isolation level for the underlying provider is used. To specify an isolation level with the method, use the overload that takes the parameter.

  Starts a database transaction with the specified isolation level.

  An object representing the new transaction.

  The isolation level under which the transaction should run. 1.0.5000.0 2.0.0.0
- Method
  System.Void ``

  The value supplied in the parameter must be a valid database name. The parameter cannot contain a null value, an empty string, or a string with only blank characters.

  Changes the current database for an open .

  The database name. 1.0.5000.0 2.0.0.0
- Method
  System.Void

  The method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. If is called while handling a event, no additional events are fired.

  An application can call more than one time. No exception is generated.

  Do not call or Dispose on an , an , or any other managed object in the Finalize method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a Finalize method in your class definition. For more information, see Garbage Collection.

  Closes the connection to the data source.

  1.0.5000.0
  2.0.0.0
- Property
  System.String To be added: an object of type 'string'

  The is designed to match OLE DB connection string format as closely as possible with the following exceptions:

  The "Provider = " clause is required. However, you cannot use "Provider = MSDASQL" because the .NET Framework Data Provider for OLE DB does not support the OLE DB Provider for ODBC (MSDASQL). To access ODBC data sources, use the object that is in the namespace.

  Unlike ODBC or ADO, the connection string that is returned is the same as the user-set , minus security information if Persist Security Info is set to false (default). The .NET Framework Data Provider for OLE DB does not persist or return the password in a connection string unless you set the Persist Security Info keyword to true (not recommended). To maintain a high level of security, it is strongly recommended that you use the Integrated Security keyword with Persist Security Info set to false.

  You can use the property to connect to a variety of data sources. The following example illustrates several possible connection strings.

  `"Provider=MSDAORA; Data Source=ORACLE8i7;Persist Security Info=False;Integrated Security=Yes" "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=c:\bin\LocalAccess40.mdb" "Provider=SQLOLEDB;Data Source=(local);Integrated Security=SSPI"`

  If the Data Source keyword is not specified in the connection string, the provider will try to connect to the local server if one is available.

  For more information about connection strings, see Using Connection String Keywords with SQL Server Native Client.

  The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the .

  Resetting the on a closed connection resets all connection string values and related properties. This includes the password. For example, if you set a connection string that includes "Initial Catalog= AdventureWorks", and then reset the connection string to "Provider= SQLOLEDB;Data Source= MySQLServer;IntegratedSecurity=SSPI", the property is no longer set to AdventureWorks. (The Initial Catalog value of the connection string corresponds to the Database property.)

  A preliminary validation of the connection string is performed when the property is set. If values for the Provider, Connect Timeout, Persist Security Info, or OLE DB Services are included in the string, these values are checked. When an application calls the method, the connection string is fully validated. If the connection string contains invalid or unsupported properties, a run-time exception, such as , is generated.

  It is possible to supply connection information for an in a Universal Data Link (UDL) file; however you should avoid doing so. UDL files are not encrypted and expose connection string information in clear text. Because a UDL file is an external file-based resource to your application, it cannot be secured using the .NET Framework.

  The basic format of a connection string includes a series of keyword/value pairs separated by semicolons. The equal sign (=) connects each keyword and its value. To include values that contain a semicolon, single-quote character, or double-quote character, the value must be enclosed in double quotation marks. If the value contains both a semicolon and a double-quote character, the value can be enclosed in single quotation marks. The single quotation mark is also useful if the value starts with a double-quote character. Conversely, the double quotation mark can be used if the value starts with a single quotation mark. If the value contains both single-quote and double-quote characters, the quotation-mark character used to enclose the value must be doubled every time it occurs within the value.

  To include preceding or trailing spaces in the string value, the value must be enclosed in either single quotation marks or double quotation marks. Any leading or trailing spaces around integer, Boolean, or enumerated values are ignored, even if enclosed in quotation marks. However, spaces within a string literal keyword or value are preserved. Single or double quotation marks may be used within a connection string without using delimiters (for example, Data Source= my'Server or Data Source= my"Server) unless a quotation-mark character is the first or last character in the value.

  To include an equal sign (=) in a keyword or value, it must be preceded by another equal sign. For example, in the hypothetical connection string

  `"key==word=value"`

  the keyword is "key=word" and the value is "value".

  If a specific keyword in a keyword=value pair occurs multiple times in a connection string, the last occurrence listed is used in the value set.

  Keywords are not case sensitive.

  You should use caution when constructing a connection string based on user input, for example, when retrieving user ID and password information from a dialog box and appending it to the connection string. The application should make sure that a user cannot embed additional connection-string parameters in these values, for example, entering a password as "validpassword;database= somedb" in an attempt to attach to a different database. If you use the Extended Properties connection string parameter for OLE DB connections, avoid passing user IDs and passwords because you should avoid storing user IDs and passwords in clear text if you can, and because the default setting of Persist Security Info= false does not affect the Extended Properties parameter.

  Gets or sets the string used to open a database.

  1.0.5000.0
  2.0.0.0
  System.ComponentModel.RefreshProperties(System.ComponentModel.RefreshProperties.All)
  System.ComponentModel.RecommendedAsConfigurable(true)
  System.ComponentModel.Editor("Microsoft.VSDesigner.Data.ADO.Design.OleDbConnectionStringEditor, Microsoft.VSDesigner, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.ComponentModel.DefaultValue("")
- Property
  System.Int32 To be added: an object of type 'int'

  A value of 0 indicates no limit, and should be avoided in a because an attempt to connect will wait indefinitely.

  Gets the time to wait while trying to establish a connection before terminating the attempt and generating an error.

  1.0.5000.0
  2.0.0.0
  System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)
- Method
  System.Data.OleDb.OleDbCommand To be added

  Creates and returns an object associated with the .

  An object.

  1.0.5000.0
  2.0.0.0
- Method
  2.0.0.0
  System.Data.Common.DbCommand To be added. To be added. To be added.
- Property
  System.String To be added: an object of type 'string'

  The property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically.

  Gets the name of the current database or the database to be used after a connection is opened.

  1.0.5000.0
  2.0.0.0
  System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)
- Property
  System.String To be added: an object of type 'string'

  If the connection to the database is closed, the DataSource property returns whatever is contained in ConnectionString for the data source keyword. If the connection is open and the ConnectionString data source keyword's value starts with "|datadirectory|", the property returns whatever is contained in ConnectionString for the data source keyword only. If the connection to the database is open, the property returns what the native provider returns for the DBPROP_INIT_DATASOURCE, and if that is empty, the native provider’s DBPROP_DATASOURCENAME is returned.

  Gets the server name or file name of the data source.

  1.0.5000.0
  2.0.0.0
  System.ComponentModel.Browsable(true)
- Method
  System.Void `` To be added: an object of type 'bool' To be added To be added 1.0.5000.0 2.0.0.0
- Method
  1.0.5000.0
  2.0.0.0
  System.Void ``

  New in ADO.NET 2.0 is support for using the method to enlist in a distributed transaction. Because it enlists a connection in a instance, EnlistTransaction takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to EnlistDistributedTransaction for this purpose. For more information, see Performing a Distributed Transaction.

  You can continue to enlist in an existing distributed transaction using the method if auto-enlistment is disabled. Enlisting in an existing distributed transaction makes sure that, if the transaction is committed or rolled back, modifications made by the code at the data source are also committed or rolled back. For more information about distributed transactions, see Performing a Distributed Transaction.

  returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), rolls back the local transaction and enlists in the existing distributed transaction as requested. You will not receive notice that the local transaction was rolled back, and are responsible for managing any local transactions not started using .

  Enlists in the specified transaction as a distributed transaction.

  A reference to an existing in which to enlist.
- Method
  2.0.0.0
  System.Void ``

  New in ADO.NET 2.0 is support for using the method to enlist in a distributed transaction. Because it enlists a connection in a instance, EnlistTransaction takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to EnlistDistributedTransaction, which uses a object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see Performing a Distributed Transaction.

  Enlists in the specified transaction as a distributed transaction.

  A reference to an existing in which to enlist.
- Method
  System.Data.DataTable `` ``

  The schema table is returned as a that has the same format as the OLE DB schema rowset specified by the parameter. Use the parameter to filter the rows to be returned in the (for example, by specifying restrictions for table name, type, owner, or schema). When you pass values in the array, include empty strings or nulls for array elements that do not contain values. If you pass an empty array to , all rows (one for each table) are returned in default order. Values in the array correspond to the order of the columns in the source table and . Each element in the restrictions array is compared with the content of the corresponding column in the schema rowset. For example, the first element in the restrictions array is compared to first column in the rowset. If a restriction element is not null, only rows from the schema rowset that exactly match the value of the restriction are added to the resulting .

  The method calls the underlying OLE DB IDBSchemaRowset::GetRowset method using standard common language runtime conversion rules. For more information, see COM Data Types.

  You can retrieve information about literals by using . This provides information equivalent to calling the OLE DB IDBInfo::GetLiteralInfo interface, or the ADO Connection.OpenSchema method with the adSchemaDBInfoLiterals constant.

  Returns schema information from a data source as indicated by a GUID, and after it applies the specified restrictions.

  A that contains the requested schema information.

  One of the values that specifies the schema table to return. An array of restriction values. These are applied in the order of the restriction columns. That is, the first restriction value applies to the first restriction column, the second restriction value applies to the second restriction column, and so on. 1.0.5000.0 2.0.0.0
- Method
  2.0.0.0
  System.Data.DataTable To be added.

  Returns schema information for the data source of this .

  A that contains schema information.

- Method
  2.0.0.0
  System.Data.DataTable ``

  When is specified as null, the will contain information about all the metadata that is available, and its restrictions.

  Returns schema information for the data source of this using the specified string for the schema name.

  A that contains schema information.

  Specifies the name of the schema to return.
- Method
  2.0.0.0
  System.Data.DataTable `` ``

  When is specified as null, the will contain information about all the metadata that is available, and its restrictions.

  The parameter can supply n depth of values which are specified by the restrictions collection for a specific collection. In order to set values on a given restriction, and not set the values of other restrictions, you need to set the preceding restrictions to null and then put the appropriate value in for the restriction that you would like to specify a value for.

  An example of this is the "Tables" collection. If the "Tables" collection has three restrictions (database, owner, and table name), and you want to get back only the tables associated with the owner "Carl," you must pass in the following values (at a minimum): null, "Carl". If a restriction value is not passed in, the default values are used for that restriction. This is the same mapping as passing in null, which is different from passing in an empty string for the parameter value. In that case, the empty string ("") is considered to be the value for the specified parameter.

  Returns schema information for the data source of this using the specified string for the schema name and the specified string array for the restriction values.

  A that contains schema information.

  Specifies the name of the schema to return. Specifies a set of restriction values for the requested schema.
- Event
  System.Data.OleDb.OleDbInfoMessageEventHandler

  Clients that want to process warnings or informational messages sent by the server should create an delegate to listen to this event.

  The event occurs when a message with low severity is returned from the data source. Low severity messages are those that do not cause an exception. For Microsoft SQL Server, this includes error messages that have a severity of 10 or less

  For more information and an example, see Working with Connection Events.

  Occurs when the provider sends a warning or an informational message.

  1.0.5000.0
  2.0.0.0
- Method
  System.Void

  The draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to the data source. You can open more than one DataReader on a single . If the OLEDB provider you use does not support more than one active DataReader on a single connection, the OLEDB provider implicitly opens an additional connection for each.

  If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling or Dispose, or using the connection within a Using statement.

  Opens a database connection with the property settings specified by the .

  1.0.5000.0
  2.0.0.0
- Property
  System.String To be added: an object of type 'string' To be added

  Gets the name of the OLE DB provider specified in the "Provider= " clause of the connection string.

  1.0.5000.0
  2.0.0.0
  System.ComponentModel.Browsable(true)
  System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)
- Method
  System.Void

  ReleaseObjectPool can be called to free resources that would otherwise be reserved for pooled objects. You might want to call this method if, for example, the connection object will not be used again for the amount of time that OLE DB services ordinarily keeps pooled connections active. Note that calling the method alone does not actually release the active connections that exist in the pool.

  The following must occur before the pool is finally disposed:

  Call to return the connection object to the pool.

  Allow each connection object to time out of the pool.

  Call .

  Invoke garbage collection.

  Conversely, if you call on all active connections, and invoke garbage collection, but do not call , the resources reserved for the pooled objects will remain available.

  Indicates that the object pool can be released when the last underlying connection is released.

  1.0.5000.0
  2.0.0.0
- Method
  2.0.0.0
  System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Advanced)
  System.Void

  Some OLE DB providers can check the current state of the connection. For example, if the database server has recycled since you opened your , the property will continue to return Open. If you are working with an OLE DB Provider that supports polling for this information on a live connection, calling the method and then checking the property will tell you that the connection is no longer open. The method relies on functionality in the OLE DB Provider to verify the current state of the connection. To determine if your OLE DB Provider supports this functionality, check the provider's documentation for information on DBPROP_CONNECTIONSTATUS.

  Updates the property of the object.

- Property
  System.String To be added: an object of type 'string'

  The property maps to the OLE DB DBPROP_DBMSVER property. If is not supported by the underlying OLE DB provider, an empty string is returned.

  The version is of the form ##.##.####, where the first two digits are the major version, the next two digits are the minor version, and the last four digits are the release version. The provider must render the product version in this form but can also append the product-specific version—for example, "04.01.0000 Rdb 4.1". The string is of the form major.minor.build, where major and minor are exactly two digits and build is exactly four digits.

  Gets a string that contains the version of the server to which the client is connected.

  1.0.5000.0
  2.0.0.0
- Property
  System.Data.ConnectionState To be added: an object of type 'Data.ConnectionState'

  The following are allowed state changes:

  From Closed to Open, using the method of the object.

  From Open to Closed, using either the method or the Dispose method of the object.

  In previous version of the .NET Framework, calling the property increased application overhead because each call caused a call to the OLE DB DBPROP_CONNECTIONSTATUS property for an open connection. With the release of the .NET Framework 2.0, this is no longer an issue.

  Gets the current state of the connection.

  1.0.5000.0
  2.0.0.0
  System.ComponentModel.Browsable(false)
  System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)
- Event
  System.Data.StateChangeEventHandler To be added To be added 1.0.5000.0 System.Data.DataSysDescription(Description="Event triggered when the connection changes state.")
- Method
  1.0.5000.0
  System.Data.IDbTransaction To be added. To be added. To be added.
- Method
  1.0.5000.0
  System.Data.IDbTransaction `` To be added. To be added. To be added. To be added.
- Method
  1.0.5000.0
  System.Data.IDbCommand To be added. To be added. To be added.
- Method
  1.0.5000.0
  2.0.0.0
  System.Object

  This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface.

  For a description of this member, see .

  A new that is a copy of this instance.