Fixes MicrosoftDocs#4079 - Add docs for ValidateScript (MicrosoftDocs…

…#8096)

* Add docs for ValidateScript

* Fix title

* update TOC

Co-authored-by: Chase Wilson <31453523+chasewilson@users.noreply.github.com>

reference/docs-conceptual/developer/cmdlet/cmdlet-attributes.md

@@ -1,50 +1,59 @@
 ---
-ms.date: 09/13/2016
+ms.date: 09/16/2021
 ms.topic: reference
 title: Cmdlet Attributes
 description: Cmdlet Attributes
 ---
 # Cmdlet Attributes
 
-Windows PowerShell defines several attributes that you can use to add common functionality to your cmdlets without implementing that functionality within your own code. This includes the Cmdlet attribute that identifies a Microsoft .NET Framework class as a cmdlet class, the OutputType attribute that specifies the .NET Framework types returned by the cmdlet, the Parameter attribute that identifies public properties as cmdlet parameters, and more.
+Windows PowerShell defines several attributes that you can use to add common functionality to your
+cmdlets without implementing that functionality within your own code. This includes the Cmdlet
+attribute that identifies a Microsoft .NET Framework class as a cmdlet class, the OutputType
+attribute that specifies the .NET Framework types returned by the cmdlet, the Parameter attribute
+that identifies public properties as cmdlet parameters, and more.
 
 ## In This Section
 
-[Attributes in Cmdlet Code](./attributes-in-cmdlet-code.md)
-Describes the benefit of using attributes in cmdlet code.
+[Attributes in Cmdlet Code](./attributes-in-cmdlet-code.md) Describes the benefit of using
+attributes in cmdlet code.
 
-[Attribute Types](./attribute-types.md)
-Describes the different attributes that can decorate a cmdlet class.
+[Attribute Types](./attribute-types.md) Describes the different attributes that can decorate a
+cmdlet class.
 
-[Alias Attribute Declaration](./alias-attribute-declaration.md)
-Describes how to define aliases for a cmdlet parameter name.
+[Alias Attribute Declaration](./alias-attribute-declaration.md) Describes how to define aliases for
+a cmdlet parameter name.
 
-[Cmdlet Attribute Declaration](./cmdlet-attribute-declaration.md)
-Describes how to define a .NET Framework class as a cmdlet.
+[Cmdlet Attribute Declaration](./cmdlet-attribute-declaration.md) Describes how to define a .NET
+Framework class as a cmdlet.
 
-[Credential Attribute Declaration](./credential-attribute-declaration.md)
-Describes how to add support for converting string input into a [System.Management.Automation.PSCredential](/dotnet/api/System.Management.Automation.PSCredential) object.
+[Credential Attribute Declaration](./credential-attribute-declaration.md) Describes how to add
+support for converting string input into a
+[System.Management.Automation.PSCredential](/dotnet/api/System.Management.Automation.PSCredential)
+object.
 
-[OutputType attribute Declaration](./outputtype-attribute-declaration.md)
-Describes how to specify the .NET Framework types returned by the cmdlet.
+[OutputType attribute Declaration](./outputtype-attribute-declaration.md) Describes how to specify
+the .NET Framework types returned by the cmdlet.
 
-[Parameter Attribute Declaration](./parameter-attribute-declaration.md)
-Describes how to define the parameters of a cmdlet.
+[Parameter Attribute Declaration](./parameter-attribute-declaration.md) Describes how to define the
+parameters of a cmdlet.
 
-[ValidateCount Attribute Declaration](./validatecount-attribute-declaration.md)
-Describes how to define how many arguments are allowed for a parameter.
+[ValidateCount Attribute Declaration](./validatecount-attribute-declaration.md) Describes how to
+define how many arguments are allowed for a parameter.
 
-[ValidateLength Attribute Declaration](./validatelength-attribute-declaration.md)
-Describes how to define the length (in characters) of a parameter argument.
+[ValidateLength Attribute Declaration](./validatelength-attribute-declaration.md) Describes how to
+define the length (in characters) of a parameter argument.
 
-[ValidatePattern Attribute Declaration](./validatepattern-attribute-declaration.md)
-Describes how to define the valid patterns for a parameter argument.
+[ValidatePattern Attribute Declaration](./validatepattern-attribute-declaration.md) Describes how to
+define the valid patterns for a parameter argument.
 
-[ValidateRange Attribute Declaration](./validaterange-attribute-declaration.md)
-Describes how to define the valid range for a parameter argument.
+[ValidateRange Attribute Declaration](./validaterange-attribute-declaration.md) Describes how to
+define the valid range for a parameter argument.
 
