Share via

Adding Code-Checking Rules to the Code Advisor for Visual Basic 6

 

February 2003

Applies to:
   Visual Basic 6.0
   Visual Basic .NET

Summary: This article demonstrates how to add new code-checking rules to the Code Advisor for Visual Basic 6.0. The Code Advisor includes a set of rules for checking many common issues related to coding standards and upgrading. The Code Advisor Rule Development application allows you to add rules for other issues as needed. (6 pages)

Download the Code Advisor for Visual Basic 6.0 at the Microsoft Download Center.

Contents

Introduction
Creating a New Rule
Testing the New Rule
Distributing Rules
Appendix A: Text Search Handler

Introduction

The Code Advisor for Visual Basic 6 is an add-in that reviews code and flags issues in Visual Basic 6 projects that might be upgraded to Visual Basic .NET. The add-in evaluates the code within a project or module using an extensible set of rules, and then inserts "FixIt" remarks in the code. You can define new rules using the Code Advisor Rule Development application.

The Code Advisor has an extensible architecture based on two key concepts: rules and handlers.

A rule is a set of persisted parameter values and a reference to a handler that searches Visual Basic 6 projects for issues that meet the criteria defined in the rule. For example, one rule is named "Non-zero lower bound arrays." This rule finds instances of arrays that have a non-zero lower bound. When a line of code that meets this criterion is found, a comment is inserted above it, and the issue is listed in a report that the user can view for each project. Some rules relate to issues that do not appear in code; those rules only insert a remark in the report.

A handler is an COM DLL that provides an interface that rules can implement. All Code Advisor handlers are implemented as Visual Basic .dll files that have access to the VB6 extensibility object model and to a library of utility procedures provided by the Code Advisor. The Code Advisor Text Search handler is a generic handler that enables you to use VBScript regular expressions to define rules for searching code and inserting remarks.

Creating a New Rule

This example extends the rule set to include a new rule that finds and flags any code that includes usage of the GoSub keyword.

To add a rule

  1. Start the Code Advisor Rule Development application. By default a shortcut to the application will appear on the Start menu in the Code Advisor for Visual Basic 6 group.

    The application displays any custom rules that have been defined. If no custom rules exist, the Rules list box will be empty.

    Note   The Code Advisor Rule Development application is installed when the Complete installation option is selected during setup. If the application was not installed, you will need to uninstall the Code Advisor add-in and reinstall it using the Complete option.

  2. Click the Add button.

  3. In the Add New Rule dialog box, select the New Rule Name field and type GoSub not recommended.

  4. Select the New Rule Description field and type GoSub is not a recommended construct. Use If/Then or Case constructs instead.

  5. Click OK to close the dialog box.

    The new rule is saved and you are now ready to specify the behavior of the rule.

To specify rule behavior

  1. Select the General tab.

  2. In the Rule Severity field, enter 2.

    Severity 2 indicates that the issue is minor. A severity of 1 indicates issues that are major, or architectural issues. The Code Advisor report sorts issues by severity.

  3. Select the Rule Is Active check box.

    This specifies that the rule is active by default. Users can change the active status of a rule at run time by using the FixIt Filter dialog box in the Code Advisor.

  4. In the Applicable Profiles list, select Best Practices and deselect any other profiles.

    This specifies that rule will only be active when the user selects the Best Practices profile.

  5. Select the Handler tab and click the Edit Rule Parameters button. The Text Search Handler Parameters dialog box will be displayed.

  6. In the Target Regular Expression Pattern field, type \bGoSub\b.

    "\bGoSub\b" is a VBScript regular expression; "\b" specifies a whole word search. For more information on regular expressions, search for the article "Microsoft Beefs Up VBScript with Regular Expressions" in the MSDN Library (msdn.microsoft.com/library).

  7. In the Remark field, type GoSub is not a recommended best practice. Please use another language construct.

  8. Select the Insert Remark when target found check box.

    When this check box is selected, a FixIt remark will be inserted if the expression in the Target Regular Expression Pattern field is matched. When this checkbox is not selected, the remark is inserted at the top of the code module only when a match for the regular expression pattern is not found, for example, this is used to insert a remark when Option Explicit is not found.

  9. Deselect the Insert '\M' Target as whole word only checkbox.

    The token \M can be used to insert a matched string into a remark. This check box determines whether the substitutions are based on the first whole word of the match, or the entire match. For example, if the target found is "GoSub SaveFile" (regular expression: \bGoSub\b\s\w), checking this option will substitute "GoSub" only. Without this option checked, "GoSub SaveFile" will be substituted. The example simply hard-codes the full remark, because this rule is only searching for a single string.

  10. Click OK to close the dialog box, and then click the Save button to save your changes.

