Gets or sets the string that the AdomdConnection uses to open an analytical data source.
Assembly: Microsoft.AnalysisServices.AdomdClient (in Microsoft.AnalysisServices.AdomdClient.dll)
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.
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.
Sets the time to wait for a command to run before the AdomdConnection stops trying to run the command and generates an error.
Sets the time to wait for a connection to be established before the AdomdConnection stops trying to connect and generates an error.
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.
Sets the user ID or name that the AdomdConnection uses to establish a connection.
Sets the password that the AdomdConnection uses to establish a connection with the specified user name.
Sets the database to which the AdomdConnection establishes a connection.
Sets the level of protection that the provider uses to sign or encrypt the connection. This setting has the following options:
Sets the safety level that determines how security for user-defined functions and actions is handled.
Sets the time, in milliseconds, that elapses before objects automatically synchronize with the server.
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.
Sets the name of the provider for the data source. The default value is MSOLAP.
Sets the provider-specific information that is required to access the data source.
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.
Sets the CREATE CUBE statement that is used during creation of a local cube.
Sets the format of the XML sent to the server. Settings can be Default, XML, or Binary.
Sets the password used to decrypt local cubes.
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.
Sets the security package to use for user authentication. Available settings include Negotiate, Kerberos, NTLM, and Anonymous User. The default is Negotiate.
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.
Sets how characters are encoded. The default is the string UTF-8.
Use Encryption for Data
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.
Sets the packet size, in bytes, of network communications between client and server. The value must between 512 and 32767. The default is 4096.
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.
Sets the preferred locale ID for the client application.
Sets the name of the server.
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
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.
Sets the session identifier that the connection will use. If the session identifier does not match an existing session, an error will be raised.
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.
Sets the compression level, from 0 to 9. The greater the value, the higher the compression.
Sets the name of the application that is to be associated with this connection. This value can be useful when monitoring trace events.
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
Specifies whether the cells in a single UPDATE CUBE statement are isolated from each other. The default is not isolated.
A bitmask that determines the behavior of subqueries. This property can have the values listed in the following table.
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.
Determines the behavior of autoexists. This property can have the values listed in the following table.
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.
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.
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.
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.
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.
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.
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://.
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.
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.
To understand overlapping, review the following fact table of a simple Sales Forecasting cube with only five rows.
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.