Artikel
05/23/2011

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
    Get
    Set
'Usage
Dim instance As AdomdConnection
Dim value As String

value = instance.ConnectionString

instance.ConnectionString = value

public string ConnectionString { get; set; }

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

abstract ConnectionString : string with get, set
override ConnectionString : string with get, set

final function get ConnectionString () : String
final function set ConnectionString (value : String)

Property Value

Type: System.String
A string that contains the connection string that is used by the AdomdConnection.

Implements

IDbConnection.ConnectionString

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. When connecting to a PowerPivot embedded instance the value must be $Embedded$; dollar signs included.
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.
Update Isolation Level	None	Specifies whether the cells in a single UPDATE CUBE statement are isolated from each other. The default is not isolated.
SubQueries	None	A bitmask that determines the behavior of subqueries. This property can have the values listed in the following table. ValueDescription 0 Default value, compatible with earlier versions of Analysis Services. Calculated members or calculated sets are not allowed in subselects or subcubes. 1 Calculated members or calculated sets are allowed in subselects or subcubes. Ascendants of the calculated member are not included in the space of the subselect or subcube. 2 Calculated members or calculated sets are allowed in subselects or subcubes. Ascendants of the calculated member are included in the space of the subselect or subcube. Zero or empty are the default values for this property. This is a session property that can only be set when the session is created. For more information about the behavior of calculated members or calculated sets in subqueries and subcubes, see Calculated Members in Subselects and Subcubes.
AutoExists	None	Determines the behavior of autoexists. This property can have the values listed in the following table. ValueDescription 0 Default value, same as 1. 1 Apply deep autoexists for query axes and named sets. Includes WHERE clauses and subselects. 2 Apply deep autoexists for query axes and exclude named sets from autoexists. Includes WHERE clauses and subselects. 3 Apply no autoexists for named sets with WHERE clause. Apply shallow autoexists for query axes with WHERE clause. Apply deep autoexists for query axes with subselects and named sets with subselects. Zero or empty are the default values for this property. This is a session property that can only be set when the session is created.

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.

Connecting to Local Cube Files

To connect to an existing local cube file, you must provide the full path and file name of a valid local cube file in the Data Source connection string setting and, if applicable, a valid password in the Password connection string setting. If the local cube file does not already exist, a new local cube file is created and protected by the password, provided that a password was specified. If a local cube is to be created, additional settings must be specified in the connection string, such as INSERTINTO or CREATECUBE.

Setting Safety Options

The value of the Safety Options property determines whether unsafe libraries can be registered and loaded by Microsoft PivotTable Service or the server. If an attempt is made to load an unsafe library or reference an unsafe user-defined function while safety checking is enabled, then PivotTable Service returns the following error:

User defined function <function name> cannot be used, because the class that implements it is not safe for initialization or scripting, which is required by client settings.

The value of the Safety Options property determines whether the PASSTHROUGH keyword is allowed in local cubes. If a client application tries to create a local cube with an INSERT INTO statement that contains the PASSTHROUGH keyword, or if a client application attempts to refresh a local cube that contains an INSERT INTO statement that uses the PASSTHROUGH keyword, an error is raised.

The following table lists the possible values for the Safety Options property.

Value	Description
0	For connections to a local cube, or by an Internet Information Services (IIS) server, this value is the same as DBPROPVAL_MSMD_SAFETY_OPTIONS_ALLOW_SAFE. For all other connections, this value is the same as DBPROPVAL_MSMD_SAFETY_OPTIONS_ALLOW_ALL.
1	This value enables all user-defined function libraries without verifying that the libraries are safe for initialization and scripting, and also allows usage of the PASSTHROUGH keyword in local cubes. MDSCHEMA_ACTIONS results are unfiltered. Note We do not recommend this option.
2	This value ensures that all classes for a particular user-defined function library are checked to ensure that they are safe for initialization and scripting, and also prevents usage of the PASSTHROUGH keyword in local cubes. MDSCHEMA_ACTIONS results of type HTML and command line are filtered out. MDSCHEMA_ACTIONS results of type URL are filtered out unless the CONTENT column begins with HTTP:// or HTTPS://.
3	This value prevents user-defined functions from being used during the session and prevents usage of the PASSTHROUGH keyword in local cubes. MDSCHEMA_ACTIONS results are empty.

Update Isolation Level

The value of the Update Isolation Level property affects how Analysis Services will evaluate each cell for update. Cells to be updated can overlap from one SET command to the next, in the same UPDATE statement. If updated cells do not overlap, you can improve performance by setting Update Isolate Level to Isolated (1). However, if updated cells do overlap and Update Isolate Level is set to Isolated (1), the outcome of the UPDATE statement will be erroneous.

The following table lists the possible values for the Update Isolate Level property.

Value	Description
0	Not Isolated
1	Isolated Note Use this value with caution, and only use it when no cells in the UPDATE CUBE statement overlap.

To understand overlapping, review the following fact table of a simple Sales Forecasting cube with only five rows.

Name	Gender	State	ProjectedSales
Alice	Female	OR	Null
Betty	Female	WA	Null
Charles	Male	WA	Null
Diego	Male	CA	Null
Edward	Male	CA	Null

Suppose you want assign to Projected Sales a distributed value of 100 for all females and a distributed value of 200 for all salespeople from California (CA). In this case, your update cube statement would be as follows:

UPDATE CUBE SalesForcasting SET Female=100, CA=200 USE_EQUAL_INCREMENT

If you check the updated cells you will notice that they do not overlap. Female updated cells are Alice and Betty's cells and California cells are Diego and Edward.

Now, suppose you want to assign a distributed value of 100 to all males and a distributed value of 200 to all salespeople from Washington (WA). In this case, your update cube statement would be the following:

UPDATE CUBE SalesForcasting SET Male=100, WA=200 USE_EQUAL_INCREMENT

If you check the updated cells you will notice that they do overlap. Male updated cells are Charles, Diego, and Edwards' cells, and Washington cells are Betty and Charles. The cells overlap at Charles.

Dela via