Microsoft SQL Server 2005 Developer’s Guide- P21 pdf

AdomdConnection The AdomdConnection class is used to open a connection to a multidimensional data source.. It can also be used to connect to the multidimensional data source metadata, fo

The DataSource Class

The DataSource class defines and interacts with the DataSources available in

Analysis Services

The DataSourceView Class

A DataSourceView contains a list of data pertinent to its underlying data source The

DataSourceView class is used to associate a data source with a data source view, assign

table schemas, and save data source views to Analysis Services

The Dimension Class

The Dimension class allows you to set the source of a dimension, process the dimension,

and save the dimension to Analysis Services Dimensions are essentially an additional

layer of metadata you can place over a table or set of tables to define hierarchical

relationships between columns

The Cube Class

The Cube class allows you to set the source of a cube, process the cube and the

objects contained in the cube, add MeasureGroups to a cube, and save the cube and

its contents to Analysis Services Cubes store results of data at different summary

levels, resulting in efficient multidimensional query actions

ADOMD.NET Object Model

ADOMD.NET data provider is a NET Framework data provider that you can use to

communicate with multidimensional data sources from a client application

AdomdConnection

The AdomdConnection class is used to open a connection to a multidimensional data

source It can also be used to connect to the multidimensional data source metadata,

for example, a local cube (.cub) file You can review the local cube file to learn about

the metadata properties that represent the cube on the multidimensional data source

Each AdomdConnection is associated with an XMLA session The AdomdConnection

objects are not automatically destroyed when they go out of scope This means that you

must explicitly close any open ADOMD.NET Connection objects in your applications

If the AdomdConnection is not closed, it remains open and can be used by other

AdomdConnections

AdomdCommand

The AdomdCommand class is used to execute a command against a multidimensional

data source that’s associated with the active AdomdConnection object AdomdCommand

supports six types of commands: Execute, ExecuteCellSet, ExecuteNonQuery,

ExecuteReader, ExecuteScalar, and ExecuteXmlReader The ExecuteCellSet command returns a CellSet, the ExecuteReader command returns an AdomdDataReader object, and the Execute command returns either a CellSet or an AdomdDataReader The

ExecuteXmlReader command returns an XmlReader object, and the ExecuteNonQuery command is used to execute the command statements without returning any results The ExecuteScalar will be implemented in the future

AdomdDataReader

The AdomdDataReader class returns a forward-only result set from the multidimensional data source that’s associated with the active AdomdConnection object Unlike objects of most other ADOMD.NET classes that are instantiated by calling the constructor, objects created from the AdomdDataReader class are instantiated by calling the ExecuteReader method of the AdomdCommand object

AdomdDataAdapter

The AdomdDataAdapter class is used to retrieve data from a multidimensional data source and fill a CellSet The AdomdDataAdapter class is responsible for both filling up the CellSet as well as sending changes made in the CellSet back to the data source You can employ the InsertCommand, UpdateCommand, and DeleteCommand properties to manipulate the data at the data source

CellSet

The CellSet object represents a multidimensional result set returned as a result of running an MDX statement or query command The Execute or ExecuteCellSet method of the AdomdCommand object returns a CellSet and contains collections

of cells that are organized along multiple dimensions or axes

Several other objects in the ADOMD.NET object hierarchy support additional data and metadata information about these main objects

AdomdParameter

The AdomdParameter class is used to represent a parameter that’s passed to an AdomdCommand object AdomdParameter objects have properties that define their attributes

AdomdTransaction

The AdomdTransaction class represents SQL transactions that allow multiple database transactions to be treated as a unit where an entire group of database updates either

can be posted to the database or can all be undone as a unit The AdomdTransaction

object uses the BeginTransaction method to specify the start of a transaction and then

either the Commit method to post the changes to the database or the Rollback method

to undo the pending transaction An AdomdTransaction object is attached to the active

AdomdConnection object

AdomdError

The AdomdError object is raised by the provider during the execution of a statement

or query and represents an XML for Analysis error The AdomdError objects are

