diff --git a/reference/docfx.json b/reference/docfx.json index e07ef33..a8ab37e 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -47,6 +47,7 @@ "docs-conceptual/PSScriptAnalyzer/Rules/**": "language-reference" }, "ms.update-cycle": { + "docs-conceptual/AIShell/**": "1825-days", "docs-conceptual/Crescendo/**": "1825-days", "docs-conceptual/SecretManagement/**": "1825-days", "docs-conceptual/SecretStore/**": "1825-days", @@ -76,6 +77,7 @@ "ms.devlang": "powershell", "ms.service": "powershell", "ms.tgt_pltfr": "windows, macos, linux", + "ms.update-cycle": "365-days", "products": [ "https://authoring-docs-microsoft.poolparty.biz/devrel/8bce367e-2e90-4b56-9ed5-5e4e9f3a2dc3" ], "social_image_url": "https://learn.microsoft.com/media/logos/logo-powershell-social.png", "titleSuffix": "PowerShell", diff --git a/reference/docs-conceptual/PSScriptAnalyzer/create-custom-rule.md b/reference/docs-conceptual/PSScriptAnalyzer/create-custom-rule.md index f052562..748d200 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/create-custom-rule.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/create-custom-rule.md @@ -1,6 +1,6 @@ --- description: This article provides a basic guide for creating your own customized rules. -ms.date: 06/28/2023 +ms.date: 01/28/2026 title: Creating custom rules --- # Creating custom rules @@ -8,8 +8,8 @@ title: Creating custom rules PSScriptAnalyzer uses the [Managed Extensibility Framework (MEF)][01] to import all rules defined in the assembly. It can also consume rules written in PowerShell scripts. -When calling `Invoke-ScriptAnalyzer`, users can specify custom rules using the -**CustomizedRulePath** parameter. +Users can specify custom rules using the **CustomizedRulePath** parameter of the +`Invoke-ScriptAnalyzer` cmdlet. This article provides a basic guide for creating your own customized rules. @@ -17,7 +17,7 @@ This article provides a basic guide for creating your own customized rules. ### Functions should have comment-based help -Include the `.DESCRIPTION` field. This becomes the description for the customized rule. +Include the `.DESCRIPTION` field. This field becomes the description for the customized rule. ```powershell <# @@ -114,7 +114,9 @@ $suggestedCorrections.add($correctionExtent) | Out-Null } ``` -### Make sure you export the function(s) +### Make sure you export the function + +You must export the functions you create so that PSScriptAnalyzer can find them. ```powershell Export-ModuleMember -Function (FunctionName) diff --git a/reference/docs-conceptual/PSScriptAnalyzer/overview.md b/reference/docs-conceptual/PSScriptAnalyzer/overview.md index 2b96ac9..e29d96d 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/overview.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/overview.md @@ -1,6 +1,6 @@ --- description: This article explains the purpose of the PSScriptAnalyzer module. -ms.date: 10/10/2024 +ms.date: 01/28/2026 title: PSScriptAnalyzer module --- # PSScriptAnalyzer module @@ -20,8 +20,8 @@ PowerShell code such as: - And many more You can choose the rules to include or exclude for your modules and scripts. PSScriptAnalyzer can -also fix the formatting of your code. This helps you produce code that conforms to a standard style, -is easier to read, and is more maintainable. +also fix the formatting of your code. Formatting helps you produce code that conforms to a standard +style that is more maintainable and easier to read. ## Installing PSScriptAnalyzer diff --git a/reference/docs-conceptual/PSScriptAnalyzer/rules-recommendations.md b/reference/docs-conceptual/PSScriptAnalyzer/rules-recommendations.md index 85673de..2fe2033 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/rules-recommendations.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/rules-recommendations.md @@ -1,15 +1,15 @@ --- description: This article lists best-practice recommendations and the rules associated with them. -ms.date: 12/03/2024 +ms.date: 01/28/2026 title: PSScriptAnalyzer rules and recommendations --- # PSScriptAnalyzer rules and recommendations The following guidelines come from a combined effort from both the PowerShell team and the -community. The guidelines are organized by type. Within each type there is a list of rules. The +community. The guidelines are organized by type. Within each type, there's a list of rules. The rules are grouped by the **Severity** defined in the implementation of the **PSScriptAnalyzer** -rule. The severity level labeled as 'TBD' means "To be determined". These are recommendations that -don't currently have rules defined. +rule. The severity level labeled `TBD` means "To be determined." Items labeled as TBD are +recommendations that don't currently have rules defined. ## Cmdlet Design Rules @@ -42,8 +42,8 @@ No rules defined. - Support **Force** parameter for interactive sessions. If your cmdlet is used interactively, always provide a **Force** parameter to override the interactive actions, such as prompts or reading - lines of input. This is important because it allows your cmdlet to be used in non-interactive - scripts and hosts. The following methods can be implemented by an interactive host. + lines of input. The **Force** parameter is important because it allows your cmdlet to be used in + non-interactive scripts and hosts. - Document output objects - Module must be loadable - No syntax errors @@ -85,7 +85,7 @@ No rules defined. - Avoid using UNC file paths - Error Handling - Use `-ErrorAction Stop` when calling cmdlets - - Use `$ErrorActionPreference = 'Stop'/'Continue'` when calling non-cmdlets + - Use `$ErrorActionPreference` set to `Stop` or `Continue` when calling noncmdlets - Avoid using flags to handle errors - Avoid using `$?` - Avoid testing for a null variable as an error condition @@ -142,7 +142,7 @@ No rules defined. ### Severity: TBD -- Avoid initializing APIKey and Credentials variables (information disclosure) +- Avoid initializing API key and credential variables (information disclosure) ## DSC Related Rules @@ -168,13 +168,14 @@ No rules defined. ### Severity: TBD -- For Windows PowerShell v4, resource modules should have a `.psd1` file and `schema.mof` for every +- For Windows PowerShell v4, resource modules should have a `.psd1` and `schema.mof` file for every resource -- MOFs should have a description for each element - see [Issue #131][131] - Resource modules should have a `.psd1` file (always) and `schema.mof` (for non-class resource) see [Issue #116][116] +- Resource module should have a DscResources folder that contains the resources - see + [Issue #130][130] +- MOFs should have a description for each element - see [Issue #131][131] - Use **ShouldProcess** for a **Set** DSC method -- Resource module contains DscResources folder which contains the resources - see [Issue #130][130] ### References diff --git a/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md b/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md index e9dea39..606335d 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/using-scriptanalyzer.md @@ -1,6 +1,6 @@ --- description: This article describes various features of PSScriptAnalyzer and how to use them. -ms.date: 04/26/2024 +ms.date: 01/28/2026 title: Using PSScriptAnalyzer --- # Using PSScriptAnalyzer @@ -104,7 +104,7 @@ function InternalFunction } ``` -You can further restrict suppression based on a function, parameter, class, variable or object's +You can further restrict suppression based on a function, parameter, class, variable, or object's name by setting the **Target** property of **SuppressMessageAttribute** to a regular expression or a wildcard pattern. @@ -155,8 +155,8 @@ Param() You can create settings that describe the ScriptAnalyzer rules to include or exclude based on **Severity**. Use the **Settings** parameter of `Invoke-ScriptAnalyzer` to specify configuration. -This enables you to create a custom configuration for a specific environment. We support the -following modes for specifying the settings file: +The **Settings** parameter allows you to create a custom configuration for a specific environment. +ScriptAnalyzer support the following modes for specifying the settings file: ### Built-in Presets @@ -214,8 +214,8 @@ If you place a settings file named `PSScriptAnalyzerSettings.psd1` in your proje Invoke-ScriptAnalyzer -Path "C:\path\to\project" -Recurse ``` -Note that providing settings explicitly takes higher precedence over this implicit mode. Sample -settings files are provided in the `Settings` folder of the **PSScriptAnalyzer** module. +Providing settings explicitly takes higher precedence over this implicit mode. You can find sample +settings files in the `Settings` folder of the **PSScriptAnalyzer** module. ## Check PowerShell version compatibility @@ -227,8 +227,8 @@ issues: PowerShell environments - [PSUseCompatibleCommands][04] checks whether commands used in a script are available in other PowerShell environments -- [PSUseCompatibleSyntax][05] checks whether a syntax used in a script will work in other PowerShell - versions +- [PSUseCompatibleSyntax][05] checks whether a syntax used in a script is compatible in other + versions of PowerShell - [PSUseCompatibleTypes][06] checks whether .NET types and static methods or properties are available in other PowerShell environments @@ -242,8 +242,8 @@ these paths point either to a module's folder, which implicitly uses the module module's script file (`.psm1`). The module must export the custom rule functions using `Export-ModuleMember` for them to be available to **PSScriptAnalyzer**. -In this example the property **CustomRulePath** points to two different modules. Both modules export -the rule functions with the verb **Measure** so `Measure-*` is used for the property +In this example, the **CustomRulePath** property points to two different modules. Both modules +export the rule functions with the verb **Measure** so `Measure-*` is used for the property **IncludeRules**. ```powershell @@ -283,10 +283,10 @@ otherwise the default rules are used. } ``` -### Using custom rules in Visual Studio Code +### Using custom rules in Visual Studio Code (VS Code) -It's also possible to use the custom rules that are provided in the settings file in Visual Studio -Code. This is done by adding a Visual Studio Code workspace settings file (`.vscode/settings.json`). +You can also use the custom rules that are provided in the settings file in VS Code. Add a VS Code +workspace settings file (`.vscode/settings.json`) with the following contents. ```json { @@ -322,16 +322,16 @@ public System.Collections.Generic.IEnumerable GetRule(string[] moduleName ## Violation Correction -You can use the **Fix** switch to to automatically replace violation-causing content with a -suggested alternative. Additionally, because `Invoke-ScriptAnalyzer` implements -**SupportsShouldProcess**, you can use **WhatIf** or **Confirm** to find out which corrections would -be applied. You should use source control when applying corrections as some changes, such as the one -for **AvoidUsingPlainTextForPassword**, might require additional script modifications that can't be -made automatically. Because initial encoding can't always be preserved when you automatically apply -suggestions, you should check your file's encoding if your scripts depend on a particular encoding. +You can use the **Fix** switch to automatically replace violation-causing content with a suggested +alternative. Additionally, because `Invoke-ScriptAnalyzer` implements **SupportsShouldProcess**, you +can use **WhatIf** or **Confirm** to find out which corrections would be applied. You should use +source control when applying corrections as some changes, such as the one for +**AvoidUsingPlainTextForPassword**, might require other script modifications that can't be made +automatically. Initial encoding can't always be preserved when you automatically apply suggestions. +You should check file encoding if your scripts depend on a particular encoding. The **SuggestedCorrections** property of the error record enables quick-fix scenarios in editors -like VSCode. We provide valid **SuggestedCorrection** for the following rules: +like VS Code. We provide valid **SuggestedCorrection** for the following rules: - **AvoidAlias** - **AvoidUsingPlainTextForPassword** diff --git a/reference/docs-conceptual/PSScriptAnalyzer/whats-new-in-pssa.md b/reference/docs-conceptual/PSScriptAnalyzer/whats-new-in-pssa.md index 8af44e0..1c2ea8c 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/whats-new-in-pssa.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/whats-new-in-pssa.md @@ -1,6 +1,6 @@ --- description: This article lists the updates to the PSScriptAnalyzer module. -ms.date: 04/29/2025 +ms.date: 01/28/2026 title: What's new in PSScriptAnalyzer --- # What's new in PSScriptAnalyzer @@ -18,7 +18,7 @@ Breaking changes New features and updates - Add new options (enabled by default) to formatting rule `UseCorrectCasing` to also correct - operators, keywords and commands + operators, keywords, and commands - `PSAlignAssignmentStatement`: Ignore hashtables with a single key-value pair - Use `RequiredResource` hashtable to specify PowerShell module versions - `PSAvoidAssignmentToAutomaticVariable`: Ignore when a Parameter has an Attribute that contains a @@ -26,7 +26,7 @@ New features and updates - Trim unnecessary trailing spaces from string resources in Strings.resx - Make Settings type detection more robust - Add foreach Assignment to `AvoidAssignmentToAutomaticVariable` -- Do not print summary repeatedly for each logger +- Don't print summary repeatedly for each logger - Set exit code of `Invoke-ScriptAnalyzer -EnableExit` to total number of diagnostics - `Invoke-ScriptAnalyzer`: Stream diagnostics instead of batching - `Invoke-ScriptAnalyzer`: Print summary only once per invocation @@ -52,8 +52,8 @@ when using PowerShell 7 is now `7.2.11`. ### Enhancements - Enable suppression of `PSAvoidAssignmentToAutomaticVariable` for specific variable or parameter -- Upgrade to use .NET 6 since PowerShell 7.0 is now out out of support -- Convert `PSUseSingularNouns` to configurable rule and add `Windows` to allowlist +- Upgrade to use .NET 6 since PowerShell 7.0 is now out of support +- Convert `PSUseSingularNouns` to configurable rule and add `Windows` to the allow list - Allow suppression of `PSUseSingularNouns` for specific function - Add `ErrorView` to `SpecialVars.cs` - Adding `ToString()` methods to `[CorrectionExtent]` and `[DiagnosticRecord]` types @@ -77,7 +77,7 @@ when using PowerShell 7 is now `7.2.11`. - Make messages of `UseCorrectCasing` more detailed - Exclude automatic variable `$FormatEnumerationLimit` from analysis by `PSAvoidGlobalVars` and `PSUseDeclaredVarsMoreThanAssignments` -- `PSAvoidUsingPositionalParameters` - Do not warn on AZ CLI +- `PSAvoidUsingPositionalParameters` - Don't warn on AzCLI ## PSScriptAnalyzer 1.20.0 - 2021-08-20 @@ -90,29 +90,29 @@ when using PowerShell 7 is now `7.2.11`. - Replace unhelpful warning about `process` aliasing `Get-Process` with warning about misused syntax - Fix `FunctionInfo` fallback AST attribute analysis for `UseShouldProcessCorrectly` -- Do not increase indentation after a left parenthesis if the previous token is a newline and the - next token is not a newline +- Don't increase indentation after a left parenthesis if the previous token is a newline and the + next token isn't a newline - `UseConsistentWhitespace` - **CheckOpenBrace** setting to not warn when being preceded by open parenthesis - Implement `-IncludeSuppressions` parameter -- Combine multiple suppressions applied to the same diagnostic +- Combine multiple suppressions that apply to the same diagnostic ## PSScriptAnalyzer 1.19.1 - 2020-07-28 ### New rules -- Add `AvoidUsingDoubleQuotesForConstantString` (disabled by default) to warn about the use of +- Add `AvoidUsingDoubleQuotesForConstantString` (disabled by default) - Warns about the use of double quotes for constant strings ### Fixes -- `UseCorrectCasing` - Do not use **CommandInfoCache** when **CommandInfoParameters** property - throws due to runspace affinity problem of PowerShell engine -- `ReviewUnusedParameter` - Do not trigger when `$MyInvocation.BoundParameters` or +- `UseCorrectCasing` - Don't use **CommandInfoCache** when the **CommandInfoParameters** property + throws. Fixes runspace affinity problem in the PowerShell engine +- `ReviewUnusedParameter` - Don't trigger when `$MyInvocation.BoundParameters` or `$PSCmdlet.MyInvocation.BoundParameters` is used - `PipelineIndentationStyle.None` - Fix bug that caused incorrect formatting in hashtables - `UseUsingScopeModifierInNewRunspaces` - Fix `ArgumentException` when the same variable name is - used in 2 different sessions. + used in two different sessions. - `UseConsistentWhitespace` - Check previous token only if it starts on the same line - Fix **CheckParameter** bug when using interpolated string