-[ValidateSet Attribute Declaration](./validateset-attribute-declaration.md)
-Describes how to define the possible values for a parameter argument.
+[ValidateScript Attribute Declaration](./validatescript-attribute-declaration.md) Describes how to
+define the possible values for a parameter argument.
+
+[ValidateSet Attribute Declaration](./validateset-attribute-declaration.md) Describes how to define
+the possible values for a parameter argument.
 
 ## Reference
 

reference/docs-conceptual/developer/cmdlet/how-to-validate-an-argument-using-script.md

@@ -0,0 +1,43 @@
+---
+ms.date: 09/16/2021
+ms.topic: reference
+title: How to validate an argument using a script
+description: How to validate an argument using a script
+---
+# How to validate an argument using a script
+
+This example shows how to specify a validation rule that uses a script to check the parameter
+argument before the cmdlet is run. The value of the parameter is piped to the script. The script
+must return `$true` for every value piped to it.
+
+> [!NOTE]
+> For more information about the class that defines this attribute, see
+> [System.Management.Automation.ValidateScriptAttribute](/dotnet/api/System.Management.Automation.ValidateScriptAttribute).
+
+## To validate an argument using a script
+
+- Add the ValidateScript attribute as shown in the following code. This example specifies a set of
+  three possible values for the `UserName` parameter.
+
+   ```csharp
+   [ValidateScript("$_ % 2", ErrorMessage = "The item '{0}' did not pass validation of script '{1}'")]
+   [Parameter(Position = 0, Mandatory = true)]
+   public int32 OddNumber
+   {
+     get { return oddNumber; }
+     set { oddNumber = value; }
+   }
+
+   private int32 oddNumber;
+   ```
+
+For more information about how to declare this attribute, see
+[ValidateScript Attribute Declaration](./ValidateScript-attribute-declaration.md).
+
+## See Also
+
+[System.Management.Automation.ValidateScriptAttribute](/dotnet/api/System.Management.Automation.ValidateScriptAttribute)
+
+[ValidateScript Attribute Declaration](./ValidateScript-attribute-declaration.md)
+
+[Writing a Windows PowerShell Cmdlet](./writing-a-windows-powershell-cmdlet.md)

reference/docs-conceptual/developer/cmdlet/how-to-validate-parameter-input.md

@@ -1,5 +1,5 @@
 ---
-ms.date: 09/13/2016
+ms.date: 09/16/2021
 ms.topic: reference
 title: How to Validate Parameter Input
 description: How to Validate Parameter Input
@@ -11,6 +11,9 @@ to implement validation rules.
 
 ## In This Section
 
+[How to Validate an Argument with a Script](./how-to-validate-an-argument-using-script.md)
+Describes how to validate an argument set by using the ArgumentSet attribute.
+
 [How to Validate an Argument Set](./how-to-validate-an-argument-set.md)
 Describes how to validate an argument set by using the ArgumentSet attribute.
 
@@ -26,7 +29,8 @@ Describes how to validate the length of an argument by using the ArgumentLength
 [How to Validate an Argument Count](./how-to-validate-an-argument-count.md)
 Describes how to validate an argument count by using the ArgumentCount attribute.
 
-The way a parameter is declared can affect validation. For more information, see [How to Declare Cmdlet Parameters](./how-to-declare-cmdlet-parameters.md).
+The way a parameter is declared can affect validation. For more information, see
+[How to Declare Cmdlet Parameters](./how-to-declare-cmdlet-parameters.md).
 
 ## Reference
 

reference/docs-conceptual/developer/cmdlet/validatescript-attribute-declaration.md

@@ -0,0 +1,43 @@
+---
+ms.date: 09/16/2021
+ms.topic: reference
+title: ValidateScript Attribute Declaration
+description: ValidateScript Attribute Declaration
+---
+# ValidateScript Attribute Declaration
+
+The `ValidateScript` attribute specifies a script that is used to validate a parameter or variable
+value. PowerShell pipes the value to the script, and generates an error if the script returns
+`$false` or if the script throws an exception.
+
+When you use the `ValidateScript` attribute, the value that's being validated is mapped to the `$_`
+variable. You can use the `$_` variable to refer to the value in the script.
+
+## Syntax
+
+```csharp
+[ValidateScriptAttribute(ScriptBlock scriptBlock)]
+```
+
+### Parameters
+
+- `scriptBlock` -
+  ([System.Management.Automation.ScriptBlock](/dotnet/api/System.Management.Automation.ScriptBlock))
+  Required. The script block used to validate the input.
+- `ErrorMessage` - Optional - The item being validated and the validating scriptblock are passed as
+  the first and second formatting arguments.
+
+## Remarks
+
+- This attribute can be used only once per parameter.
+- If this attribute is applied to a collection, each element in the collection must match the
+  pattern.
+- The ValidateScript attribute is defined by the
+  [System.Management.Automation.ValidateScriptAttribute](/dotnet/api/System.Management.Automation.ValidateScriptAttribute)
+  class.
+
+## See Also
+
+[System.Management.Automation.ValidateScriptAttribute](/dotnet/api/System.Management.Automation.ValidateScriptAttribute)
+
+[Writing a Windows PowerShell Cmdlet](./writing-a-windows-powershell-cmdlet.md)

