Merge pull request #490 from rkeithhill/rkeithhill/fix-readme-profile-sample2

Changed section on Profile support to use Setting instead.

Author: Kapil Borle

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,75 +100,96 @@ 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.
 
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPositionalParameters", Scope="Function", Target="PositionalParametersAllowed")]
     Param(
     )
-     
+
     function PositionalParametersAllowed()
     {
         Param([string]$Parameter1)
         {
             Write-Verbose $Parameter1
         }
-    
+
     }
-    
+
     function PositionalParametersNotAllowed()
     {
         param([string]$Parameter1)
         {
             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="*")]
     Param(
     )
 
 
-
-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<DiagnosticRecord> AnalyzePath(string path, 
+public System.Collections.Generic.IEnumerable<DiagnosticRecord> AnalyzePath(string path,
 [bool searchRecursively = false])
 
-public System.Collections.Generic.IEnumerable<IRule> GetRule(string[] moduleNames, 
+public System.Collections.Generic.IEnumerable<IRule> GetRule(string[] moduleNames,
 string[] ruleNames)
 ```
 
@@ -215,7 +236,7 @@ Pester-based ScriptAnalyzer Tests are located in ```<branch>/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
 ==============================