Testing the New Rule

Now that you have created the new "GoSub" rule, you can test the rule.

To test the new rule

  1. Start Visual Basic 6.

    Note   If Visual Basic 6 is already open, you will need restart Visual Basic or unload and then reload the add-in before the new rule will be available.

  2. Click the FixIt Filter button on the Code Advisor toolbar.

  3. In the FixIt Filter dialog box, verify that the Best Practices platform is selected and the new rule (GoSub not recommended) is checked.

  4. Click OK to close the dialog box.

  5. Create a new procedure that contains a GoSub construct:

    Public Sub TestGoSub()
    If Hour(Now) = 12 Then
        GoSub Noon
    End If
    Exit Sub
Noon:
    MsgBox "Time to eat!"
End Sub

  6. Click the Add FixIts button on the Code Advisor toolbar.

    The GoSub remark ("GoSub is not a recommended best practice. Please use another language construct")****is inserted into your code just above the line that contains GoSub.

  7. Click the View FixIt Report button on the Code Advisor toolbar.

    The GoSub issue shows a severity of 2.

Distributing Rules

Now that your new rule has been created and tested, you may want to share it with other developers. You do this by distributing a .bag file. The Code Advisor uses a file with a .bag extension to store the data related to each rule, making use of Visual Basic's built-in property bag persistence model.

When the Code Advisor add-in is loaded, it searches the installation directory for .bag files. Each .bag file is processed and the rules contained in the .bag file are loaded.

The standard rules that ship with the Code Advisor are defined in a file named LocalRules.bag. Any custom rules created using the Code Advisor Rule Development application are stored in a file named CustomRules.bag.

To distribute rules

  1. In Windows Explorer, navigate to the Code Advisor for Visual Basic 6 directory. The default location is C:\Program Files\Code Advisor for Visual Basic 6.

  2. Copy the CustomRules.bag file to a distribution media such as a floppy disk or a network share.

  3. Rename the file to a unique name (for example, Myrules01.bag) to avoid overwriting the existing CustomRules.bag file on the target machine.

  4. Copy the renamed file to the Code Advisor for Visual Basic 6 directory on the target computer.

    The next time the Code Advisor is loaded, any rules contained in the renamed .bag file will be visible.

Appendix A: Text Search Handler

Any new rules created with the Code Advisor Rule Development tool utilize the Text Search handler. The Text Search handler uses the VBScript RegExp object to perform a regular expression search; a working knowledge of VB Script regular expression syntax and usage is a prerequisite for creating new rules. For more information about VBScript regular expressions, search for the article "Microsoft Beefs Up VBScript with Regular Expressions" in the MSDN Library (msdn.microsoft.com/library).

Note   To support international variable names, avoid using expressions that include "\w" to specify a whole-word match. This pattern will not work as expected with certain Unicode characters.

Tip   By default, VBScript regular expressions are case-sensitive. To ignore case, you can set the IgnoreCase property of the VBScript RegExp object to True.

