Crystal Reports For Visual Studio 2005 Walkthroughs Walkthroughs Copyright © 2004 Business Objects Page 2 © 2004 Business Objects. All rights reserved. Business Objects, the Business Objects logo, Crystal Reports, and Crystal Enterprise are trademarks or registered trademarks of Business Objects SA or its affiliated companies in the United States and other countries. All other names mentioned herein may be trademarks of their respective owners. Version 1.0 Walkthroughs Copyright © 2004 Business Objects Page 3 Contents CrystalReportViewer Object Model Tutorials 6 Logging onto a Secure SQL Server Database 7 Reading and Setting Discrete Parameters 16 Reading and Setting Range Parameters for a Subreport 40 Filtering Data Using Selection Formulas 52 Customizing the CrystalReportViewer Control 65 ReportDocument Object Model Tutorials 100 Persisting the ReportDocument Object Model Using Session 101 Logging onto a Secure SQL Server Database Using SQL Authentication 113 Logging onto a Secure SQL Server Database Using Integrated Security 129 Logging onto a Secure SQL Server Database with a Subreport 141 Reading and Setting Discrete Parameters 148 Reading and Setting Parameters with a Subreport 176 Exporting to Multiple Formats 191 Printing and Setting Print Options 248 Filtering Data Using Selection Formulas 264 Displaying Report Parts with the CrystalReportPartsViewer Control 279 Reduced-Code Tutorials in Visual Studio 2005 288 Web Site Setup with Crystal Reports Using Smart Tasks 289 Windows Project Setup with Crystal Reports using Smart Tasks 295 Secure Database Logon in a Web Site 300 Parameter Setting in a Web Site 310 Exposing Report Data to Other Controls in a Web Site 319 Exposing Report Data to Other Controls in a Windows Application 325 Data Connectivity Tutorials 331 Connecting to ADO.NET DataSets 332 Connecting to IDataReader 347 Connecting to Object Collections 358 Walkthroughs Copyright © 2004 Business Objects Page 4 Other Tutorials 374 Configuring Multilingual Client Support 375 Creating a User Function Library 389 Populating a Drop Down List of Reports from the File Directory 403 Populating a Drop Down List of Reports from a Web Service 412 Triggered Export with the ReportExporter Control 428 Deployment Tutorials 432 Deploying a Windows Application with ClickOnce Deployment 433 Creating a New Web Site Deployment Project with Windows Installer 438 Creating a New Windows Application Deployment Project with Windows Installer 441 Migrating a Project that Uses Crystal Reports for Visual Studio .NET 2002 or 2003 Merge Modules Deployment 444 Migrating a Project that Uses Crystal Reports for Visual Studio 2005 Merge Modules Deployment 446 Performing a Silent Installation with a Windows Installer 448 Deploying Web Sites with Merge Modules 450 Deploying Windows Applications with Merge Modules 453 Configuring Database Driver Installation Options 456 Appendix 458 Crystal Reports Product Keycode and Registration Number 459 Design Time Preview 461 Formula Reference 462 System Setup 531 What Needs to be Installed? 532 What Needs to be Verified? 535 Add New Item Dialog Box Includes Crystal Reports 536 64-Bit Development Configuration 537 Optional Installation: MSDE 538 MSDE Installation with Windows or SQL Server Authentication 539 Northwind Database Installation 542 Security: Creating a Limited Access Database Account 544 Walkthroughs Copyright © 2004 Business Objects Page 5 Sample Reports’ Directory 547 Tutorials’ Sample Code Directory 549 Viewers’ Virtual Directory 550 Location of Xtreme Sample Database 552 ODBC DSN Entry for Xtreme Sample Database 553 Project Setup 555 Additional Setup Requirements 564 Multilingual Client Support 576 Useful Addresses at a Glance 578 Which Persistence Approach Should I Use with Crystal Reports? 579 .NET Framework 2.0 587 Crystal Reports for .NET Framework 2.0 Windows Installer 588 Merge Modules Summary 589 Crystal Reports Merge Modules for Visual Studio 2005 591 Walkthroughs Copyright © 2004 Business Objects Page 8 Logging onto a Secure SQL Server Database Introduction When you use the CrystalReportViewer object model to log on to a secure SQL Server database, you must use classes from the CrystalDecisions.Shared namespace. The properties of the ConnectionInfo class are used to connect to the database server or ODBC data sources. In this tutorial, you set the ServerName, DatabaseName, UserID and Password properties. If you choose only to set the DatabaseName, UserID, and Password properties, then you are logged on to the default server of the database that you have specified within the report. However, if you choose to assign an alternate ServerName property, you can redirect the report to a different server at runtime. You retrieve the TableLogOnInfos instance from the LogOnInfo property of the CrystalReportViewer control. Then, you assign the ConnectionInfo instance to each TableLogOnInfo object in the TableLogOnInfos instance. The logon code in this tutorial also works for subreports that are inserted into the main report. For the ReportDocument object model, you must modify the code to work for subreports. The ReportDocument object model is recommended over the CrystalReportViewer object model. Creating a Report Connected to a Secure SQL Server Database To begin, create a report that draws its information from the Northwind database. Note Northwind is a sample database provided with SQL Server. Some setup is required as a prerequisite to this tutorial. Prerequisite Database Setup 1. SQL Server configuration: If you have SQL Server (or the OEM version, MSDE) installed, it must be configured to require SQL Server Authentication. If you do not have SQL Server (or the OEM version, MSDE) installed, you must install MSDE with SQL Server Authentication set to "True." 2. The Northwind database provided with SQL Server must be installed and verified that it requires SQL Server Authentication. 3. A limited access account must be created for use within the Web site. To install MSDE with SQL Server Authentication, or the Northwind database, go to the following sections from Appendix: System Setup in this documentation: Appendix: MSDE Installation with Windows or SQL Server Authentication Appendix: Northwind Database Installation Appendix: Security: Creating a Limited Access Database Account Once you have configured SQL Server and the Northwind database according to the sections above, you are ready to create a report that draws its information securely from a Northwind database. Walkthroughs Copyright © 2004 Business Objects Page 9 To create a report with secure data from the Northwind database Note This procedure works only with a project that has been created from Appendix: Project Setup. Project Setup contains specific namespace references and code configuration that is required for this procedure, and you will be unable to complete the procedure without that configuration. Therefore, before you begin this procedure, you must first follow the steps in Appendix: Project Setup. 1. In Solution Explorer, right-click the project name that is in bold type, point to Add, and then click Add New Item. 2. In the Add New Item dialog box, in the Templates view, select the Crystal Report template. 3. In the Name field, enter the name "NorthwindCustomers.rpt", and then click Open. Note If you have not registered before, you may be asked to register. To find out how to register, see Appendix: Crystal Reports Registration and Keycode. 4. In the Create New Crystal Report Document panel of the Crystal Reports Gallery dialog box, select Using a Report Wizard. 5. In the Choose an Expert panel, select Standard. Click OK. The Standard Report Creation Wizard window appears. 6. In the Available Data Sources panel, expand the Create New Connection folder. 7. From the subfolder that opens, expand the OLE DB (ADO) folder. The OLE DB (ADO) window appears. 8. Select Microsoft OLE DB Provider for SQL Server, and then click Next. 9. Enter the values for your database server, user id and password into the Server, User ID and Password fields. 10. From the Database drop down list, select "Northwind." Leave the Integrated Security checkbox unchecked because you are using SQL Server authentication instead of NT authentication. 11. Click Finish. The OLE DB folder is now expanded, showing your database server, and within it, the Northwind database. 12. Expand the nodes Northwind, dbo, and Tables, and then select the Customers table. 13. Click the > symbol to move the table into the Selected Tables panel, and then click Next. 14. Expand the Customers table, and then hold down the Ctrl key while you click CompanyName, ContactName and City. 15. Click the > symbol to move these fields into the Fields to Display panel, then click Next. 16. In the Available Fields panel, under Report Fields, select Customer.City, then click the > symbol to move the field into the Group By panel, and then click Finish. The NorthwindCustomers report is created and loaded into the main window of Visual Studio. You are now ready to bind the report to the CrystalReportViewer control. Walkthroughs Copyright © 2004 Business Objects Page 10 Binding the Report Without Logon Code In Appendix: Project Setup, you have placed a CrystalReportViewer control on the Web or Windows Form. In the previous step, you have added a NorthwindCustomers report to the project. In this section, you bind the file directory path of the NorthwindCustomers report to the CrystalReportViewer control. Then you test whether the report displays correctly when the database logon code has not been set. To bind the file directory path of the NorthwindCustomers report to the CrystalReportViewer control 1. Open the Web or Windows Form. 2. From the View menu, click Code. 3. Locate the ConfigureCrystalReports() method (that you have created in Appendix: Project Setup). 4. Declare a string variable, name it reportPath, and assign to it a runtime path to the local report. This path is determined differently for Web Sites and Windows projects: For a Web Site, pass the name of the local report file as a string parameter into the Server.MapPath() method. This maps the local report to the hard drive file directory path at runtime. [Visual Basic] Dim reportPath As String = Server.MapPath("NorthwindCustomers.rpt") [end] [C#] string reportPath = Server.MapPath("NorthwindCustomers.rpt"); [end] For a Windows project, concatenate the Application.StartupPath property with a backslash and the local report file name. This maps the report to the same directory as the Windows executable file. Note At compile time you will copy the report to the directory containing the executable file. [Visual Basic] Dim reportPath As String = Application.StartupPath & "\" & "NorthwindCustomers.rpt" [end] [C#] string reportPath = Application.StartupPath + "\\" + "NorthwindCustomers.rpt"; [end] 5. Assign the file directory path of the NorthwindCustomers report to the ReportSource property of the CrystalReportViewer control. [Visual Basic] myCrystalReportViewer.ReportSource = reportPath [end] Walkthroughs Copyright © 2004 Business Objects Page 11 [C#] crystalReportViewer.ReportSource = reportPath; [end] You are now ready to build and run your project. It is expected that the report loading will fail, because code has not yet been written to log onto the database. To test the loading of the NorthwindCustomers report 1. From the Build menu, select Build Solution. 2. If you have any build errors, go ahead and fix them now. 3. If you use a non-embedded report in a Windows project, locate the compiled Windows executable in the \bin\debug\ subdirectory, and then copy the report to that subdirectory. Note To have the non-embedded report loaded by the Windows executable at runtime, the report must be stored in the same directory as the Windows executable. 4. From the Debug menu, click Start. Note If you are developing a Web Site in Visual Studio 2005, and this is the first time you have started debugging, a dialog box appears and states that the Web.config file must be modified. Click the OK button to enable debugging. The NorthwindCustomers report will not display. It will display after you add the database logon code. Note Results may vary, depending on the version of Crystal Reports that you use. For example, if you have Crystal Reports 10 and up installed, you are prompted for database logon information for that report. This is a new feature of Crystal Reports Developer and Crystal Reports for Visual Studio 2005. If you are running a previous version of Crystal Reports, an exception is thrown. In either case, you must follow the next step procedure to create a fully functional application. 5. Return to Visual Studio and click Stop to exit from debug mode. Adding the Report Logon Code You are now ready to add the logon code to the code-behind class. You begin by creating a private helper method, SetDBLogonForReport() . To create and code the SetDBLogonForReport() method 1. Return to the code-behind class for this Web or Windows Form. 2. At the bottom of the class, create a new private method named SetDBLogonForReport() with ConnectionInfo passed into the method signature. [Visual Basic] Private Sub SetDBLogonForReport(ByVal myConnectionInfo As ConnectionInfo) End Sub [end] [C#] private void SetDBLogonForReport(ConnectionInfo connectionInfo) Walkthroughs Copyright © 2004 Business Objects Page 12 { } [end] 3. Within this method, retrieve the TableLogOnInfos instance from the LogOnInfo property of the CrystalReportViewer class. Note To make the TableLogOnInfos class accessible, include an "Imports" [Visual Basic] or "using" [C#] statement at the top of the code-behind class for the CrystalDecisions.Shared namespace. (You added this declaration in Appendix: Project Setup.) TableLogOnInfos is an indexed class that contains instances of the TableLogOnInfo class. [Visual Basic] Dim myTableLogOnInfos As TableLogOnInfos = myCrystalReportViewer.LogOnInfo [end] [C#] TableLogOnInfos tableLogOnInfos = crystalReportViewer.LogOnInfo; [end] 4. Create a foreach loop that loops through each TableLogOnInfo instance in the TableLogOnInfos indexed class instance. [Visual Basic] For Each myTableLogOnInfo As TableLogOnInfo In myTableLogOnInfos Next [end] [C#] foreach(TableLogOnInfo tableLogOnInfo in tableLogOnInfos) { } [end] 5. Within the foreach loop, set the ConnectionInfo property of TableLogOnInfo to the ConnectionInfo parameter. [Visual Basic] myTableLogOnInfo.ConnectionInfo = myConnectionInfo [end] [C#] tableLogOnInfo.ConnectionInfo = connectionInfo; [end] This step procedure has created a method to set the logon for the database. However, you must modify the ConfigureCrystalReports() method to address this method, for the report to be aware that it has database logon information. [...]... is shown below is for a Visual Studio 2005 project "ProjectName" is replaced by the name of your Windows project "UserName" is replaced by your logon name The default path for a Windows project: [Visual Basic] myCrystalReportViewer.ReportSource = "C:\Documents and Settings\UserName\My Documents \Visual Studio\ Projects\ProjectName\CustomersByCity.rpt" [end] [C#] crystalReportViewer.ReportSource = "C:\\Documents... the foreach loop, rebind the file directory path of the CustomersByCity report to the ReportSource property of the CrystalReportViewer class Note The file directory path that is shown below is for a Visual Studio 2005 project "ProjectName" is replaced by the name of your Web Site "UserName" is replaced by your logon name The default path for a Web Site project: [Visual Basic] myCrystalReportViewer.ReportSource... In Visual Studio NET 2002 or 2003 where Crystal Reports has not been upgraded to Crystal Reports Developer, the Create New Connection folder does not exist; the contents are shown at the top level 7 From the subfolder that opens, expand the ODBC (RDO) folder 8 In the ODBC (RDO) window, select the correct ODBC DSN entry for your version of Crystal Reports as explained in Appendix: ODBC DSN Entry for. .. string identifier for the Session that you add [Visual Basic] Session("myArrayList") = myArrayList [end] [C#] Session["arrayList"] = arrayList; [end] 3 Call the ConfigureCrystalReports() method This retrieves the ArrayList instance, applies it to the report, and binds the report to the CrystalReportViewer control [Visual Basic] ConfigureCrystalReports() [end] [C#] ConfigureCrystalReports(); [end] You... draws its information from the sample Microsoft Access database that ships with Crystal Reports Note Xtreme.mdb is the sample database that is provided with Crystal Reports To locate xtreme.mdb on your hard drive for your version of Crystal Reports, see Appendix: Location of Xtreme Sample Database You need to connect to the database through its ODBC DSN entry To learn the name of this entry for your version...Walkthroughs Modifying the ConfigureCrystalReports() method requires two actions: Configure the ConnectionInfo instance Call the SetDBLogonForReport() method To modify the ConfigureCrystalReports() method to address the database logon code 1 In the ConfigureCrystalReports() method, create a couple of line breaks in the code above the line that binds the report to the CrystalReportViewer control 2 Within... to the CrystalReportViewer control, for the report to be aware that it has parameter settings To call the SetCurrentValuesForParameterField() method before the report is bound to the CrystalReportViewer control 1 In the ConfigureCrystalReports() method, declare and instantiate an ArrayList above the line that binds the report to the CrystalReportViewer control [Visual Basic] Dim myArrayList As ArrayList... Name field, enter the name "CustomersByCity.rpt" and click Add Note In Visual Studio NET 2002 or 2003, the button is named Open If you have not registered before, you are asked to register To find out how to register, see Appendix: Crystal Reports Registration and Keycode 4 In the Create New Crystal Report Document panel of the Crystal Reports Gallery dialog box, select Using a Report Wizard 5 In the Choose... data from the sample database that is shipped with Crystal Reports for Visual Studio When you instantiate the report in the code, you create an ArrayList that contains city names (Paris, Tokyo) and pass that ArrayList instance to a helper method that sets those city names as the current values for the city parameter You then bind the report to the CrystalReportViewer control and view the report with... { Copyright © 2004 Business Objects Page 27 Walkthroughs } [end] Within the foreach loop, you now create a nested conditional block that checks for discrete (as opposed to range) parameter values Two versions of this conditional block exist, because the API has changed slightly across versions of Crystal Reports for Visual Studio Check your API (using IntelliSense) to see which property is available . Installer 4 41 Migrating a Project that Uses Crystal Reports for Visual Studio .NET 2002 or 2003 Merge Modules Deployment 444 Migrating a Project that Uses Crystal Reports for Visual Studio 2005. Crystal Reports? 579 .NET Framework 2.0 587 Crystal Reports for .NET Framework 2.0 Windows Installer 588 Merge Modules Summary 589 Crystal Reports Merge Modules for Visual Studio 2005 5 91. of Crystal Reports that you use. For example, if you have Crystal Reports 10 and up installed, you are prompted for database logon information for that report. This is a new feature of Crystal