contained within the Errors property of an AdomdErrorResponseException and so

are not directly raised in ADOMD.NET

AdomdException

The AdomdException class throws an exception if an error occurs with the

AdomdConnection while information is being retrieved from a data source

CubeDef

The CubeDef represents only the metadata of a cube The CubeDef is referenced from

the AdomdConnection, allowing you to retrieve information, such as the dimensions,

measures, and the properties of the cube, that is stored in a multidimensional data source

Building a BI Application with ADOMD.NET

In the first part of this chapter you learned about the various components that make

up SQL Server 2005’s Analysis Services In this part of the chapter you’ll get a more

detailed look at the steps required to develop a BI application with ADOMD.NET

You begin building a client application by starting the Visual Studio 2005

development environment and creating a Windows forms project In this example,

we’ll step through a sample program that connects to the AdventureWorksDW

database and displays data and metadata for a sample cube

To build a Windows forms application, first open Visual Studio and then select the

File | New | Project option to display the New Project dialog as shown in Figure 11-2

This example uses the VB.NET language, so as you can see in the figure, in the

Project Types area of the dialog the Visual Basic | Windows option has been selected,

and in the Templates area of the dialog the Windows Application option has been

selected Fill in the boxes at the bottom of the dialog, setting the name and location

for your project Clicking OK creates the project and displays the Visual Studio design environment with a default Windows form created for you

In the design environment of this VB.NET project, items from the Toolbox have been added and formatted on the Windows form to create a wizard-like program that steps through the basic ADOMD.NET events Figure 11-3 shows the ADOMDNETSample application form

Now that the screen has been designed, the next step is to add code to execute the ADOMD.NET actions

Adding a Reference for ADOMD.NET

Before you can use the ADOMD.NET data provider in your code, you must first add

a reference to the SSAS DLL and also specify an import directive for the Microsoft AnalysisServices.AdomdClient namespace in your project To add a reference to the SSAS DLL, you select Project | Add Reference from the Visual Studio’s main menu

In the Add Reference dialog that is displayed, scroll through the list of available NET components until you see Microsoft.AnalysisServices.AdomdClient option Highlight the option and click the OK button to add the DLL reference to your project The

Figure 11-2 ADOMD.NET New Project dialog

Microsoft.AnalysisServices.AdomdClient namespace contains all of the related SSAS

connection and data access classes Next, to add an import directive for the Microsoft

.AnalysisServices.AdomdClient to a VB.NET project, you would add the following code

to the declaration section of your source file:

Imports Microsoft.AnalysisServices.AdomdClient

Using the AdomdConnection Object

After adding an import directive to your code, you’re ready to begin using the different

classes contained in the Microsoft.AnalysisServices.AdomdClient namespace The most

basic of the classes is the AdomdConnection class The Microsoft.AnalysisServices

.AdomdClient AdomdConnection class is used to connect to a multidimensional data

Figure 11-3 ADOMDNETSample screen design

source on SQL Server 2005 The following example illustrates how to make a connection

by setting the AdomdConnection object’s ConnectionString Property:

Private Sub AdomdConnect(ByRef sServer As String, _

ByRef sLoginID As String, ByRef sPassword As String)

Dim cn As New AdomdConnection()

Dim sConnString As String = _

"Provider=SQLNCLI.1;Data Source=" & sServer & ";"

' Check for Integrated security

If chkIntegratedSecurity.CheckState = CheckState.Checked Then

sConnString += "Integrated Security=SSPI;"

Else

sConnString += "User ID=" & sLoginID & ";Password=" & _

sPassword & ";"

End If

sConnString += "Initial Catalog=AdventureWorksDW"

cn.ConnectionString = sConnString

Try

cn.Open()

Catch ex As Exception

MessageBox.Show(ex.Message)

End Try

End Sub

In this case string variables containing the name of the SQL Server system to connect

to along with the user ID and password are passed into the top of the routine Next,

a new instance of the Microsoft.AnalysisServices.AdomdClient AdomdConnection object named cn is created Then the ConnectionString property of the Microsoft