The Text Search handler is used by several of the standard rules that ship with the Code Advisor. The following examples show the parameters for those rules; they correspond to what you would see in the Parameters Summary field in the Code Advisor Rule Development tool for your own rules. The Target parameter is the regular expression for the rule.

Missing Option Explicit

Target="Option Explicit"
Remark="Use Option Explicit to avoid implicitly creating variables of type Variant"
RemOnMatch="False"
TargetWholeWord="False"

Non Zero Lowerbound Arrays Not Supported

Target="(?:(Dim|Private|Public|Dim WithEvents|Private WithEvents|Public WithEvents|ReDim|ReDim Preserve|Static) \S+\(([^0].*|.*[^0]) To .*)"
Remark="Non Zero lowerbound arrays are not supported in Visual Basic .NET"
RemOnMatch="True"
TargetWholeWord="False"

As Any Not Supported

Target="\(.*As Any.*\)"
Remark="As Any is not supported in Visual Basic .NET. Use a specific type"
RemOnMatch="True"
TargetWholeWord="False"

Keyword Not Supported

Target="(\bRightB\$?\()|(\bLeftB\$?\()|(\bMidB\$?\()|(\bChrB\$?\()|(\bChrW\$?\()|(\bDefBool \S+)|(\bDefByte \S+)|(\bDefInt \S+)|(\bDefLng \S+)|(\bDefCur \S+)|(\bDefSng \S+)|(\bDefDbl \S+)|(\bDefDec \S+)|(\bDefDate \S+)|(\bDefStr \S+)|(\bDefObj \S+)|(\bDefVar \S+)|(\bDefBool \S+)|(\bDefByte \S+)|(\bDefInt \S+)|(\bDefLng \S+)|(\bDefCur \S+)|(\bDefSng \S+)|(\bDefDbl \S+)|(\bDefDec \S+)|(\bDefDate \S+)|(\bDefStr \S+)|(\bDefObj \S+)|(\bDefVar \S+)|(?:\bObjPtr\()|(?:\bVarPtr\()|(?:\bStrPtr\()|(?:\bGoSub \S+)"
Remark="Keyword '\M' not supported in Visual Basic .NET"
RemOnMatch="True"
TargetWholeWord="True"

Return Has New Meaning

Target="\bReturn(\s.*|$)"
Remark="Return has new meaning in Visual Basic .NET"
RemOnMatch="True"
TargetWholeWord="True"

Option Base 1 is not supported

Target="(?:\bOption Base 1)"
Remark="Option Base 1' is not supported in Visual Basic .NET"
RemOnMatch="True"
TargetWholeWord="False"

On ... GoTo is not supported

Target="(?:\bOn\s[^E]+[^r]*[^r]*[^o]*[^r]*\sGoTo\s)"
Remark="On ... GoTo' is not supported in Visual Basic .NET"
RemOnMatch="True"
TargetWholeWord="False"

#If Blocks are not reliably upgraded

Target="#If|#End If|#ElseIf|#Else"
Remark="'\M' not upgraded reliably to Visual Basic .NET"
RemOnMatch="True"
TargetWholeWord="False"

Printer Object and Printers Collection Not Upgraded

Target="\bPrinters\b|\bAs Printer\b|\bSet Printer\b| = Printer\b|\bPrinter\b.\w+"
Remark="Printer object and Printers collection not upgraded to Visual Basic .NET by the Upgrade Wizard."
RemOnMatch="True"
TargetWholeWord="False"

Forms Collection Not Upgraded

Target="\bForms\b "
Remark="Forms collection not upgraded to Visual Basic .NET by the Upgrade Wizard."
RemOnMatch="True"
TargetWholeWord="False"

Clipboard Not Upgraded

Target="(\bClipboard\b[.])|(\S+\sAs\s\bClipboard\b)"
Remark="Clipboard object not upgraded to Visual Basic .NET by the Upgrade Wizard."
RemOnMatch="True"
TargetWholeWord="False"