Implementing the IRenderingExtension Interface

As described earlier in this section, the rendering extension is responsible for taking the results from a report definition that is combined with the actual data, and rendering the resulting data to a format that is useable. The transformation of the combined data and formatting is done through a common language runtime (CLR) class that implements IRenderingExtension, which transforms the object model into an output format consumable by a viewer, printer, or other output target.

The IRenderingExtension has three methods that must be coded. They are:

• Render Method - renders the report.
• RenderStream Method - renders a specific stream from the report.
• GetRenderingResource Method - gets additional information, like icons, needed for the report.

The following sections discuss these methods in more detail.

Render Method

The Render method contains arguments that represent the following objects:

• The report itself that you want to render. This object contains properties, data, and layout information for the report. The report is the root of the report object model tree.
• The reportServerParameters containing the string dictionary object, with the parameters for the report server, if any.
• The deviceInfo parameters containing the device settings. For more information on device settings, see Reporting Services Device Information Settings.
  The clientCapabilities parameter which contains a NameValueCollection dictionary object that has information about the client to which you are rendering.
• The EvaluateHeaderFooterExpressions delegate is called if the page header or the footer is dependent on the contents of the page. That is, there are times when the header or footer contains totals or aggregation of data that is contained in the report. For more information on this delegate, see EvaluateHeaderFooterExpressions Delegate in SQL Server Books Online.
• The createAndRegisterStream is a delegate function to be called to get a stream to render into.

deviceInfo Parameter

The deviceInfo contains rendering parameters, not report parameters. These rendering parameters are passed to the rendering extension. The deviceInfo values are converted into a NameValueCollection object by the report server. Items in the deviceInfo parameter are treated as case-insensitive values. If the render request came as a result of URL access, the URL parameters in the form rc:key=value are converted to key/value pairs in the deviceInfo dictionary object. The browser detection code also provides the following items in the clientCapabilities dictionary: EcmaScriptVersion, JavaScript, MajorVersion, MinorVersion, Win32, Type, and AcceptLanguage. Any name/value pair in the deviceInfo that is not understood by the rendering extension is ignored. The following code sample shows a sample GetRenderingResource method that retrieves icons.

public void GetRenderingResource (CreateStream createStreamCallback, NameValueCollection deviceInfo)
{
    string[] iconTagValues = deviceInfo.GetValues("Icon");
    if ((iconTagValues != null) && (iconTagValues.Length > 0) )
    {
        // Create a stream to output to.
        Stream outputStream = createStreamCallback(m_iconResourceName, "gif", null, "image/gif", false);
        // Get the GIF image for one of the buttons on the toolbar
        Image requiredImage = (Image) m_resourcemanager.GetObject(m_iconResourceName
        // Write the image to the output stream
        requiredImage.Save(outputStream, requiredImage.RawFormat);
    }
    return;
}

RenderStream Method

The RenderStream method renders a particular stream from the report. All streams are created during the initial Render call, but the streams are not returned to the client initially. This method is used to secondary streams (like images in HTML rendering) or additional pages of a multi-page rendering extension (like Image/EMF).

GetRenderingResource Method

There are times when the report requires information that does not require the report itself to be rendered. For example, if you need the icon associated with the rendering extension, use the deviceInfo parameter containing the single tag <Icon>. In these cases, you can use the GetRenderingResource method. This method retrieves the information without executing an entire rendering of the report.

Additional Classes to Implement or Override

In the inheritance hierarchy of a report, the ReportItem class is the abstract base class that represents a single item on the report. It is the base class that the classes representing the more detailed objects on the report inherit from, such as:

• DataRegion
• Image (also inherits from interface IImage)
• Textbox
• Line
• Subreport
• PageSection
• Rectangle

From the DataRegion class, the following classes are further inherited:

• Chart
• List
• Matrix
• Table

For more information on the classes that inherit from ReportItem and DataRegion, see Microsoft.ReportingServices.ReportRendering.

See Also

Concepts

Implementing a Rendering Extension
Introducing Rendering Extensions

Help and Information

Getting SQL Server 2005 Assistance