.AnalysisServices.AdomdClient AdomdConnection object is assigned The connection string uses the Data Source keyword to identify the SQL Server system that will be connected to The User ID and Password keywords provide the authentication values required to log in to SQL Server if you are connecting using mixed security A User ID and Password are not required in the connection string if you are connecting using a trusted connection A complete list of the valid ADOMD.NET Data Provider connection string keywords is presented in the next section After the ConnectionString property has been assigned the appropriate connection string, a Try-Catch block is used to execute the cn AdomdConnection object’s Open method If a connection could not be made to the data source, the Catch block will be executed and a message box will be displayed showing the error information

The ADOMD.NET Data Provider Connection String Keywords

The ADOMD.NET connection string is much like the connection strings used by

ADO.NET When an application calls the Open method of the AdomdConnection

object, the connection string is parsed and each of the properties are evaluated If the

AdomdConnection object supports the property provided in the connection string,

the value for that property is validated However, if the value is invalid or is not

supported, an exception is thrown Table 11-1 shows the connection string keywords

that are directly supported by the AdomdConnection object

Table 11-1 ADOMD NET Connection String Keywords

Keyword Description

AutoSyncPeriod Sets the time, in milliseconds, before objects are automatically synchronized with the server

Catalog – or - Initial

Catalog – or - Database

Sets the database for the AdomdConnection to connect to

Character Encoding Sets how characters are encoded The default is a UTF-8 string

ClientProcessID Sets the process ID of the application associated with connection If not set, and

SspropInitAppName is set, it will automatically be set to the process ID retrieved from the client operating system

Compression Level Sets compression level Values range from 0 to 9

Connect Timeout The time to wait before terminating a connection attempt and throwing an exception

Connect To Sets the method used to connect to the server

8.0: Connection uses in-process XMLA.

9.0: Connection uses XMLA.

Default: Connection first tries XMLA and then attempts to use in-process XMLA.

CreateCube Sets the CREATE CUBE statement used during the creation of a local cube

Data Source

–or-DataSourceLocation

Sets the instance or local cube (.cub) file of the AdomdConnection connection

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

Encryption Password Sets the password used to decrypt local cubes

Extended Properties Sets the connection string properties Supports unlimited nesting

Impersonation Level Sets the level of impersonation the server is allowed when impersonating the client Available

settings are Anonymous, Identify, Impersonate, and Delegate Default is Impersonate

Integrated Security Sets the connect access to use

SSPI: An SSPI-supported security package is used for user authentication.

Basic: The UserName and Password settings are required for connection HTTP

connections can only use the Basic setting

LocaleIdentifier Sets the Locale ID for the client application

Keyword Description

Location Sets server name

Packet Size Sets network packet size in bytes The value must between 512 and 32767 The default

is 4096

Password –or-PWD Sets the password for the AdomdConnection

Persist Security Info Sets if security information will be persisted If ‘true’, security-related information can be

obtained from the connection after the connection has been opened

ProtectionLevel Sets the level of protection for the provider to sign or encrypt the connection

NONE: Performs no authentication of data sent to the server.

CONNECT: Authenticates when the client establishes the connection with the server PKT INTEGRITY: Authenticates that complete and unchanged data is received from

the client

PKT PRIVACY: Encrypts the data and authenticates that complete and unchanged data

is received from the client

Protocol Format Sets the format of the XML sent to the server Settings can be Default, XML, or Binary Provider Sets the name of the provider for the data source Default is MSOLAP

Restricted Client Sets client restriction If ‘true’, the client is restricted from using local cube and local mining

model functions

Safety Options Sets the safety level for how security for user-defined functions and actions is handled SessionID Sets the session identifier for the connection

SSPI Sets the security package to use for user authentication Settings are Negotiate, Kerberos,

NTLM, or Anonymous User Default is Negotiate

SspropInitAppName Sets the name of the application to be associated with connection

Timeout The time to wait for a command to run before terminating the attempt and throwing an exception Transport Compression Sets if connection will communicate with compression

