This article will explain how to create a custom ruleset, which can be used in SPCAF.
SPCAF by default comes with 7 standard rulesets that cover the general requirements needed to scan the majority of files. However, we do recommend that you create your own custom ruleset to be used for analyzing your specific project. This means you can ignore specific files/folders, use which rules you want and set the desired severity of these rules.
Although a custom ruleset can be created by .xml we do recommend our settings editor which is automatically installed with the client application. If you are not using the client application the settings editor can be download here. Run the installer to install the settings editor.
You can either create a new ruleset from scratch or edit an existing one. We advise starting by editing an existing ruleset so that you have the foundation already in place. Later on, you can create a new ruleset from the ground up.
Editing a Ruleset using the Settings Editor Tool
You now have our Settings Editor Tool and by default, if you use our client app you have the standard ruleset. If you do not use our client app you can get the current release of our rulesets here.
Unless your project is specifically an Angular or SharePoint Framework project we recommend using the Extended Recommended Rules ruleset as a starting point.
- You can run the "SPCAF.SettingsEditor.exe" directly in the installation directory of SPCAF or in your start menu (depending on your installation).
- Once the editor tool has loaded click on the 2nd icon in the top right corner as shown below.
- Make sure that the folder path is set to "C:\Program Files (x86)\Rencore\SPCAF\RuleSets" (default installation folder) then select "RS10_ExtendedRecommendedRules.spruleset" and click "Open". This will now load up the Default ruleset used by SPCAF with all the specific rules enabled with the default severity and ignore list.
- Change the Title of the new ruleset, give it a brief description in the "General Settings" (see General Settings below for more details).
- Set the list of Ignored files/folders at the bottom of the "General Settings" (see General Settings below for more details).
- In the "Analyzers and Reports" section enable or disable the Analyzers (rules) that you want or do not want to use during analysis (see Analyzers and Reports below for more details).
- Also in the "Analyzers and Reports" section disable any reports that you do not want to appear in the results (see Analyzers and Reports below for more details).
- In the "Configuration and Details" you can amend the severity rating for the reported analyzer or additional parameters (where permitted).
- Once done click on the save icon (shown below) at the top right and choose a location and file name.
The left side of the screen is the general settings of the ruleset, here you can change the name of the ruleset and description, once the ruleset has been saved via a new name and path it will also be displayed here.
It is here where you define "Global Properties" which include "ApprovedScriptLocations", "ApprovedSourceLocations" and "IgnoreFiles". If the property is not present add the property by clicking the "Add" button, enter the key and value.
SPCAF uses wildcards for ignoring a selection of files or folders, such as "Aspose.*.dll" for files or "/node_modules/" to exclude folders. Each item you want to exclude must be separated with a semicolon (;). For more details of excluding files please follow the details on the knowledge base article How to: Exclude files from the analysis.
The final section of the "Global Properties" is where you dictate whether new rules that may be generated by Rencore in new releases of SPCAF get added to the ruleset.
- Only load enabled analyzers: This option only loads the selected analyzers (e.g. SPCop, Inventory, etc.), but if new rules appear in these analyzers they are loaded automatically. This option means the ruleset will be updated with the new rules.
- Only load enabled rules: This option defines that only the selected rules in the ruleset should be loaded. New rules are not loaded. This option means the ruleset will not be updated with new rules.
Analyzers and Reports
The center of the "Settings Editor" is where you enable or disable analyzers (rules) and reports via the tabs at the top, which will be applied during analysis.
The default selection will be on "Analyzers", here is where you can:
- Enable or disable whole analyzers (e.g. enable FxCop analyzer).
- Enable or disable a whole category (e.g. disable all 'Best Practices' rules).
- Enable or disable a single rule, metric, dependency, or inventory entry.
The Analyzers, categories, and rules are configured via a hierarchy tree.
The first level of checkboxes permits you to enable or disable an analyzer, categories it contains, and the rules within the categories. To enable the analyzer click on the checkbox to place a tick in it.
Clicking on the arrow next to the analyzer will display the categories for that analyzer. As before the checkbox is how you enable or disable the category and all the rules for that category. To enable the category click on the checkbox to place a tick in it.
Finally, click the arrow next to the category to display the rules with that category. As before the checkbox is how you enable or disable the rule. Additionally, if you were to click on a rule, the details about that rule will be displayed including a link to the documentation for the rule where further information will be shown. For more details what is shown please see the "Configuration and Details" section below.
Selecting the "Reports" tab is where you can:
- Enable/Disable report types e.g. Code Quality Analysis Report
- Configure which sections should show up in the specific Report.
As with Analyzers, the options are organized by a hierarchy tree.
Here you can disable complete sections of a report (Code Dependencies, Code Inventory, Code Metric, Quality Assessment, or SPCAF Analysis Summary) or parts of each section. To disable part of a section or a complete section click on the checkbox and remove the tick.
Configuration and Details
The right side of the "Settings Editor" is the "Configuration and Details" section where you can add additional configuration to the analyzer and view details of the selected element:
- Change the severity of a rule (e.g. from Error to Warning).
- Add comments to a rule, category, or analyzer which appears in the reports (e.g. to provide background information about changed severity).
- Add configuration values (some rules may have additional values that can be entered here).
- View the documentation relating to the rule.