Non-Embedded Reports

When you save a .NET project, each report in the project is saved as a separate “.rpt” file. Although these files are saved in the same folder as your .NET application, they are independent of the project. In other words, you can copy them to another folder and use them in another project. These reports are called non-embedded reports because they are separate from your application. They give you flexibility because you can copy them to a reporting library to be shared among many applications.

Embedded Reports

When you create a report within a Windows application, .NET automatically creates both the report (an .rpt file) and a report class within the current project. The report class has the same name as the report file (without the .rpt extension). Reports that are referenced by their class name are called embedded reports. To use an embedded report, declare and instantiate an object variable of the report class. This lets you open the report, set its properties, and print it.

Unfortunately, embedded reports are not available for ASP.NET applications. When you create a report in ASP.NET, it creates a separate .rpt file and nothing else. In previous versions of Visual Studio 2002 and 2003, embedded reports were available for both Windows and ASP.NET applications, but not any longer. However, if you upgrade an older project, you can still use the embedded report classes and not change your code. But, any new reports that you create will not have the associated report classes created for you.

Non-Embedded -VS- Embedded Reports

Each report type has its own benefits and drawbacks. Non-embedded reports are useful for applications that let the user choose from a dynamic list of reports. An example of this is when the user browses to a directory location and selects which report to print. You can also use non-embedded reports to share reports between different applications. This lets you create a reporting library that is shared on the network. Another benefit is that if you distribute an application and later find that you have to modify a report, you can change the report without rebuilding the application.

A drawback of using non-embedded reports is that when deploying your application you have to remember to include each report file in the deployment project (unless it’s stored on the network). If you are writing an ASP.NET application, you also have to make sure that the security settings let you access the report. If you forget either of these steps, you’ll wonder why your application runs but printing reports gives you errors.

Embedde reports are the easiest to work with in your application. Since the class is already part of your project, it is pretty simple to reference it by name. You also get the benefit of having the report compiled within the application’s executable and you don’t have to distribute the report file. However, there are two limitations to using embedded reports. First is that you can’t reference reports designed by other applications or by the Crystal Reports stand-alone designer (e.g. Crystal Reports 2008). The second drawback is that modifying a report requires you to recompile and redistribute the application’s executable to your users.

Report types are not mutually exclusive within an application. Choosing to open a report as an embedded report doesn’t mean you can’t open other reports as non-embedded reports. For example, your application can have a set of embedded reports built specifically for that application, but it can also reference non-embedded reports stored in a shared reporting library. Each report can be opened in the way that is best suited for it.

In this chapter, the nuances of non-embedded reports versus embedded reports isn’t as important because you are still at the beginning stages of learning how to integrate Crystal Reports into your application. The CrystalReportDocument control doesn’t differentiate between the two because it lets you select either one as the report source. It hides the complexities from you. This topic is much more important in Part II of the book where we look at how to do runtime report customization using the ReportDocument object model. Starting in Chapter 14, we’ll look at how to write the code which opens a report manually and modifies its properties. This is where the choice between non-embedded and embedded reports becomes more significant.