Chapter 22. Implementing Custom Embedded Functions
In This Chapter
• Adding Embedded Code
• Debugging Embedded Code
The simplest form of custom code available in SSRS is expressions, which were discussed in Chapter 8, “Expressions.” The next level of coding complexity is a custom embedded code in a report.
Adding Embedded Code
To get a better understanding of how embedded custom code is used in a report, report developers can assume all of the code placed in the code window gets compiled into a make-believe class called Code. You can add properties and methods to the make-believe Code class, and call class members from expressions in the report, which has the class defined.
Embedded code is compiled into a report’s intermediate format and gets executed as needed when the report is rendered. Report Designer provides a simple text area to allow editing of the embedded code. To access the code editor, complete the following steps:
• Use the Report, Report Properties menu (if the Report menu is not available, click within the report design area). Alternatively, right-click on the area surrounding the report’s body and select the Properties menu.
• Click the Code tab in the Report Properties dialog box.
You should see a window similar to Figure 22.1 and can type the code in the Custom code area.
The code editor is basically a multiline text box, and it does not provide any productivity assistance, such as Intellisense or debugging. You have to be extremely careful while using this code editor. For example, only one level of “undo” action is allowed, as compared to Visual Studio’s infinite undo.
For all of its difficulties, embedded code provides several key benefits for a developer, including the following:
• A more elegant approach (as compared to expressions) to medium-complexity coding scenarios
• A single repository for functions and methods that can be reused by multiple items within a single report, as opposed to complex copy-and-paste expressions
• Direct access to the exception handling functionality of VB.NET
Every developer knows function reuse is beneficial over copy-and-paste programming. Take the following fictitious example. Suppose two developers were assigned the parallel development of a single report. One developer used embedded code, whereas the other one used simple expressions. One of the initial goals was to highlight negative values in red. Later, this goal changed to a more complex requirement, such as color-coding numeric ranges. The developer who used embedded code could adapt to the change in requirements quickly, and would make his manager happy, probably getting a bonus in the process.
Embedded functions must be written in VB.NET. If you prefer C#, you would have to develop a custom assembly. This topic is covered in Chapter 23, “How to Create and Call a Custom Assembly from a Report.”
The following steps add the function used in the preceding narrative:
1. Open the report properties by either clicking the Report, Report Properties menu, or right-clicking on the area surrounding the report’s body and selecting Properties.
2. In the Report Properties dialog box, click the Code tab and enter the following-function:
Function Highlight(value As Integer) As String
If value < 0
return "Red"
Else
return "Black"
End If
End Function
3. Drag a Textbox from the Toolbox to the report and place the following code in the Background Color property:
=Code.Highlight(me.value)
4. Place −1 (minus one) in the Value property.
5. Open the report in Preview mode to see the text box with a red background.
Debugging Embedded Code
SSRS does not provide any facilities to step through the embedded code, and, thus, you have two options: You can either debug code in Visual Studio .NET or use some pre—Visual Basic tricks for debugging. The first trick is to label code lines. This is beneficial to locate both compile-time and runtime errors. The following code fragment shows how to label code lines. It also has errors that have been intentionally placed for demonstration purposes.
Function Add(n As Integer)
1: i = i + n
2: return i
End Function
When you build a report with the code snippet or try to preview the report that calls this code, SSRS reports two issues (one warning and one error):
• Warning—There is an error on line 0 of the custom code: [BC42021] Function without an ‘As’ clause; return type of Object assumed. Warnings are only displayed if at least one error is found.
• Error—There is an error on line 1 of the custom code:[BC30451] Name ‘i’ is not declared. Only the first error is displayed.
With a small code fragment such as the preceding example, finding errors might not be an issue. For a code fragment that has a significant number of lines, locating the one with an error can be a burden.
Note
Keep in mind that labels can only be present inside of functions or subroutines and can repeat inside of different functions.
Tip
To properly determine line numbers, deliberately add an error and preview the report. The SSRS error indicates the line number.
Tip
To avoid laborious efforts of numbering and renumbering of lines, you should only label key expressions or the first line of functions. Alternatively, you can use labeling to narrow down a line with an error.
The second trick is to locate a line that causes runtime errors by using a TRY-CATCH block:
Function DivByZero()
Dim x As Integer
Try ' Set up structured error handling.
3: x = x/ 0
Catch ex As Exception
Return ex.ToString() & vbCrLf & "Exception at Line: " & CStr(Erl)
End Try
End Function
The result of the call to the function DivByZero() is
System.OverflowException: Arithmetic operation resulted in an overflow.
at ReportExprHostImpl.CustomCodeProxy.DivByZero()
Exception at Line: 3
Note that function DivByZero() uses the undocumented function Erl to return a line number for the line of code that produced the error. Erl really returns a label number (in the preceding code, it is 3).
When you do not implement error handling, and then make a call to a function within the Value property of a report item, the report item shows “#Error” as a result.
Depending on the precision of a return value provided from a function, other potential results are “Infinity” or “NaN”(Not a Number).
Tip
Always check the Error List window after a Build operation has completed, and make sure that there are no warnings. Best practice suggests eliminating all warnings in production code.
Exceptions within other properties can be caught during the Build operation.
Summary
Custom embedded code can provide a more elegant approach to medium-complexity custom code than expressions through function reuse, centralized code repository, and additional error-handling options.
Custom embedded code is a VB.NET code embedded in a report. A code is embedded as a part of a report definition (RDL) file and compiled together with the container report. Many errors are caught by the compiler when a reporting solution is built.
Although embedded code allows a developer to use full object-oriented functionality of VB.NET, embedded code is mostly used for simple logic. It is possible to develop complex embedded code, but this is not usually done due to limited debugging facilities and limited functionality of the embedded code editor. The embedded code editor is a simple text box that does not have advanced features, such as code completion, available in Visual Studio.
When functions are too complicated for embedded code to handle efficiently or you have a preference to use C# instead of Visual Basic, you can develop and call a custom assembly from a report. The next chapter explains how to leverage a custom assembly within a report.