AdomdConnection.ConnectionString Property

Gets or sets the string that the AdomdConnection uses to open an analytical data source.

Namespace: Microsoft.AnalysisServices.AdomdClient
Assembly: Microsoft.AnalysisServices.AdomdClient (in microsoft.analysisservices.adomdclient.dll)

Syntax

'Declaration
Public Property ConnectionString As String

public string ConnectionString { get; set; }

public:
virtual property String^ ConnectionString {
    String^ get () sealed;
    void set (String^ value) sealed;
}

/** @property */
public final String get_ConnectionString ()

/** @property */
public final void set_ConnectionString (String value)

public final function get ConnectionString () : String

public final function set ConnectionString (value : String)

Property Value

A string that contains the connection string that is used by the AdomdConnection.

Remarks

The ConnectionString property matches the OLE DB connection string format as closely as possible. You can use the ConnectionString property to connect to an analytical data source that supports the XML for Analysis 1.1 specification.

Many of the connection string values have corresponding read-only properties. When you set the connection string, all of these properties are updated, except when an error is detected. Detection of an error prevents all properties from being updated.

Resetting the ConnectionString property on a closed connection resets all connection string values (and related properties), including the password. For example, you set a connection string that includes Catalog= Adventure Works DW. You then reset the connection string to DataSource=localhost;Password=MyPassword. The Database property is now no longer set to the Adventure Works DW database. (The Catalog setting of the connection string corresponds to the Database property.)

A preliminary validation of the connection string is performed when the property is set. When an application calls the Open method, the connection string is parsed and individual properties are evaluated based on their level of support. If the AdomdConnection directly supports a property provided in the connection string, the value for that property is validated. If the value is not valid or is unsupported, an exception is thrown. If the property is not directly supported by the AdomdConnection, but the property can be used to construct a valid XML element, the property and its value are passed directly to the underlying provider. If such a property contains a value that is not valid or is unsupported, an exception is thrown at that time.

Values can be delimited by single or double quotes (for example, name='value' or name="value"). Either single or double quotes may be used within a connection string by using the other delimiter (for example, name="value's" or name= 'value"s', but not name='value's' or name= ""value""). All blank characters are ignored, except those placed within a value or within quotes. Keyword value pairs must be separated by a semicolon (;). If a semicolon is part of a value, it also must be delimited by quotes. No escape sequences are supported. The value type is irrelevant. Names are not case sensitive. If a property name occurs more than once in the connection string, the value associated with the last occurrence is used.

Note

Applications 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 this information to the connection string). The application should ensure that a user cannot embed extra connection string parameters in these values (for example, a user that is trying to connect to a different database might enter a password as validpassword;database=somedb).

The following table describes the connection string settings directly supported by the AdomdConnection. Provider-specific connection strings settings may also be set, but are not listed here.

Setting name

Setting aliases

Description

Timeout

None

Sets the time to wait for a command to run before the AdomdConnection stops trying to run the command and generates an error.

Connect Timeout

None

Sets the time to wait for a connection to be established before the AdomdConnection stops trying to connect and generates an error.

Data Source

DataSourceLocation

Sets the instance or local cube (.cub) file to which the AdomdConnection establishes a connection.

UserName

Authenticated User

UID

User ID

Sets the user ID or name that the AdomdConnection uses to establish a connection.

Note:

Authenticated User is no longer supported.

Password

PWD

Sets the password that the AdomdConnection uses to establish a connection with the specified user name.

Catalog

Initial Catalog

Database

Sets the database to which the AdomdConnection establishes a connection.

ProtectionLevel

None

Sets the level of protection that the provider uses to sign or encrypt the connection. This setting has the following options:

• NONE   Performs no authentication of data sent to the server

• CONNECT   Authenticates only when the client establishes the connection with the server.

• PKT INTEGRITY   Authenticates that all data received is from the client and that it has not been changed in transit.

• PKT PRIVACY   Encrypts the data and authenticates that the data is received from the client and that it has not been changed in transit.

Safety Options

None

Sets the safety level that determines how security for user-defined functions and actions is handled.

AutoSyncPeriod

None

Sets the time, in milliseconds, that elapses before objects automatically synchronize with the server.

ConnectTo

None

