From 6cf6dcf1d053bd5d2749761292fc24b5f271b34b Mon Sep 17 00:00:00 2001 From: Keith Hill Date: Sat, 2 Apr 2016 18:18:27 -0600 Subject: [PATCH] Changed section on Profile support to use Setting instead. --- README.md | 93 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 57 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index b272eeee5..df8d7587d 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ Installation ```powershell Import-Module PSScriptAnalyzer ``` -If you have previous version of PSScriptAnalyzer installed on your machine, you may need to override old binaries by copying content of [``~/ProjectRoot/PSScriptAnalyzer``] to PSModulePath. +If you have previous version of PSScriptAnalyzer installed on your machine, you may need to override old binaries by copying content of [``~/ProjectRoot/PSScriptAnalyzer``] to PSModulePath. To confirm installation: run ```Get-ScriptAnalyzerRule``` in the PowerShell console to obtain the built-in rules @@ -78,11 +78,11 @@ You can suppress a rule by decorating a script/function or script/function param param() Write-Verbose -Message "I'm making a difference!" - + } - + All rule violations within the scope of the script/function/parameter you decorate will be suppressed. - + To suppress a message on a specific parameter, set the `SuppressMessageAttribute`'s `CheckId` parameter to the name of the parameter: function SuppressTwoVariables() @@ -100,14 +100,14 @@ Use the `SuppressMessageAttribute`'s `Scope` property to limit rule suppression [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideCommentHelp", "", Scope="Function")] param( ) - + function InternalFunction { param() - + Write-Verbose -Message "I am invincible!" } - + The above example demonstrates how to suppress rule violations for internal functions using the `SuppressMessageAttribute`'s `Scope` property. You can further restrict suppression based on a function/parameter/class/variable/object's name by setting the `SuppressMessageAttribute's` `Target` property to a regular expression. Any function/parameter/class/variable/object whose name matches the regular expression is skipped. @@ -115,16 +115,16 @@ You can further restrict suppression based on a function/parameter/class/variabl [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPositionalParameters", Scope="Function", Target="PositionalParametersAllowed")] Param( ) - + function PositionalParametersAllowed() { Param([string]$Parameter1) { Write-Verbose $Parameter1 } - + } - + function PositionalParametersNotAllowed() { param([string]$Parameter1) @@ -132,13 +132,13 @@ You can further restrict suppression based on a function/parameter/class/variabl Write-Verbose $Parameter1 } } - + # The script analyzer will skip this violation PositionalParametersAllowed 'value1' - + # The script analyzer will report this violation PositionalParametersNotAllowed 'value1 - + To match all functions/variables/parameters/objects, use `*` as the value of the Target parameter: [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPositionalParameters", Scope="Function", Target="*")] @@ -146,29 +146,50 @@ To match all functions/variables/parameters/objects, use `*` as the value of the ) - -Profile support in ScriptAnalyzer +Settings Support in ScriptAnalyzer ======================================== -Profiles that describe ScriptAnalyzer rules to include/exclude based on `Severity` can be created and supplied to `Invoke-ScriptAnalyzer` using the `-profile` parameter. This enables a user to create custom configuration for a specific environment. +Settings that describe ScriptAnalyzer rules to include/exclude based on `Severity` can be created and supplied to +`Invoke-ScriptAnalyzer` using the `-Setting` parameter. This enables a user to create a custom configuration for a specific environment. + +Using Settings support: -Using Profile support: +The following example excludes two rules from the default set of rules and any rule +that does not output an Error or Warning diagnostic record. ```powershell -$myProfile = @{ - Severity='Warning' - IncludeRules=@('PSAvoidUsingCmdletAliases', - 'PSAvoidUsingPositionalParameters', - 'PSAvoidUsingInternalURLs' - 'PSAvoidUninitializedVariable') - ExcludeRules=@('PSAvoidUsingCmdletAliases' - 'PSAvoidUninitializedVariable') +# ScriptAnalyzerSettings.psd1 +@{ + Severity=@('Error','Warning') + ExcludeRules=@('PSAvoidUsingCmdletAliases', + 'PSAvoidUsingWriteHost') } +``` + +Then invoke that settings file when using `Invoke-ScriptAnalyzer`: + +```powershell +Invoke-ScriptAnalyzer -Path MyScript.ps1 -Setting ScriptAnalyzerSettings.psd1 +``` + +The next example selects a few rules to execute instead of all the default rules. + +```powershell +# ScriptAnalyzerSettings.psd1 +@{ + IncludeRules=@('PSAvoidUsingPlainTextForPassword', + 'PSAvoidUsingConvertToSecureStringWithPlainText') +} +``` + +Then invoke that settings file when using `Invoke-ScriptAnalyzer`: -Invoke-ScriptAnalyzer -path MyScript.ps1 -Profile $myProfile +```powershell +Invoke-ScriptAnalyzer -Path MyScript.ps1 -Setting ScriptAnalyzerSettings.psd1 ``` -ScriptAnalyzer as a .net library + +ScriptAnalyzer as a .NET library ================================ ScriptAnalyzer engine and functionality can now be directly consumed as a library. @@ -179,18 +200,18 @@ Here are the public interfaces: using Microsoft.Windows.PowerShell.ScriptAnalyzer; public void Initialize(System.Management.Automation.Runspaces.Runspace runspace, -Microsoft.Windows.PowerShell.ScriptAnalyzer.IOutputWriter outputWriter, -[string[] customizedRulePath = null], -[string[] includeRuleNames = null], -[string[] excludeRuleNames = null], -[string[] severity = null], -[bool suppressedOnly = false], +Microsoft.Windows.PowerShell.ScriptAnalyzer.IOutputWriter outputWriter, +[string[] customizedRulePath = null], +[string[] includeRuleNames = null], +[string[] excludeRuleNames = null], +[string[] severity = null], +[bool suppressedOnly = false], [string profile = null]) -public System.Collections.Generic.IEnumerable AnalyzePath(string path, +public System.Collections.Generic.IEnumerable AnalyzePath(string path, [bool searchRecursively = false]) -public System.Collections.Generic.IEnumerable GetRule(string[] moduleNames, +public System.Collections.Generic.IEnumerable GetRule(string[] moduleNames, string[] ruleNames) ``` @@ -215,7 +236,7 @@ Pester-based ScriptAnalyzer Tests are located in ```/PSScriptAnalyzer/Te * Run Tests for Built-in rules: .\*.ps1 (Example - .\ AvoidConvertToSecureStringWithPlainText.ps1) *You can also run all tests under \Engine or \Rules by calling Invoke-Pester in the Engine/Rules directory. - + Project Management Dashboard ==============================