Chapter 11: Developing BI Applications with ADOMD.NET 419 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 420 Microsoft SQL Server 2005 Developer’s Guide 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 Chapter 11: Developing BI Applications with ADOMD.NET 421 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 422 Microsoft SQL Server 2005 Developer’s Guide 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 Chapter 11: Developing BI Applications with ADOMD.NET 423 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 424 Microsoft SQL Server 2005 Developer’s Guide 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. Chapter 11: Developing BI Applications with ADOMD.NET 425 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. 426 Microsoft SQL Server 2005 Developer’s Guide 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) Chapter 11: Developing BI Applications with ADOMD.NET 427 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 428 Microsoft SQL Server 2005 Developer’s Guide 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 [...]... Object The AdomdDataAdapter is used in combination with the AdomdConnection object and the AdomdCommand object to fill a CellSet with multidimensional data and then resolve the information back to a SQL Server database The following example illustrates how to use an AdomdConnection, create an AdomdCommand object, and populate a new DataTable with the AdomdDataAdapter The contents of the DataTable will... ADOMD.NET Summary ADOMD.NET is a database provider that allows you to develop database applications that communicate with multidimensional data sources In this chapter you learned about some of the SQL Server Analysis Services capabilities as well as how to develop BI applications that access some of those capabilities SSAS allows you to analyze your data to determine trends and patterns to meet your . class. The Microsoft. AnalysisServices .AdomdClient AdomdConnection class is used to connect to a multidimensional data Figure 11-3 ADOMDNETSample screen design 424 Microsoft SQL Server 2005 Developer’s. setting. LocaleIdentifier Sets the Locale ID for the client application. 426 Microsoft SQL Server 2005 Developer’s Guide Keyword Description Location Sets server name. Packet Size Sets network packet size in bytes source that’s associated with the active AdomdConnection object. AdomdCommand 420 Microsoft SQL Server 2005 Developer’s Guide supports six types of commands: Execute, ExecuteCellSet, ExecuteNonQuery,