Sets the method that the AdomdConnection uses used to connect to the server. If set to 8.0, the connection uses in-process XML for Analysis to connect to the server. If set to 9.0, the connection uses XML for Analysis. If set to Default, the connection first tries XML for Analysis, and then tries to use in-process XML for Analysis.

Provider

None

Sets the name of the provider for the data source. The default value is MSOLAP.

DataSourceInfo

None

Sets the provider-specific information that is required to access the data source.

Integrated Security

None

Sets the control access to use. If set to SSPI, an SSPI supported security package is used for user authentication. If set to Basic, the UserName and Password settings is required. An HTTP connection can use only the setting of Basic.

CreateCube

None

Sets the CREATE CUBE statement that is used during creation of a local cube.

Protocol Format

None

Sets the format of the XML sent to the server. Settings can be Default, XML, or Binary.

Encryption Password

None

Sets the password used to decrypt local cubes.

Impersonation Level

None

Sets the level of impersonation that the server is allowed to use when impersonating the client. The available settings are Anonymous, Identify, Impersonate, and Delegate. The default is Impersonate.

SSPI

None

Sets the security package to use for user authentication. Available settings include Negotiate, Kerberos, NTLM, and Anonymous User. The default is Negotiate.

UseExistingFile

None

Sets whether to use or overwrite the existing file. If set to true, the local file must already exist, and the cube is either created if the cube does not exist, or used if the cube does exist. If set to false, the existing local cube is overwritten. The default is false.

Character Encoding

None

Sets how characters are encoded. The default is the string UTF-8.

Use Encryption for Data

None

Sets whether encryption is used between the client and server. If set to true, all data sent between the client and server is encrypted with Secure Sockets Layer (SSL) encryption, provided that the server has a certificate installed.

Packet Size

None

Sets the packet size, in bytes, of network communications between client and server. The value must between 512 and 32767. The default is 4096.

Extended Properties

None

Sets the connection string properties that are to override the connection string in which Extended Properties is contained. This property is itself a connection string, the properties of which override the connection string in which Extended Properties is contained. Extended Properties can contain another Extended Properties, the properties of which maintain precedence. Extended Properties supports unlimited nesting.

LocaleIdentifier

None

Sets the preferred locale ID for the client application.

Location

None

Sets the name of the server.

Restricted Client

None

Sets whether the client is restricted. If set to true, the client will be restricted from using local cube and local mining model functionality. Thus, a client that tries to use the local cube or local mining models will raise an error.

Persist Security Info

None

Sets whether security information will be persisted. If set to true, security-related information can be obtained from the connection after the connection has been opened.

SessionID

None

Sets the session identifier that the connection will use. If the session identifier does not match an existing session, an error will be raised.

Transport Compression

None

Sets whether the connection will communicate with compression. If set to None, no compression will be used. If set to Compressed, communications may be compressed to reduce packet size. The GZIP setting compresses HTTP connections. If set to Default, GZIP will be used over an HTTP connection; otherwise, no compression will be used.

Compression Level

None

Sets the compression level, from 0 to 9. The greater the value, the higher the compression.

SspropInitAppName

None

Sets the name of the application that is to be associated with this connection. This value can be useful when monitoring trace events.

ClientProcessID

None

Sets the process ID of the application that is to be associated with this connection. If this value is not set, and SspropInitAppName has been set, ClientProcessID will automatically be set to the process ID retrieved from the client operating system. This value can be useful when monitoring trace events.

Several connection string settings map to a corresponding property in the AdomdConnection. The following table lists the connection string settings their corresponding AdomdConnection property.

Setting name	Property name
ConnectionTimeout	ConnectionTimeout
Catalog	Database

Note

Properties that are Initialization Properties cannot be changed after a connection has been opened. The set of available initialization properties can be queried through IDBProperties::GetPropertyInfo.

Thread Safety

Any public static (Shared in Microsoft Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

For a list of the supported platforms, see Hardware and Software Requirements for Installing SQL Server 2005.

Target Platforms

For a list of the supported platforms, see Hardware and Software Requirements for Installing SQL Server 2005.

See Also

Reference

AdomdConnection Class
AdomdConnection Members
Microsoft.AnalysisServices.AdomdClient Namespace