Should I Use Embedded or Non-embedded Reports?

When you plan an application to build with the Crystal Reports SDK, one of your most important considerations is whether to use embedded or non-embedded reports. Learning the SDK fundamentals that affect report embedding helps you to choose the best structure for your Crystal Reports for Visual Studio project.

What is the difference between embedded and non-embedded reports?

An embedded report is a report that has been imported into, or created within, a Visual Studio project. When a report is embedded into the project, a wrapper class is automatically generated for the report.

A non-embedded report is a report that is external to the Visual Studio project. You can use many ways to access the report and load it into an object model (to enable programmatic interaction with the report), but the report always remains external to the project.

How does an embedded report work?

When the report is imported into or created within the project, a wrapper class (of the same name as the report) is created. This wrapper class wraps, or represents, the report in the project. Once this occurs, all code in the project interacts with the report class that has been created to represent the report, rather than with the original report file itself.

When you compile the project, both the report and its wrapper class are embedded into the assembly, the same as with any other project resource.

A report wrapper class extends from the common base class ReportDocument. It inherits all of ReportDocument 's properties and methods.

Note

Previous versions of this documentation referred to embedded reports as "strongly-typed". The term now used to refer to a report that is added or imported into a Visual Studio project is "embedded."

ReportDocument is the root class of the ReportDocument object model.

How does a non-embedded report work?

A non-embedded report is always accessed externally and made accessible to the SDK in various ways:

• The report may be located on the hard drive along a file directory path (see Binding to a File Directory Path in Code).
• The report may be exposed as a Report Web Service (see Binding to a Report Web Service URL).
• The report may be one of a group of reports that are exposed through Crystal Services (see CrystalReportViewer Binding Scenarios that Use Crystal Services).

Non-embedded reports are never imported into the project and, therefore, a report wrapper class is never created (unlike embedded reports). Instead, the non-embedded report is loaded into one of the object models at runtime, in each their own way:

• The ReportDocument object model uses the ReportDocument.Load() method to load the report into the ReportDocument object model.

  Note

  This only works for reports located on a file directory path.

• The CrystalReportViewer object model uses the CrystalReportViewer.ReportSource property to bind the report directly to the control.

  Note

  The use of the ReportDocument object model is preferred. See Which Object Model Should I Use? for more information.

When to choose embedded or non-embedded reports

If you want to simplify deployment of your project, use embedded reports. You'll have fewer files to work with and no concern about reports being misplaced into the wrong file directory path. This solution also offers more security, in that the reports are not exposed for modifications.

Also, when you are first learning to develop and deploy Crystal Reports with Visual Studio, it is simply easier to embed the reports. Once reports are embedded, they always exist as a class in the project, and are available from IntelliSense and visible in the Object Browser. You don't have to worry about reports being moved or deleted in your file directory, or having to spell the path correctly.

Embedded reports offer simplicity and security, but add labor. They cannot be modified without recompiling the entire project. If reports must be modified regularly, keep the reports non-embedded to make it easy to access and modify them, with no concerns about the need to recompile the assemblies each time. Additionally, there are limits to how large an embedded report can be. You compile an extremelly large report as an embedded resource.

Also, non-embedded reports offer advantages in scalability.

Web sites in Crystal Reports for Visual Studio 2005 and Crystal Reports Basic for Visual Studio 2008 will only work with a non-embedded report.

The scenarios on report binding show you many ways to bind embedded and non-embedded reports (see Which Report Binding Scenario Should I Use?). You'll also see how you can use ReportDocument as your generic class for either type of report. This enables you to keep code changes to a minimum, should you decide to switch approaches.