reference/docs-conceptual/developer/cmdlet/validating-parameter-input.md

@@ -1,46 +1,52 @@
 ---
-ms.date: 09/13/2016
+ms.date: 09/16/2021
 ms.topic: reference
 title: Validating Parameter Input
 description: Validating Parameter Input
 ---
 # Validating Parameter Input
 
-PowerShell can validate the arguments passed to cmdlet parameters in several ways.
-PowerShell can validate the length, the range, and the pattern of the characters of the argument.
-It can validate the number of arguments available (the count).
-These validation rules are defined by validation attributes that are declared with the Parameter attribute on public properties of the cmdlet class.
+PowerShell can validate the arguments passed to cmdlet parameters in several ways. PowerShell can
+validate the length, the range, and the pattern of the characters of the argument. It can validate
+the number of arguments available (the count). These validation rules are defined by validation
+attributes that are declared with the Parameter attribute on public properties of the cmdlet class.
 
-To validate a parameter argument, the PowerShell runtime uses the information provided by the validation attributes to confirm the value of the parameter before the cmdlet is run.
-If the parameter input is not valid, the user receives an error message.
-Each validation parameter defines a validation rule that is enforced by PowerShell.
+To validate a parameter argument, the PowerShell runtime uses the information provided by the
+validation attributes to confirm the value of the parameter before the cmdlet is run. If the
+parameter input is not valid, the user receives an error message. Each validation parameter defines
+a validation rule that is enforced by PowerShell.
 
 PowerShell enforces the validation rules based on the following attributes.
 
 ### ValidateCount
 
-Specifies the minimum and maximum number of arguments that a parameter can accept.
-For more information, see [ValidateCount Attribute Declaration](./validatecount-attribute-declaration.md).
+Specifies the minimum and maximum number of arguments that a parameter can accept. For more
+information, see [ValidateCount Attribute Declaration](./validatecount-attribute-declaration.md).
 
 ### ValidateLength
 
-Specifies the minimum and maximum number of characters in the parameter argument.
-For more information, see [ValidateLength Attribute Declaration](./validatelength-attribute-declaration.md).
+Specifies the minimum and maximum number of characters in the parameter argument. For more
+information, see [ValidateLength Attribute Declaration](./validatelength-attribute-declaration.md).
 
 ### ValidatePattern
 
-Specifies a regular expression that validates the parameter argument.
-For more information, see [ValidatePattern Attribute Declaration](./validatepattern-attribute-declaration.md).
+Specifies a regular expression that validates the parameter argument. For more information, see
+[ValidatePattern Attribute Declaration](./validatepattern-attribute-declaration.md).
 
 ### ValidateRange
 
-Specifies the minimum and maximum values of the parameter argument.
-For more information, see [ValidateRange Attribute Declaration](./validaterange-attribute-declaration.md).
+Specifies the minimum and maximum values of the parameter argument. For more information, see
+[ValidateRange Attribute Declaration](./validaterange-attribute-declaration.md).
+
+### ValidateScript
+
+Specifies the valid values for the parameter argument. For more information, see
+[ValidateScript Attribute Declaration](./validatescript-attribute-declaration.md).
 
 ### ValidateSet
 
-Specifies the valid values for the parameter argument.
-For more information, see [ValidateSet Attribute Declaration](./validateset-attribute-declaration.md).
+Specifies the valid values for the parameter argument. For more information, see
+[ValidateSet Attribute Declaration](./validateset-attribute-declaration.md).
 
 ## See Also
 

reference/docs-conceptual/toc.yml

@@ -926,6 +926,8 @@ items:
                         href: developer/cmdlet/validatepattern-attribute-declaration.md
                       - name: ValidateRange Attribute Declaration
                         href: developer/cmdlet/validaterange-attribute-declaration.md
+                      - name: ValidateScript Attribute Declaration
+                        href: developer/cmdlet/validatescript-attribute-declaration.md
                       - name: ValidateSet Attribute Declaration
                         href: developer/cmdlet/validateset-attribute-declaration.md
                   - name: Cmdlet Aliases
@@ -992,6 +994,8 @@ items:
                   - name: How to Validate Parameter Input
                     href: developer/cmdlet/how-to-validate-parameter-input.md
                     items:
+                      - name: How to Validate an Argument using a script
+                        href: developer/cmdlet/how-to-validate-an-argument-using-script.md
                       - name: How to Validate an Argument Set
                         href: developer/cmdlet/how-to-validate-an-argument-set.md
                       - name: How to Validate an Argument Range