Connection Class
Connection.When the object is serialized out as xml, its qualified name is x:connection.
Inheritance Hierarchy
System.Object
DocumentFormat.OpenXml.OpenXmlElement
DocumentFormat.OpenXml.OpenXmlCompositeElement
DocumentFormat.OpenXml.Spreadsheet.Connection
Namespace: DocumentFormat.OpenXml.Spreadsheet
Assembly: DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)
Syntax
'Declaration
<ChildElementInfoAttribute(GetType(DatabaseProperties))> _
<ChildElementInfoAttribute(GetType(TextProperties))> _
<ChildElementInfoAttribute(GetType(Parameters))> _
<ChildElementInfoAttribute(GetType(OlapProperties))> _
<ChildElementInfoAttribute(GetType(WebQueryProperties))> _
<ChildElementInfoAttribute(GetType(ConnectionExtensionList))> _
Public Class Connection _
Inherits OpenXmlCompositeElement
'Usage
Dim instance As Connection
[ChildElementInfoAttribute(typeof(DatabaseProperties))]
[ChildElementInfoAttribute(typeof(TextProperties))]
[ChildElementInfoAttribute(typeof(Parameters))]
[ChildElementInfoAttribute(typeof(OlapProperties))]
[ChildElementInfoAttribute(typeof(WebQueryProperties))]
[ChildElementInfoAttribute(typeof(ConnectionExtensionList))]
public class Connection : OpenXmlCompositeElement
Remarks
The following table lists the possible child types:
DatabaseProperties <x:dbPr>
OlapProperties <x:olapPr>
WebQueryProperties <x:webPr>
TextProperties <x:textPr>
Parameters <x:parameters>
ConnectionExtensionList <x:extLst>
[ISO/IEC 29500-1 1st Edition]
18.13.1 connection (Connection)
This element contains both the definition of how to get at an external data source as well as information describing how the connection is used within the workbook. Specific constructs in a worksheet, such as OLAP formulas, QueryTables, or PivotTables make use of information in the connection to retrieve or refresh data based on default events or the user's explicit request.
Parent Elements |
|---|
connections (§18.13.2) |
Child Elements |
Subclause |
|---|---|
dbPr (Database Properties) |
§18.13.3 |
extLst (Future Feature Data Storage Area) |
§18.2.10 |
olapPr (OLAP Properties) |
§18.13.5 |
parameters (Query Parameters) |
§18.13.7 |
textPr (Text Import Settings) |
§18.13.12 |
webPr (Web Query Properties) |
§18.13.13 |
Attributes |
Description |
|---|---|
background (Background Refresh) |
Indicates whether the connection can be refreshed in the background (asynchronously). true if preferred usage of the connection is to refresh asynchronously in the background; false if preferred usage of the connection is to refresh synchronously in the foreground. This flag should be intentionally ignored in specific cases. [Example: An example of when the flag would be ignored is in the case of a connection to OLAP data on Microsoft SQL Server Analysis Services, where the connection is used by both a PivotTable and also by CUBE functions within the workbook. That connection will always be refreshed synchronously by the PivotTable and will always be refreshed asynchronously by the CUBE functions. end example] The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
credentials (Reconnection Method) |
Specifies the authentication method to be used when establishing (or re-establishing) the connection. The possible values for this attribute are defined by the ST_CredMethod simple type (§18.18.16). |
deleted (Deleted Connection) |
Indicates whether the associated workbook connection has been deleted. true if the connection has been deleted; otherwise, false. Deleted connections contain only the attributes name and deleted=true, all other information is removed from the SpreadsheetML file. If a new connection is created with the same name as a deleted connection, then the deleted connection is overwritten by the new connection. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
description (Connection Description) |
Specifies the user description for this connection. The possible values for this attribute are defined by the ST_Xstring simple type (§22.9.2.19). |
id (Connection Id) |
Specifies The unique identifier of this connection. The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype. |
interval (Automatic Refresh Interval) |
Specifies the number of minutes between automatic refreshes of the connection. When this attribute is not present, the connection is not automatically refreshed. The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype. |
keepAlive (Keep Connection Open) |
true when the spreadsheet application should make efforts to keep the connection open. When false, the application should close the connection after retrieving the information. This corresponds to the MaintainConnection property of a PivotCache object. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
minRefreshableVersion (Minimum Version Required for Refresh) |
For compatibility with legacy spreadsheet applications. This represents the minimum version # that is required to be able to correctly refresh the data connection. This attribute applies to connections that are used by a QueryTable. The possible values for this attribute are defined by the W3C XML Schema unsignedByte datatype. |
name (Connection Name) |
Specifies the name of the connection. Each connection shall have a unique name. When a connection has been marked as deleted and then a new connection is added with the same name, the deleted connection is replaced with the new connection. The possible values for this attribute are defined by the ST_Xstring simple type (§22.9.2.19). |
new (New Connection) |
true if the connection has not been refreshed for the first time; otherwise, false. This state can happen when the user saves the file before a query has finished returning. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
odcFile (Connection File) |
Specifies the full path to external connection file from which this connection was created. If a connection fails during an attempt to refresh data, and reconnectionMethod=1, then the spreadsheet application will try again using information from the external connection file instead of the connection object embedded within the workbook. This is a benefit for data source and spreadsheetML document manageability. If the definition in the external connection file is changed (e.g., because of a database server name change), then the workbooks that made use of that connection will fail to connect with their internal connection information, and reload the new connection information from this file. This attribute is cleared by the spreadsheet application when the user manually edits the connection definition within the workbook. Can be expressed in URI or system-specific file path notation. [Note: Applications can decide what forms of URI they support, and whether system-specific file path notations are supported. end note] The possible values for this attribute are defined by the ST_Xstring simple type (§22.9.2.19). |
onlyUseConnectionFile (Only Use Connection File) |
Indicates whether the spreadsheet application should always and only use the connection information in the external connection file indicated by the odcFile attribute when the connection is refreshed. If false, then the spreadsheet application should follow the procedure indicated by the reconnectionMethod attribute described below. Applies only to OLE DB and ODBC connections, this attribute is ignored for other types of connections. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
reconnectionMethod (Reconnection Method) |
Specifies what the spreadsheet application should do when a connection fails. The values are as follows: 1 = As required: On refresh use the existing connection information. If the existing information cannot be used to establish a connection, get updated connection information, if available from the external connection file. 2 = Always: On every refresh get updated connection information from the external connection file, if available, and use that instead of the existing connection information. In this case the data refresh will fail if the external connection file is unavailable. 3 = Never: Never get updated connection information from the external connection file even if it is available and even if the existing connection information cannot be used. The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype. |
refreshedVersion (Last Refresh Version) |
For backward compatibility purposes, this attribute indicates the version of the spreadsheet application that last refreshed the connection. This attribute applies to connections that are used by a query table. The possible values for this attribute are defined by the W3C XML Schema unsignedByte datatype. |
refreshOnLoad (Refresh on Open) |
true if this connection should be refreshed when opening the file; otherwise, false. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
saveData (Save Data) |
true if the external data fetched over the connection to populate a table is to be saved with the workbook; otherwise, false. This exists for data security purposes - if no external data is saved in (or "cached") in the workbook, then current user credentials can be required every time to retrieve the relevant data, and people won't see the data the workbook author had last been using before saving the file. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
savePassword (Save Password) |
true if the password is to be saved as part of the connection string; otherwise, False. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
singleSignOnId (SSO Id) |
Identifier for Single Sign On (SSO) used for authentication between an intermediate spreadsheetML server and the external data source. [Note: Data connectivity can use a number of different technologies. One example of potential values stored in this attribute can be found at: https://msdn.microsoft.com/library/default.asp?url=/library/en-us/spptsdk/html/cSSOReturnCodes_SV01001109.asp end note] The possible values for this attribute are defined by the ST_Xstring simple type (§22.9.2.19). |
sourceFile (Source Database File) |
Used when the external data source is file-based. When a connection to such a data source fails, the spreadsheet application attempts to connect directly to this file. Can be expressed in URI or system-specific file path notation. [Note: Applications can decide what forms of URI they support, and whether system-specific file path notations are supported. end note] The possible values for this attribute are defined by the ST_Xstring simple type (§22.9.2.19). |
type (Database Source Type) |
Specifies the data source type. Values are as follows: 1. ODBC-based source 2. DAO-based source 3. File based database source 4. Web query 5. OLE DB-based source 6. Text-based source 7. ADO record set 8. DSP The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype. |
[Note: The W3C XML Schema definition of this element’s content model (CT_Connection) is located in §A.2. end note]
© ISO/IEC29500: 2008.
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.