None: No compression is used.

Compressed: Compression is used.

GZIP: Compresses HTTP connections.

Default: Compression is used over HTTP connections; otherwise, no compression.

Use Encryption for Data Sets encryption between the client and server If ‘true’, all data sent between the client and

server is encrypted with SSL encryption Server needs certificate installed

UseExistingFile Set to use or overwrite the existing file If ‘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 ‘false’, the existing local cube is overwritten Default is ‘false’

UserName -or-UID –

or User ID – or

-Authenticated User

Sets the login ID for the AdomdConnection

Table 11-1 ADOMD NET Connection String Keywords (continued)

Using the AdomdCommand Object

After a connection has been established to a multidimensional data source, you can

use the AdomdCommand object to execute commands that return data or metadata

information from the multidimensional data source The format of data or metadata

that is returned depends on the execution method you call from the AdomdCommand

object These are the AdomdCommand execution methods:

䉴 Execute The Execute method runs the command contained in the

AdomdCommand object and returns either an AdomdDataReader or a CellSet

If the results of the command cannot be formatted into an AdomdDataReader

or a CellSet, the Execute method returns a null value

䉴 ExecuteCellSet The ExecuteCellSet method runs the command contained in

the AdomdCommand object and returns a CellSet If the results of the command

cannot be formatted into a CellSet, an exception is thrown

䉴 ExecuteNonQuery The ExecuteNonQuery method is used to execute

commands that do not return any data or metadata

䉴 ExecuteReader The ExecuteReader method runs the AdomdCommand

command and returns an AdomdDataReader object While the AdomdDataReader

is in use and being served by the AdomdConnection and AdomdCommand

objects, only the Close method can be performed on the AdomdConnection

and AdomdCommand objects Once the Close or Dispose method is called

on the AdomdDataReader object, other operations can be performed on the

AdomdConnection and AdomdCommand objects

䉴 ExecuteXmlReader TheExecuteXmlReader method returns an XmlReader

object in response to the AdomdCommand object’s command The XmlReader

object directly references the XMLA response to the command in its native

XML format Like the AdomdDataReader, the AdomdConnection object can

only be closed until the Close method for the XmlReader is called

Let’s take a closer look at how to use several of these execution methods using the

example program

Using the AdomdDataReader Object

The AdomdDataReader class is the implementation of the System.Data.IDataReader

interface for ADOMD.NET and is used as a quick way to read forward-only result

sets To create an AdomdDataReader, you must call the ExecuteReader method of

the AdomdCommand, instead of directly using a constructor The following code

listing shows creating an AdomdDataReader and outputting the results to a ListView control:

Private Sub AdomdDataReader(ByRef cn As AdomdConnection)

Dim cmd As New AdomdCommand("SELECT NON EMPTY " & _

"[Dim Time].[English Month Name].MEMBERS ON COLUMNS, " & _

"NON EMPTY {[Dim Employee].[Last Name].MEMBERS} ON ROWS " & _ "FROM [AdventureWorksDW]", cn)

Dim dr As AdomdDataReader

Dim lvItem As ListViewItem

' Clear the ListView

rstListView.Items.Clear()

rstListView.Columns.Clear()

Try

' Execute the query and return AdomdDataReader

dr = cmd.ExecuteReader()

dr.Read()

rstListView.Columns.Add("", 80, HorizontalAlignment.Left) ' Add the column names

For iColName As Integer = 1 To dr.FieldCount - 1

rstListView.Columns.Add _

(ParseColName(dr.GetName(iColName)), 60, _

HorizontalAlignment.Left)

Next iColName

' Read the DataReader

Do

' Init the new ListViewItem

If (Not dr.IsDBNull(0)) Then

lvItem = New ListViewItem(dr(0).ToString())

Else

lvItem = New ListViewItem(String.Empty)

End If

' Add the column items

For iField As Integer = 1 To dr.FieldCount - 1

If (Not dr.IsDBNull(iField)) Then

lvItem.SubItems.Add(dr(iField).ToString())

Else