diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md index ab4fb973409d..7384d76683c2 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -194,8 +194,8 @@ Get-Help about_Functions PowerShell aliases are represented by objects that are instances of the System.Management.Automation.AliasInfo class. For more information about this -type of object, see [AliasInfo Class](http://go.microsoft.com/fwlink/?LinkId=143644) -in the Microsoft Developer Network (MSDN) library. +type of object, see [AliasInfo Class][aliasinfo] in the Microsoft Developer +Network (MSDN) library. To view the properties and methods of the alias objects, get the aliases. Then, pipe them to the Get-Member cmdlet. For example: @@ -266,3 +266,6 @@ Get-Help Alias - [about_functions](about_functions.md) - [about_profiles](about_profiles.md) - [about_providers](about_providers.md) + + +[aliasinfo]: http://go.microsoft.com/fwlink/?LinkId=143644 \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 237a0e83b1cf..a08a495cb977 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -33,20 +33,29 @@ Beginning in PowerShell 3.0, the `-shr` (shift-right) and `-shl` PowerShell supports the following arithmetic operators: -|Operator|Description|Example| -|--------|-----------|-------| -| + |Adds integers; concatenates strings,
concatenates arrays, and hash tables.|`6 + 2`
`"file" + "name"`
`@(1, "one") + @(2.0, "two")`
`@{"one" = 1} + @{"two" = 2}`| -| - | Subtracts one value from another value | `6 - 2` | -| - | Makes a number a negative number | `-6`
`(Get-Date).AddDays(-1)` | -| * |Multiplies numbers, copies strings and
arrays the specified number of times.|`6 * 2`
`"!" * 3`
`@("!") * 4`| -| / |Divides two values.|`6 / 2`| -| % |Returns the remainder of a division operation.|`7 % 2`| -|-band|Bitwise AND|`5 -band 3`| -|-bnot|Bitwise NOT|`-bnot 5`| -|-bor|Bitwise OR|`5 -bor 0x03`| -|-bxor|Bitwise XOR|`5 -bxor 3`| -|-shl|Shifts bits to the left the specified number of times|`102 -shl 2`| -|-shr|Shifts bits to the right the specified number of times|`102 -shr 2`| +|Operator|Description |Example | +|--------|----------------------------------|-----------------------------| +| + |Adds integers; concatenates |`6 + 2` | +| |strings, arrays, and hash tables. |`"file" + "name"` | +| | |`@(1, "one") + @(2.0, "two")`| +| | |`@{"one" = 1} + @{"two" = 2}`| +| - |Subtracts one value from another |`6 - 2` | +| |value | | +| - |Makes a number a negative number |`-6` | +| | |`(Get-Date).AddDays(-1)` | +| * |Multiply numbers or copy strings |`6 * 2` | +| |and arrays the specified number |`@("!") * 4` | +| |of times. |`"!" * 3` | +| / |Divides two values. |`6 / 2` | +| % |Modulus - returns the remainder of|`7 % 2` | +| |a division operation. | | +|-band |Bitwise AND |`5 -band 3` | +|-bnot |Bitwise NOT |`-bnot 5` | +|-bor |Bitwise OR |`5 -bor 0x03` | +|-bxor |Bitwise XOR |`5 -bxor 3` | +|-shl |Shifts bits to the left the |`102 -shl 2` | +| |specified number of times | | +|-shr |Shifts bits to the right |`102 -shr 2` | The bitwise operators only work on integer types. @@ -54,22 +63,22 @@ The bitwise operators only work on integer types. PowerShell processes arithmetic operators in the following order: -| Precedence | Operator | Description | -|---|---|---| -|1 | `()` | Parentheses| -|2 | `-` | For a negative number or unary operator| -|3 | `*`, `/`, `%` | -|4 | `+`, `-` | For addition and subtraction| +|Precedence|Operator |Description | +|----------|---------------|---------------------------------------| +|1 | `()` |Parentheses | +|2 | `-` |For a negative number or unary operator| +|3 | `*`, `/`, `%` |For muliplication and division | +|4 | `+`, `-` |For addition and subtraction | PowerShell processes the expressions from left to right according to the precedence rules. The following examples show the effect of the precedence rules: -| Expression | Result | -|---|---| -| `3+6/3*4` | `11` | -|`3+6/(3*4)` | `3.5` | -|`(3+6)/3*4` | `12` | +|Expression |Result| +|-----------|------| +|`3+6/3*4` |`11` | +|`3+6/(3*4)`|`3.5` | +|`(3+6)/3*4`|`12` | The order in which PowerShell evaluates expressions might differ from other programming and scripting languages that you have used. The following @@ -110,10 +119,10 @@ nearest even integer. The following example shows the effect of rounding to the nearest even integer. -| Expression | Result | -|---|---| -|`[int]( 5 / 2 )` | `2` | -|`[int]( 7 / 2 )` | `4` | +|Expression |Result| +|----------------|------| +|`[int]( 5 / 2 )`|`2` | +|`[int]( 7 / 2 )`|`4` | Notice how **_5/2_ = 2.5** gets rounded to **2**. But, **_7/2_ = 3.5** gets rounded to **4**. @@ -159,13 +168,13 @@ The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object types. Assume `$array = 1,2,3`: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`$array + 16` | `1`
`2`
`3`
`16`| -|`$array + "file"` | `1`
`2`
`3`
`file`| -|`$array * 2` | `1`
`2`
`3`
`1`
`2`
`3`| -|`"file" * 3` | `filefilefile`| +|Expression |Result | +|-----------------|-----------------------| +|`"file" + 16` |`file16` | +|`$array + 16` |`1`,`2`,`3`,`16` | +|`$array + "file"`|`1`,`2`,`3`,`file` | +|`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| +|`"file" * 3` |`filefilefile` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -174,10 +183,13 @@ commutative. For example, `(a + b)` does not always equal `(b + a)`, and The following examples demonstrate this principle: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`16 + "file"` | `Cannot convert value "file" to type "System.Int32".`
`Error: "Input string was not in a correct format."`
`At line:1 char:1`
`+ 16 + "file"`| +|Expression |Result | +|-------------|-----------------------------------------------------| +|`"file" + 16`|`file16` | +|`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| +| |`Error: "Input string was not in a correct format."` | +| |`At line:1 char:1` | +| |+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -325,10 +337,11 @@ Decimal type, the result will be of the Decimal type. If the result is too large for the Decimal type, it will not be cast to Double. Instead, an error results. -| Expression | Result | -|---|---| -|`[Decimal]::maxvalue` | `79228162514264337593543950335`| -|`[Decimal]::maxvalue + 1` | `Value was either too large`
`or too small for a Decimal.`| +|Expression |Result | +|-------------------------|-----------------------------------------------| +|`[Decimal]::maxvalue` |`79228162514264337593543950335` | +|`[Decimal]::maxvalue + 1`|`Value was either too large or too small for a`| +| |`Decimal.` | ## ARITHMETIC OPERATORS AND VARIABLES @@ -336,10 +349,10 @@ You can also use arithmetic operators with variables. The operators act on the values of the variables. The following examples demonstrate the use of arithmetic operators with variables: -| Expression | Result | -|---|---| -|`$intA = 6`
`$intB = 4`
`$intA + $intB` | `10`| -|`$a = "Power"`
`$b = "Shell"`
`$a + $b` | `PowerShell`| +| Expression |Result | +|-----------------------------------------------|------------| +|`$intA = 6`
`$intB = 4`
`$intA + $intB`|`10` | +|`$a = "Power"`
`$b = "Shell"`
`$a + $b`|`PowerShell`| ## ARITHMETIC OPERATORS AND COMMANDS @@ -377,27 +390,6 @@ In the above expression, each process working space (`$_.ws`) is multiplied by `2`; and, the result, compared against `50mb` to see if it is greater than that. -### EXAMPLES - -The following examples show how to use the arithmetic operators in -PowerShell: - -|Expression|Result| -|----------|------| -|`1 + 1` | `2` | -|`1 - 1` | `0` | -|`-(6 + 3)`| `-9` | -|`6 * 2` | `12` | -|`7 / 2` | `3.5`| -|`7 % 2` | `1` | -|`'w' * 3` | `www`| -|`3 * 'w'` | `Cannot convert value "w" to type "System.Int32".`
` Error: "Input string was not in a correct format."`| -|`"Power" + "Shell"` | `PowerShell`| -|`$a = "Power" + "Shell"`
`$a[5]` | `S`| -|`$b = 1,2,3`
`$b + 4` | `1`
`2`
`3`
`4`| -|`$servers = @{`
  `0 = "LocalHost"`
  `1 = "Server01"`
  `2 = "Server02"`
`}`
`$servers + @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| -|`#Use assignment operator`
`$servers += @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| - ## Bitwise Operators PowerShell supports the standard bitwise operators, including bitwise-AND @@ -484,11 +476,11 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shl 0` | 21 | 0001 0101 | -|`21 -shl 1` | 42 | 0010 1010 | -|`21 -shl 2` | 84 | 0101 0100 | +|Expression |Result|Binary Result| +|-----------|------|-------------| +|`21 -shl 0`|21 |0001 0101 | +|`21 -shl 1`|42 |0010 1010 | +|`21 -shl 2`|84 |0101 0100 | In a bitwise shift-right operation, all bits are moved "n" places to the right, where "n" is specified by the right operand. The shift-right @@ -501,19 +493,19 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shr 0` | 21 | 0001 0101 | -|`21 -shr 1` | 10 | 0000 1010 | -|`21 -shr 2` | 5 | 0000 0101 | -|`21 -shr 31` | 0 | 0000 0000 | -|`21 -shr 32` | 21 | 0001 0101 | -|`21 -shr 64` | 21 | 0001 0101 | -|`21 -shr 65` | 10 | 0000 1010 | -|`21 -shr 66` | 5 | 0000 0101 | -|`[int]::MaxValue -shr 1` | 1073741823 | 0011 1111 1111 1111 1111 1111 1111 1111 | -|`[int]::MinValue -shr 1` | -1073741824 | 1100 0000 0000 0000 0000 0000 0000 0000 | -|`-1 -shr 1` | -1 | 1111 1111 1111 1111 1111 1111 1111 1111 | +|Expression |Result |Binary |Hex | +|------------------------|------------|-----------|------------| +|`21 -shr 0` | 21 | 0001 0101 | 0x15 | +|`21 -shr 1` | 10 | 0000 1010 | 0x0A | +|`21 -shr 2` | 5 | 0000 0101 | 0x05 | +|`21 -shr 31` | 0 | 0000 0000 | 0x00 | +|`21 -shr 32` | 21 | 0001 0101 | 0x15 | +|`21 -shr 64` | 21 | 0001 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x15 | +|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | +|`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | +|`-1 -shr 1` | -1 | | 0xFFFFFFFF | ## SEE ALSO diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index 0f8a7fb028c2..34af56c3eab2 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-24 +ms.date: 2017-11-27 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators @@ -18,16 +18,21 @@ perform numeric operations on the values before the assignment. Windows PowerShell supports the following assignment operators. -| Operator | Description | -| ------- | ----------- | -| = | Sets the value of a variable to the specified value. | -| += | Increases the value of a variable by the specified value, or appends the specified value to the existing value. | -|-= | Decreases the value of a variable by the specified value. | -| *= | Multiplies the value of a variable by the specified value, or appends the specified value to the existing value. | -| /= | Divides the value of a variable by the specified value. | -| %= | Divides the value of a variable by the specified value and then assigns the remainder (modulus) to the variable. | -| ++ | Increases the value of a variable, assignable property, or array element by 1. | -| -- | Decreases the value of a variable, assignable property, or array element by 1. | +|Operator|Description | +|--------|-------------------------------------------------------------| +|= |Sets the value of a variable to the specified value. | +|+= |Increases the value of a variable by the specified value, or | +| |appends the specified value to the existing value. | +|-= |Decreases the value of a variable by the specified value. | +|*= |Multiplies the value of a variable by the specified value, or| +| |appends the specified value to the existing value. | +|/= |Divides the value of a variable by the specified value. | +|%= |Divides the value of a variable by the specified value and | +| |then assigns the remainder (modulus) to the variable. | +|++ |Increases the value of a variable, assignable property, or | +| |array element by 1. | +|-- |Decreases the value of a variable, assignable property, or | +| |array element by 1. | ## SYNTAX @@ -335,8 +340,8 @@ $a You cannot use the `-=` operator to delete the values of a variable. To delete all the values that are assigned to a variable, use the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) or -[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) cmdlets -to assign a value of `$null` or `""` to the variable. +[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) +cmdlets to assign a value of `$null` or `""` to the variable. ```powershell $a = $null diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 85f7b0567465..0fe7b2fae3a1 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -251,7 +251,8 @@ were ignored. ```powershell $calendar = @($null, $null, “Meeting”, $null, $null, “Team Lunch”, $null) -$days = Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" +$days = "Sunday","Monday","Tuesday","Wednesday","Thursday", + "Friday","Saturday" $currentDay = 0 foreach($day in $calendar) { diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 223cd9bdde41..2c2792134daf 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -17,10 +17,11 @@ Describes how to write comment-based help topics for functions and scripts. You can write comment-based help topics for functions and scripts by using special help comment keywords. -The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same format in which -it displays the cmdlet help topics that are generated from XML files. Users -can use all of the parameters of `Get-Help`, such as **Detailed**, **Full**, **Example**, -and **Online**, to display the contents of comment-based help. +The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same +format in which it displays the cmdlet help topics that are generated from XML +files. Users can use all of the parameters of `Get-Help`, such as +**Detailed**, **Full**, **Example**, and **Online**, to display the contents +of comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function @@ -31,8 +32,9 @@ This topic explains how to write help topics for functions and scripts. For information about how to display help topics for functions and scripts, see `Get-Help`. -The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets work only on XML files. Updatable Help -does not support comment-based help topics. +The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets +work only on XML files. Updatable Help does not support comment-based help +topics. ## SYNTAX FOR COMMENT-BASED HELP @@ -52,8 +54,10 @@ or #> ``` -Comment-based help is written as a series of comments. You can type a -comment symbol `#` before each line of comments, or you can use the `<#` and `#>` symbols to create a comment block. All the lines within the comment block are interpreted as comments. +Comment-based help is written as a series of comments. You can type a comment +symbol `#` before each line of comments, or you can use the `<#` and `#>` +symbols to create a comment block. All the lines within the comment block are +interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a comment-based help topic follows a comment that is not part of the help @@ -84,10 +88,9 @@ multiple lines. Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - - At the end of the function body. - -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword. +- Before the Function keyword. There cannot be more than one blank line + between the last line of the function help and the Function keyword. For example: @@ -132,11 +135,17 @@ function Get-Function { } Comment-based help for a script can appear in one of the following two locations in the script. -- At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. +- At the beginning of the script file. Script help can be preceded in the + script only by comments and blank lines. -- If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. +- If the first item in the script body (after the help) is a function + declaration, there must be at least two blank lines between the end of the + script help and the function declaration. Otherwise, the help is interpreted + as being help for the function, not help for the script. -- At the end of the script file. However, if the script is signed, place Comment-based help at the beginning of the script file. The end of the script is occupied by the signature block. +- At the end of the script file. However, if the script is signed, place + Comment-based help at the beginning of the script file. The end of the script + is occupied by the signature block. For example: @@ -162,14 +171,13 @@ function Get-Function { } ## SYNTAX FOR COMMENT-BASED HELP IN SCRIPT MODULES -In a script module `.psm1`, comment-based help uses the syntax -for functions, not the syntax for scripts. You cannot use the -script syntax to provide help for all functions defined in a -script module. +In a script module `.psm1`, comment-based help uses the syntax for functions, +not the syntax for scripts. You cannot use the script syntax to provide help +for all functions defined in a script module. -For example, if you are using the "ExternalHelp" keyword to -identify the XML-based help files for the functions in a script -module, you must add an "ExternalHelp" comment to each function. +For example, if you are using the "ExternalHelp" keyword to identify the +XML-based help files for the functions in a script module, you must add an +"ExternalHelp" comment to each function. ```powershell .ExternalHelp @@ -182,10 +190,10 @@ function ## COMMENT-BASED HELP KEYWORDS -The following are valid comment-based help keywords. They are listed in the order in -which they typically appear in a help topic along with their intended use. -These keywords can appear in any order in the comment-based help, and they -are not case-sensitive. +The following are valid comment-based help keywords. They are listed in the +order in which they typically appear in a help topic along with their intended +use. These keywords can appear in any order in the comment-based help, and +they are not case-sensitive. ### .SYNOPSIS @@ -199,45 +207,44 @@ used only once in each topic. ### .PARAMETER -The description of a parameter. Add a ".PARAMETER" keyword for -each parameter in the function or script syntax. +The description of a parameter. Add a ".PARAMETER" keyword for each parameter +in the function or script syntax. -Type the parameter name on the same line as the ".PARAMETER" keyword. -Type the parameter description on the lines following the ".PARAMETER" -keyword. Windows PowerShell interprets all text between the ".PARAMETER" -line and the next keyword or the end of the comment block as part of -the parameter description. The description can include paragraph breaks. +Type the parameter name on the same line as the ".PARAMETER" keyword. Type the +parameter description on the lines following the ".PARAMETER" keyword. Windows +PowerShell interprets all text between the ".PARAMETER" line and the next +keyword or the end of the comment block as part of the parameter description. +The description can include paragraph breaks. ``` .PARAMETER ``` -The Parameter keywords can appear in any order in the comment block, but -the function or script syntax determines the order in which the parameters -(and their descriptions) appear in help topic. To change the order, -change the syntax. +The Parameter keywords can appear in any order in the comment block, but the +function or script syntax determines the order in which the parameters (and +their descriptions) appear in help topic. To change the order, change the +syntax. You can also specify a parameter description by placing a comment in the -function or script syntax immediately before the parameter variable name. -If you use both a syntax comment and a Parameter keyword, the description +function or script syntax immediately before the parameter variable name. If +you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored. ### .EXAMPLE -A sample command that uses the function or script, optionally followed -by sample output and a description. Repeat this keyword for each example. +A sample command that uses the function or script, optionally followed by +sample output and a description. Repeat this keyword for each example. ### .INPUTS The Microsoft .NET Framework types of objects that can be piped to the -function or script. You can also include a description of the input -objects. +function or script. You can also include a description of the input objects. ### .OUTPUTS -The .NET Framework type of the objects that the cmdlet returns. You can -also include a description of the returned objects. +The .NET Framework type of the objects that the cmdlet returns. You can also +include a description of the returned objects. ### .NOTES @@ -245,24 +252,24 @@ Additional information about the function or script. ### .LINK -The name of a related topic. The value appears on the line below -the ".LINK" keyword and must be preceded by a comment symbol `#` or -included in the comment block. +The name of a related topic. The value appears on the line below the ".LINK" +keyword and must be preceded by a comment symbol `#` or included in the +comment block. Repeat the ".LINK" keyword for each related topic. This content appears in the Related Links section of the help topic. The "Link" keyword content can also include a Uniform Resource Identifier -(URI) to an online version of the same help topic. The online version -opens when you use the **Online** parameter of `Get-Help`. The URI must begin -with "http" or "https". +(URI) to an online version of the same help topic. The online version opens +when you use the **Online** parameter of `Get-Help`. The URI must begin with +"http" or "https". ### .COMPONENT -The technology or feature that the function or script uses, or to which -it is related. This content appears when the `Get-Help` command includes -the **Component** parameter of `Get-Help`. +The technology or feature that the function or script uses, or to which it is +related. This content appears when the `Get-Help` command includes the +**Component** parameter of `Get-Help`. ### .ROLE @@ -276,9 +283,9 @@ command includes the **Functionality** parameter of `Get-Help`. ### .FORWARDHELPTARGETNAME -Redirects to the help topic for the specified command. You can redirect -users to any help topic, including help topics for a function, script, -cmdlet, or provider. +Redirects to the help topic for the specified command. You can redirect users +to any help topic, including help topics for a function, script, cmdlet, or +provider. ``` .FORWARDHELPTARGETNAME @@ -286,10 +293,10 @@ cmdlet, or provider. ### .FORWARDHELPCATEGORY -Specifies the help category of the item in "ForwardHelpTargetName". -Valid values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", -"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use this -keyword to avoid conflicts when there are commands with the same name. +Specifies the help category of the item in "ForwardHelpTargetName". Valid +values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", +"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use +this keyword to avoid conflicts when there are commands with the same name. ``` .FORWARDHELPCATEGORY @@ -298,7 +305,8 @@ keyword to avoid conflicts when there are commands with the same name. ### .REMOTEHELPRUNSPACE Specifies a session that contains the help topic. Enter a variable that -contains a "PSSession". This keyword is used by the [Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) +contains a "PSSession". This keyword is used by the +[Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) cmdlet to find the help topics for the exported commands. ``` @@ -313,34 +321,35 @@ Specifies an XML-based help file for the script or function. .EXTERNALHELP ``` -The "ExternalHelp" keyword is required when a function or script -is documented in XML files. Without this keyword, `Get-Help` cannot -find the XML-based help file for the function or script. +The "ExternalHelp" keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +file for the function or script. -The "ExternalHelp" keyword takes precedence over other comment-based -help keywords. If "ExternalHelp" is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches -the value of the "ExternalHelp" keyword. +The "ExternalHelp" keyword takes precedence over other comment-based help +keywords. If "ExternalHelp" is present, `Get-Help` does not display +comment-based help, even if it cannot find a help topic that matches the value +of the "ExternalHelp" keyword. -If the function is exported by a module, set the value of the -"ExternalHelp" keyword to a file name without a path. `Get-Help` looks for -the specified file name in a language-specific subdirectory of the module -directory. There are no requirements for the name of the XML-based help -file for a function, but a best practice is to use the following format: +If the function is exported by a module, set the value of the "ExternalHelp" +keyword to a file name without a path. `Get-Help` looks for the specified file +name in a language-specific subdirectory of the module directory. There are no +requirements for the name of the XML-based help file for a function, but a +best practice is to use the following format: ``` -help.xml ``` -If the function is not included in a module, include a path to the -XML-based help file. If the value includes a path and the path contains +If the function is not included in a module, include a path to the XML-based +help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in -accordance with the language fallback standards established for Windows, -just as it does in a module directory. +accordance with the language fallback standards established for Windows, just +as it does in a module directory. -For more information about the cmdlet help XML-based help file format, -see [How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in the MSDN library. +For more information about the cmdlet help XML-based help file format, see +[How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in +the MSDN library. ## AUTOGENERATED CONTENT @@ -349,41 +358,40 @@ parameters, and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The "Name" section of a function help topic is taken from the function -name in the function syntax. The "Name" of a script help topic is -taken from the script file name. To change the name or its -capitalization, change the function syntax or the script file name. +The "Name" section of a function help topic is taken from the function name in +the function syntax. The "Name" of a script help topic is taken from the +script file name. To change the name or its capitalization, change the +function syntax or the script file name. ### Syntax -The "Syntax" section of the help topic is generated from the function -or script syntax. To add detail to the help topic syntax, such as -the .NET Framework type of a parameter, add the detail to the syntax. -If you do not specify a parameter type, the "Object" type is -inserted as the default value. +The "Syntax" section of the help topic is generated from the function or +script syntax. To add detail to the help topic syntax, such as the .NET +Framework type of a parameter, add the detail to the syntax. If you do not +specify a parameter type, the "Object" type is inserted as the default value. ### Parameter List -The "Parameter list" in the help topic is generated from the function -or script syntax and from the descriptions that you add by using the -"Parameters" keyword. The function parameters appear in the "Parameters" -section of the help topic in the same order that they appear in -the function or script syntax. The spelling and capitalization of -parameter names is also taken from the syntax; it is not affected -by the parameter name specified by the "Parameter" keyword. +The "Parameter list" in the help topic is generated from the function or +script syntax and from the descriptions that you add by using the "Parameters" +keyword. The function parameters appear in the "Parameters" section of the +help topic in the same order that they appear in the function or script +syntax. The spelling and capitalization of parameter names is also taken from +the syntax; it is not affected by the parameter name specified by the +"Parameter" keyword. ### Common Parameters -The "Common parameters" are added to the syntax and parameter list -of the help topic, even if they have no effect. For more information -about the common parameters, see [about_CommonParameters](about_CommonParameters.md). +The "Common parameters" are added to the syntax and parameter list of the help +topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters](about_CommonParameters.md). ### Parameter Attribute Table -`Get-Help` generates the table of parameter attributes that appears -when you use the **Full** or **Parameter** parameter of `Get-help`. The value -of the "Required", "Position", and "Default" value attributes is taken -from the function or script syntax. +`Get-Help` generates the table of parameter attributes that appears when you +use the **Full** or **Parameter** parameter of `Get-help`. The value of the +"Required", "Position", and "Default" value attributes is taken from the +function or script syntax. Default values and a value for "Accept Wildcard characters" do not appear in the "Parameter attribute table" even when they are defined in the function or @@ -391,21 +399,19 @@ script. To help users, provide this information in the parameter description. ### Remarks -The "Remarks" section of the help topic is automatically generated -from the function or script name. You cannot change or affect its -content. +The "Remarks" section of the help topic is automatically generated from the +function or script name. You cannot change or affect its content. ## DISABLING COMMENT-BASED HELP -[This technique was suggested by Rich Prescott, a Windows engineer -from New York, NY.] +[This technique was suggested by Rich Prescott, a Windows engineer from New +York, NY.] -You can disable comment-based help. This makes the comment-based -help ineffective without deleting it. +You can disable comment-based help. This makes the comment-based help +ineffective without deleting it. -To disable comment-based help, enclose the comments in a here-string. To -hide the here-string, assign it to a variable or pipe it to the Out-Null -cmdlet. +To disable comment-based help, enclose the comments in a here-string. To hide +the here-string, assign it to a variable or pipe it to the Out-Null cmdlet. While it is disabled, the comment-based help has no effect. @@ -425,8 +431,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To disable the comment-based help, enclose it in a here-string, -as shown in the following example. +To disable the comment-based help, enclose it in a here-string, as shown in +the following example. ```powershell @" @@ -445,10 +451,9 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To hide the disabled comment-based help, assign the here-string to -a local variable that is not otherwise used in the function, as -shown in the following example. You can also pipe it to the [Out-Null](../Out-Null.md) -cmdlet. +To hide the disabled comment-based help, assign the here-string to a local +variable that is not otherwise used in the function, as shown in the following +example. You can also pipe it to the [Out-Null](../Out-Null.md) cmdlet. ```powershell $x = @" @@ -467,7 +472,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ## EXAMPLES @@ -504,7 +510,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension +or file name. .EXAMPLE @@ -549,11 +556,13 @@ Adds a file name extension to a supplied name. SYNTAX -Add-Extension [[-Name] ] [[-Extension] ] [] +Add-Extension [[-Name] ] [[-Extension] ] +[] DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. PARAMETERS @@ -586,7 +595,8 @@ None. You cannot pipe objects to Add-Extension. OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. Example 1 @@ -612,8 +622,8 @@ Set-Item - Parameter Descriptions in Function Syntax This example is the same as the previous one, except that the parameter -descriptions are inserted in the function syntax. This format is most -useful when the descriptions are brief. +descriptions are inserted in the function syntax. This format is most useful +when the descriptions are brief. ```powershell function Add-Extension @@ -640,7 +650,8 @@ Adds a file name extension to a supplied name. .DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. .INPUTS @@ -648,7 +659,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. .EXAMPLE @@ -678,12 +690,12 @@ Set-Item - Comment-based Help for a Script -The following sample script includes comment-based help. -Notice the blank lines between the closing "#>" and the "Param" statement. -In a script that does not have a Param statement, there must be at least -two blank lines between the final comment in the help topic and the first -function declaration. Without these blank lines, `Get-Help` associates the -help topic with the function, not the script. +The following sample script includes comment-based help. Notice the blank +lines between the closing "#>" and the "Param" statement. In a script that +does not have a Param statement, there must be at least two blank lines +between the final comment in the help topic and the first function +declaration. Without these blank lines, `Get-Help` associates the help topic +with the function, not the script. ```powershell <# @@ -722,7 +734,8 @@ C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv +C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +C:\Reports\2009\January.csv #> param ([string]$InputPath, [string]$OutPutPath) @@ -731,9 +744,9 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not -in a directory that is listed in the "Path" environment variable, the -`Get-Help` command that gets the script help must specify the script path. +The following command gets the script help. Because the script is not in a +directory that is listed in the "Path" environment variable, the `Get-Help` +command that gets the script help must specify the script path. ```powershell Get-Help -Path .\update-month.ps1 -Full @@ -813,12 +826,12 @@ C:\Reports\2009\January.csv - Redirecting to an XML File You can write XML-based help topics for functions and scripts. Although -comment-based help is easier to implement, XML-based help is required -for Updatable Help and to provide help topics in multiple languages. +comment-based help is easier to implement, XML-based help is required for +Updatable Help and to provide help topics in multiple languages. The following example shows the first few lines of the Update-Month.ps1 -script. The script uses the "ExternalHelp" keyword to specify the path to -an XML-based help topic for the script. +script. The script uses the "ExternalHelp" keyword to specify the path to an +XML-based help topic for the script. Note that the value of the "ExternalHelp" keyword appears on the same line as the keyword. Any other placement is ineffective. @@ -831,7 +844,8 @@ function Get-Data { } ... ``` -The following examples show three valid placements of the "ExternalHelp" keyword in a function. +The following examples show three valid placements of the "ExternalHelp" +keyword in a function. ```powershell function Add-Extension @@ -867,10 +881,10 @@ $name - Redirecting to a Different Help Topic -The following code is an excerpt from the beginning of the built-in -help function in Windows PowerShell, which displays one screen of help -text at a time. Because the help topic for the `Get-Help` cmdlet describes -the help function, the help function uses the "ForwardHelpTargetName" and +The following code is an excerpt from the beginning of the built-in help +function in Windows PowerShell, which displays one screen of help text at a +time. Because the help topic for the `Get-Help` cmdlet describes the help +function, the help function uses the "ForwardHelpTargetName" and "ForwardHelpCategory" keywords to redirect the user to the `Get-Help` cmdlet help topic. diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 4d6610ec5065..c7950b31389a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -498,8 +498,8 @@ Are you sure you want to perform this action? Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is -"Y"): s +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default +is "Y"): s PS C:\ps-test> Get-Help New-Item -Parameter ItemType @@ -516,8 +516,10 @@ PS C:\ps-test> exit Confirm Are you sure you want to perform this action? -Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y +Performing operation "Create File" on Target "Destination: C:\ps-test\test +.txt". +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (defau +lt is "Y"): y Directory: C:\ps-test diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Aliases.md index ab4fb973409d..7384d76683c2 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -194,8 +194,8 @@ Get-Help about_Functions PowerShell aliases are represented by objects that are instances of the System.Management.Automation.AliasInfo class. For more information about this -type of object, see [AliasInfo Class](http://go.microsoft.com/fwlink/?LinkId=143644) -in the Microsoft Developer Network (MSDN) library. +type of object, see [AliasInfo Class][aliasinfo] in the Microsoft Developer +Network (MSDN) library. To view the properties and methods of the alias objects, get the aliases. Then, pipe them to the Get-Member cmdlet. For example: @@ -266,3 +266,6 @@ Get-Help Alias - [about_functions](about_functions.md) - [about_profiles](about_profiles.md) - [about_providers](about_providers.md) + + +[aliasinfo]: http://go.microsoft.com/fwlink/?LinkId=143644 \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 237a0e83b1cf..a08a495cb977 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -33,20 +33,29 @@ Beginning in PowerShell 3.0, the `-shr` (shift-right) and `-shl` PowerShell supports the following arithmetic operators: -|Operator|Description|Example| -|--------|-----------|-------| -| + |Adds integers; concatenates strings,
concatenates arrays, and hash tables.|`6 + 2`
`"file" + "name"`
`@(1, "one") + @(2.0, "two")`
`@{"one" = 1} + @{"two" = 2}`| -| - | Subtracts one value from another value | `6 - 2` | -| - | Makes a number a negative number | `-6`
`(Get-Date).AddDays(-1)` | -| * |Multiplies numbers, copies strings and
arrays the specified number of times.|`6 * 2`
`"!" * 3`
`@("!") * 4`| -| / |Divides two values.|`6 / 2`| -| % |Returns the remainder of a division operation.|`7 % 2`| -|-band|Bitwise AND|`5 -band 3`| -|-bnot|Bitwise NOT|`-bnot 5`| -|-bor|Bitwise OR|`5 -bor 0x03`| -|-bxor|Bitwise XOR|`5 -bxor 3`| -|-shl|Shifts bits to the left the specified number of times|`102 -shl 2`| -|-shr|Shifts bits to the right the specified number of times|`102 -shr 2`| +|Operator|Description |Example | +|--------|----------------------------------|-----------------------------| +| + |Adds integers; concatenates |`6 + 2` | +| |strings, arrays, and hash tables. |`"file" + "name"` | +| | |`@(1, "one") + @(2.0, "two")`| +| | |`@{"one" = 1} + @{"two" = 2}`| +| - |Subtracts one value from another |`6 - 2` | +| |value | | +| - |Makes a number a negative number |`-6` | +| | |`(Get-Date).AddDays(-1)` | +| * |Multiply numbers or copy strings |`6 * 2` | +| |and arrays the specified number |`@("!") * 4` | +| |of times. |`"!" * 3` | +| / |Divides two values. |`6 / 2` | +| % |Modulus - returns the remainder of|`7 % 2` | +| |a division operation. | | +|-band |Bitwise AND |`5 -band 3` | +|-bnot |Bitwise NOT |`-bnot 5` | +|-bor |Bitwise OR |`5 -bor 0x03` | +|-bxor |Bitwise XOR |`5 -bxor 3` | +|-shl |Shifts bits to the left the |`102 -shl 2` | +| |specified number of times | | +|-shr |Shifts bits to the right |`102 -shr 2` | The bitwise operators only work on integer types. @@ -54,22 +63,22 @@ The bitwise operators only work on integer types. PowerShell processes arithmetic operators in the following order: -| Precedence | Operator | Description | -|---|---|---| -|1 | `()` | Parentheses| -|2 | `-` | For a negative number or unary operator| -|3 | `*`, `/`, `%` | -|4 | `+`, `-` | For addition and subtraction| +|Precedence|Operator |Description | +|----------|---------------|---------------------------------------| +|1 | `()` |Parentheses | +|2 | `-` |For a negative number or unary operator| +|3 | `*`, `/`, `%` |For muliplication and division | +|4 | `+`, `-` |For addition and subtraction | PowerShell processes the expressions from left to right according to the precedence rules. The following examples show the effect of the precedence rules: -| Expression | Result | -|---|---| -| `3+6/3*4` | `11` | -|`3+6/(3*4)` | `3.5` | -|`(3+6)/3*4` | `12` | +|Expression |Result| +|-----------|------| +|`3+6/3*4` |`11` | +|`3+6/(3*4)`|`3.5` | +|`(3+6)/3*4`|`12` | The order in which PowerShell evaluates expressions might differ from other programming and scripting languages that you have used. The following @@ -110,10 +119,10 @@ nearest even integer. The following example shows the effect of rounding to the nearest even integer. -| Expression | Result | -|---|---| -|`[int]( 5 / 2 )` | `2` | -|`[int]( 7 / 2 )` | `4` | +|Expression |Result| +|----------------|------| +|`[int]( 5 / 2 )`|`2` | +|`[int]( 7 / 2 )`|`4` | Notice how **_5/2_ = 2.5** gets rounded to **2**. But, **_7/2_ = 3.5** gets rounded to **4**. @@ -159,13 +168,13 @@ The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object types. Assume `$array = 1,2,3`: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`$array + 16` | `1`
`2`
`3`
`16`| -|`$array + "file"` | `1`
`2`
`3`
`file`| -|`$array * 2` | `1`
`2`
`3`
`1`
`2`
`3`| -|`"file" * 3` | `filefilefile`| +|Expression |Result | +|-----------------|-----------------------| +|`"file" + 16` |`file16` | +|`$array + 16` |`1`,`2`,`3`,`16` | +|`$array + "file"`|`1`,`2`,`3`,`file` | +|`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| +|`"file" * 3` |`filefilefile` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -174,10 +183,13 @@ commutative. For example, `(a + b)` does not always equal `(b + a)`, and The following examples demonstrate this principle: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`16 + "file"` | `Cannot convert value "file" to type "System.Int32".`
`Error: "Input string was not in a correct format."`
`At line:1 char:1`
`+ 16 + "file"`| +|Expression |Result | +|-------------|-----------------------------------------------------| +|`"file" + 16`|`file16` | +|`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| +| |`Error: "Input string was not in a correct format."` | +| |`At line:1 char:1` | +| |+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -325,10 +337,11 @@ Decimal type, the result will be of the Decimal type. If the result is too large for the Decimal type, it will not be cast to Double. Instead, an error results. -| Expression | Result | -|---|---| -|`[Decimal]::maxvalue` | `79228162514264337593543950335`| -|`[Decimal]::maxvalue + 1` | `Value was either too large`
`or too small for a Decimal.`| +|Expression |Result | +|-------------------------|-----------------------------------------------| +|`[Decimal]::maxvalue` |`79228162514264337593543950335` | +|`[Decimal]::maxvalue + 1`|`Value was either too large or too small for a`| +| |`Decimal.` | ## ARITHMETIC OPERATORS AND VARIABLES @@ -336,10 +349,10 @@ You can also use arithmetic operators with variables. The operators act on the values of the variables. The following examples demonstrate the use of arithmetic operators with variables: -| Expression | Result | -|---|---| -|`$intA = 6`
`$intB = 4`
`$intA + $intB` | `10`| -|`$a = "Power"`
`$b = "Shell"`
`$a + $b` | `PowerShell`| +| Expression |Result | +|-----------------------------------------------|------------| +|`$intA = 6`
`$intB = 4`
`$intA + $intB`|`10` | +|`$a = "Power"`
`$b = "Shell"`
`$a + $b`|`PowerShell`| ## ARITHMETIC OPERATORS AND COMMANDS @@ -377,27 +390,6 @@ In the above expression, each process working space (`$_.ws`) is multiplied by `2`; and, the result, compared against `50mb` to see if it is greater than that. -### EXAMPLES - -The following examples show how to use the arithmetic operators in -PowerShell: - -|Expression|Result| -|----------|------| -|`1 + 1` | `2` | -|`1 - 1` | `0` | -|`-(6 + 3)`| `-9` | -|`6 * 2` | `12` | -|`7 / 2` | `3.5`| -|`7 % 2` | `1` | -|`'w' * 3` | `www`| -|`3 * 'w'` | `Cannot convert value "w" to type "System.Int32".`
` Error: "Input string was not in a correct format."`| -|`"Power" + "Shell"` | `PowerShell`| -|`$a = "Power" + "Shell"`
`$a[5]` | `S`| -|`$b = 1,2,3`
`$b + 4` | `1`
`2`
`3`
`4`| -|`$servers = @{`
  `0 = "LocalHost"`
  `1 = "Server01"`
  `2 = "Server02"`
`}`
`$servers + @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| -|`#Use assignment operator`
`$servers += @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| - ## Bitwise Operators PowerShell supports the standard bitwise operators, including bitwise-AND @@ -484,11 +476,11 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shl 0` | 21 | 0001 0101 | -|`21 -shl 1` | 42 | 0010 1010 | -|`21 -shl 2` | 84 | 0101 0100 | +|Expression |Result|Binary Result| +|-----------|------|-------------| +|`21 -shl 0`|21 |0001 0101 | +|`21 -shl 1`|42 |0010 1010 | +|`21 -shl 2`|84 |0101 0100 | In a bitwise shift-right operation, all bits are moved "n" places to the right, where "n" is specified by the right operand. The shift-right @@ -501,19 +493,19 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shr 0` | 21 | 0001 0101 | -|`21 -shr 1` | 10 | 0000 1010 | -|`21 -shr 2` | 5 | 0000 0101 | -|`21 -shr 31` | 0 | 0000 0000 | -|`21 -shr 32` | 21 | 0001 0101 | -|`21 -shr 64` | 21 | 0001 0101 | -|`21 -shr 65` | 10 | 0000 1010 | -|`21 -shr 66` | 5 | 0000 0101 | -|`[int]::MaxValue -shr 1` | 1073741823 | 0011 1111 1111 1111 1111 1111 1111 1111 | -|`[int]::MinValue -shr 1` | -1073741824 | 1100 0000 0000 0000 0000 0000 0000 0000 | -|`-1 -shr 1` | -1 | 1111 1111 1111 1111 1111 1111 1111 1111 | +|Expression |Result |Binary |Hex | +|------------------------|------------|-----------|------------| +|`21 -shr 0` | 21 | 0001 0101 | 0x15 | +|`21 -shr 1` | 10 | 0000 1010 | 0x0A | +|`21 -shr 2` | 5 | 0000 0101 | 0x05 | +|`21 -shr 31` | 0 | 0000 0000 | 0x00 | +|`21 -shr 32` | 21 | 0001 0101 | 0x15 | +|`21 -shr 64` | 21 | 0001 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x15 | +|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | +|`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | +|`-1 -shr 1` | -1 | | 0xFFFFFFFF | ## SEE ALSO diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index 0f8a7fb028c2..34af56c3eab2 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-24 +ms.date: 2017-11-27 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators @@ -18,16 +18,21 @@ perform numeric operations on the values before the assignment. Windows PowerShell supports the following assignment operators. -| Operator | Description | -| ------- | ----------- | -| = | Sets the value of a variable to the specified value. | -| += | Increases the value of a variable by the specified value, or appends the specified value to the existing value. | -|-= | Decreases the value of a variable by the specified value. | -| *= | Multiplies the value of a variable by the specified value, or appends the specified value to the existing value. | -| /= | Divides the value of a variable by the specified value. | -| %= | Divides the value of a variable by the specified value and then assigns the remainder (modulus) to the variable. | -| ++ | Increases the value of a variable, assignable property, or array element by 1. | -| -- | Decreases the value of a variable, assignable property, or array element by 1. | +|Operator|Description | +|--------|-------------------------------------------------------------| +|= |Sets the value of a variable to the specified value. | +|+= |Increases the value of a variable by the specified value, or | +| |appends the specified value to the existing value. | +|-= |Decreases the value of a variable by the specified value. | +|*= |Multiplies the value of a variable by the specified value, or| +| |appends the specified value to the existing value. | +|/= |Divides the value of a variable by the specified value. | +|%= |Divides the value of a variable by the specified value and | +| |then assigns the remainder (modulus) to the variable. | +|++ |Increases the value of a variable, assignable property, or | +| |array element by 1. | +|-- |Decreases the value of a variable, assignable property, or | +| |array element by 1. | ## SYNTAX @@ -335,8 +340,8 @@ $a You cannot use the `-=` operator to delete the values of a variable. To delete all the values that are assigned to a variable, use the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) or -[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) cmdlets -to assign a value of `$null` or `""` to the variable. +[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) +cmdlets to assign a value of `$null` or `""` to the variable. ```powershell $a = $null diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 85f7b0567465..0fe7b2fae3a1 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -251,7 +251,8 @@ were ignored. ```powershell $calendar = @($null, $null, “Meeting”, $null, $null, “Team Lunch”, $null) -$days = Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" +$days = "Sunday","Monday","Tuesday","Wednesday","Thursday", + "Friday","Saturday" $currentDay = 0 foreach($day in $calendar) { diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 223cd9bdde41..2c2792134daf 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -17,10 +17,11 @@ Describes how to write comment-based help topics for functions and scripts. You can write comment-based help topics for functions and scripts by using special help comment keywords. -The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same format in which -it displays the cmdlet help topics that are generated from XML files. Users -can use all of the parameters of `Get-Help`, such as **Detailed**, **Full**, **Example**, -and **Online**, to display the contents of comment-based help. +The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same +format in which it displays the cmdlet help topics that are generated from XML +files. Users can use all of the parameters of `Get-Help`, such as +**Detailed**, **Full**, **Example**, and **Online**, to display the contents +of comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function @@ -31,8 +32,9 @@ This topic explains how to write help topics for functions and scripts. For information about how to display help topics for functions and scripts, see `Get-Help`. -The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets work only on XML files. Updatable Help -does not support comment-based help topics. +The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets +work only on XML files. Updatable Help does not support comment-based help +topics. ## SYNTAX FOR COMMENT-BASED HELP @@ -52,8 +54,10 @@ or #> ``` -Comment-based help is written as a series of comments. You can type a -comment symbol `#` before each line of comments, or you can use the `<#` and `#>` symbols to create a comment block. All the lines within the comment block are interpreted as comments. +Comment-based help is written as a series of comments. You can type a comment +symbol `#` before each line of comments, or you can use the `<#` and `#>` +symbols to create a comment block. All the lines within the comment block are +interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a comment-based help topic follows a comment that is not part of the help @@ -84,10 +88,9 @@ multiple lines. Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - - At the end of the function body. - -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword. +- Before the Function keyword. There cannot be more than one blank line + between the last line of the function help and the Function keyword. For example: @@ -132,11 +135,17 @@ function Get-Function { } Comment-based help for a script can appear in one of the following two locations in the script. -- At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. +- At the beginning of the script file. Script help can be preceded in the + script only by comments and blank lines. -- If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. +- If the first item in the script body (after the help) is a function + declaration, there must be at least two blank lines between the end of the + script help and the function declaration. Otherwise, the help is interpreted + as being help for the function, not help for the script. -- At the end of the script file. However, if the script is signed, place Comment-based help at the beginning of the script file. The end of the script is occupied by the signature block. +- At the end of the script file. However, if the script is signed, place + Comment-based help at the beginning of the script file. The end of the script + is occupied by the signature block. For example: @@ -162,14 +171,13 @@ function Get-Function { } ## SYNTAX FOR COMMENT-BASED HELP IN SCRIPT MODULES -In a script module `.psm1`, comment-based help uses the syntax -for functions, not the syntax for scripts. You cannot use the -script syntax to provide help for all functions defined in a -script module. +In a script module `.psm1`, comment-based help uses the syntax for functions, +not the syntax for scripts. You cannot use the script syntax to provide help +for all functions defined in a script module. -For example, if you are using the "ExternalHelp" keyword to -identify the XML-based help files for the functions in a script -module, you must add an "ExternalHelp" comment to each function. +For example, if you are using the "ExternalHelp" keyword to identify the +XML-based help files for the functions in a script module, you must add an +"ExternalHelp" comment to each function. ```powershell .ExternalHelp @@ -182,10 +190,10 @@ function ## COMMENT-BASED HELP KEYWORDS -The following are valid comment-based help keywords. They are listed in the order in -which they typically appear in a help topic along with their intended use. -These keywords can appear in any order in the comment-based help, and they -are not case-sensitive. +The following are valid comment-based help keywords. They are listed in the +order in which they typically appear in a help topic along with their intended +use. These keywords can appear in any order in the comment-based help, and +they are not case-sensitive. ### .SYNOPSIS @@ -199,45 +207,44 @@ used only once in each topic. ### .PARAMETER -The description of a parameter. Add a ".PARAMETER" keyword for -each parameter in the function or script syntax. +The description of a parameter. Add a ".PARAMETER" keyword for each parameter +in the function or script syntax. -Type the parameter name on the same line as the ".PARAMETER" keyword. -Type the parameter description on the lines following the ".PARAMETER" -keyword. Windows PowerShell interprets all text between the ".PARAMETER" -line and the next keyword or the end of the comment block as part of -the parameter description. The description can include paragraph breaks. +Type the parameter name on the same line as the ".PARAMETER" keyword. Type the +parameter description on the lines following the ".PARAMETER" keyword. Windows +PowerShell interprets all text between the ".PARAMETER" line and the next +keyword or the end of the comment block as part of the parameter description. +The description can include paragraph breaks. ``` .PARAMETER ``` -The Parameter keywords can appear in any order in the comment block, but -the function or script syntax determines the order in which the parameters -(and their descriptions) appear in help topic. To change the order, -change the syntax. +The Parameter keywords can appear in any order in the comment block, but the +function or script syntax determines the order in which the parameters (and +their descriptions) appear in help topic. To change the order, change the +syntax. You can also specify a parameter description by placing a comment in the -function or script syntax immediately before the parameter variable name. -If you use both a syntax comment and a Parameter keyword, the description +function or script syntax immediately before the parameter variable name. If +you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored. ### .EXAMPLE -A sample command that uses the function or script, optionally followed -by sample output and a description. Repeat this keyword for each example. +A sample command that uses the function or script, optionally followed by +sample output and a description. Repeat this keyword for each example. ### .INPUTS The Microsoft .NET Framework types of objects that can be piped to the -function or script. You can also include a description of the input -objects. +function or script. You can also include a description of the input objects. ### .OUTPUTS -The .NET Framework type of the objects that the cmdlet returns. You can -also include a description of the returned objects. +The .NET Framework type of the objects that the cmdlet returns. You can also +include a description of the returned objects. ### .NOTES @@ -245,24 +252,24 @@ Additional information about the function or script. ### .LINK -The name of a related topic. The value appears on the line below -the ".LINK" keyword and must be preceded by a comment symbol `#` or -included in the comment block. +The name of a related topic. The value appears on the line below the ".LINK" +keyword and must be preceded by a comment symbol `#` or included in the +comment block. Repeat the ".LINK" keyword for each related topic. This content appears in the Related Links section of the help topic. The "Link" keyword content can also include a Uniform Resource Identifier -(URI) to an online version of the same help topic. The online version -opens when you use the **Online** parameter of `Get-Help`. The URI must begin -with "http" or "https". +(URI) to an online version of the same help topic. The online version opens +when you use the **Online** parameter of `Get-Help`. The URI must begin with +"http" or "https". ### .COMPONENT -The technology or feature that the function or script uses, or to which -it is related. This content appears when the `Get-Help` command includes -the **Component** parameter of `Get-Help`. +The technology or feature that the function or script uses, or to which it is +related. This content appears when the `Get-Help` command includes the +**Component** parameter of `Get-Help`. ### .ROLE @@ -276,9 +283,9 @@ command includes the **Functionality** parameter of `Get-Help`. ### .FORWARDHELPTARGETNAME -Redirects to the help topic for the specified command. You can redirect -users to any help topic, including help topics for a function, script, -cmdlet, or provider. +Redirects to the help topic for the specified command. You can redirect users +to any help topic, including help topics for a function, script, cmdlet, or +provider. ``` .FORWARDHELPTARGETNAME @@ -286,10 +293,10 @@ cmdlet, or provider. ### .FORWARDHELPCATEGORY -Specifies the help category of the item in "ForwardHelpTargetName". -Valid values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", -"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use this -keyword to avoid conflicts when there are commands with the same name. +Specifies the help category of the item in "ForwardHelpTargetName". Valid +values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", +"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use +this keyword to avoid conflicts when there are commands with the same name. ``` .FORWARDHELPCATEGORY @@ -298,7 +305,8 @@ keyword to avoid conflicts when there are commands with the same name. ### .REMOTEHELPRUNSPACE Specifies a session that contains the help topic. Enter a variable that -contains a "PSSession". This keyword is used by the [Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) +contains a "PSSession". This keyword is used by the +[Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) cmdlet to find the help topics for the exported commands. ``` @@ -313,34 +321,35 @@ Specifies an XML-based help file for the script or function. .EXTERNALHELP ``` -The "ExternalHelp" keyword is required when a function or script -is documented in XML files. Without this keyword, `Get-Help` cannot -find the XML-based help file for the function or script. +The "ExternalHelp" keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +file for the function or script. -The "ExternalHelp" keyword takes precedence over other comment-based -help keywords. If "ExternalHelp" is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches -the value of the "ExternalHelp" keyword. +The "ExternalHelp" keyword takes precedence over other comment-based help +keywords. If "ExternalHelp" is present, `Get-Help` does not display +comment-based help, even if it cannot find a help topic that matches the value +of the "ExternalHelp" keyword. -If the function is exported by a module, set the value of the -"ExternalHelp" keyword to a file name without a path. `Get-Help` looks for -the specified file name in a language-specific subdirectory of the module -directory. There are no requirements for the name of the XML-based help -file for a function, but a best practice is to use the following format: +If the function is exported by a module, set the value of the "ExternalHelp" +keyword to a file name without a path. `Get-Help` looks for the specified file +name in a language-specific subdirectory of the module directory. There are no +requirements for the name of the XML-based help file for a function, but a +best practice is to use the following format: ``` -help.xml ``` -If the function is not included in a module, include a path to the -XML-based help file. If the value includes a path and the path contains +If the function is not included in a module, include a path to the XML-based +help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in -accordance with the language fallback standards established for Windows, -just as it does in a module directory. +accordance with the language fallback standards established for Windows, just +as it does in a module directory. -For more information about the cmdlet help XML-based help file format, -see [How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in the MSDN library. +For more information about the cmdlet help XML-based help file format, see +[How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in +the MSDN library. ## AUTOGENERATED CONTENT @@ -349,41 +358,40 @@ parameters, and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The "Name" section of a function help topic is taken from the function -name in the function syntax. The "Name" of a script help topic is -taken from the script file name. To change the name or its -capitalization, change the function syntax or the script file name. +The "Name" section of a function help topic is taken from the function name in +the function syntax. The "Name" of a script help topic is taken from the +script file name. To change the name or its capitalization, change the +function syntax or the script file name. ### Syntax -The "Syntax" section of the help topic is generated from the function -or script syntax. To add detail to the help topic syntax, such as -the .NET Framework type of a parameter, add the detail to the syntax. -If you do not specify a parameter type, the "Object" type is -inserted as the default value. +The "Syntax" section of the help topic is generated from the function or +script syntax. To add detail to the help topic syntax, such as the .NET +Framework type of a parameter, add the detail to the syntax. If you do not +specify a parameter type, the "Object" type is inserted as the default value. ### Parameter List -The "Parameter list" in the help topic is generated from the function -or script syntax and from the descriptions that you add by using the -"Parameters" keyword. The function parameters appear in the "Parameters" -section of the help topic in the same order that they appear in -the function or script syntax. The spelling and capitalization of -parameter names is also taken from the syntax; it is not affected -by the parameter name specified by the "Parameter" keyword. +The "Parameter list" in the help topic is generated from the function or +script syntax and from the descriptions that you add by using the "Parameters" +keyword. The function parameters appear in the "Parameters" section of the +help topic in the same order that they appear in the function or script +syntax. The spelling and capitalization of parameter names is also taken from +the syntax; it is not affected by the parameter name specified by the +"Parameter" keyword. ### Common Parameters -The "Common parameters" are added to the syntax and parameter list -of the help topic, even if they have no effect. For more information -about the common parameters, see [about_CommonParameters](about_CommonParameters.md). +The "Common parameters" are added to the syntax and parameter list of the help +topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters](about_CommonParameters.md). ### Parameter Attribute Table -`Get-Help` generates the table of parameter attributes that appears -when you use the **Full** or **Parameter** parameter of `Get-help`. The value -of the "Required", "Position", and "Default" value attributes is taken -from the function or script syntax. +`Get-Help` generates the table of parameter attributes that appears when you +use the **Full** or **Parameter** parameter of `Get-help`. The value of the +"Required", "Position", and "Default" value attributes is taken from the +function or script syntax. Default values and a value for "Accept Wildcard characters" do not appear in the "Parameter attribute table" even when they are defined in the function or @@ -391,21 +399,19 @@ script. To help users, provide this information in the parameter description. ### Remarks -The "Remarks" section of the help topic is automatically generated -from the function or script name. You cannot change or affect its -content. +The "Remarks" section of the help topic is automatically generated from the +function or script name. You cannot change or affect its content. ## DISABLING COMMENT-BASED HELP -[This technique was suggested by Rich Prescott, a Windows engineer -from New York, NY.] +[This technique was suggested by Rich Prescott, a Windows engineer from New +York, NY.] -You can disable comment-based help. This makes the comment-based -help ineffective without deleting it. +You can disable comment-based help. This makes the comment-based help +ineffective without deleting it. -To disable comment-based help, enclose the comments in a here-string. To -hide the here-string, assign it to a variable or pipe it to the Out-Null -cmdlet. +To disable comment-based help, enclose the comments in a here-string. To hide +the here-string, assign it to a variable or pipe it to the Out-Null cmdlet. While it is disabled, the comment-based help has no effect. @@ -425,8 +431,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To disable the comment-based help, enclose it in a here-string, -as shown in the following example. +To disable the comment-based help, enclose it in a here-string, as shown in +the following example. ```powershell @" @@ -445,10 +451,9 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To hide the disabled comment-based help, assign the here-string to -a local variable that is not otherwise used in the function, as -shown in the following example. You can also pipe it to the [Out-Null](../Out-Null.md) -cmdlet. +To hide the disabled comment-based help, assign the here-string to a local +variable that is not otherwise used in the function, as shown in the following +example. You can also pipe it to the [Out-Null](../Out-Null.md) cmdlet. ```powershell $x = @" @@ -467,7 +472,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ## EXAMPLES @@ -504,7 +510,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension +or file name. .EXAMPLE @@ -549,11 +556,13 @@ Adds a file name extension to a supplied name. SYNTAX -Add-Extension [[-Name] ] [[-Extension] ] [] +Add-Extension [[-Name] ] [[-Extension] ] +[] DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. PARAMETERS @@ -586,7 +595,8 @@ None. You cannot pipe objects to Add-Extension. OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. Example 1 @@ -612,8 +622,8 @@ Set-Item - Parameter Descriptions in Function Syntax This example is the same as the previous one, except that the parameter -descriptions are inserted in the function syntax. This format is most -useful when the descriptions are brief. +descriptions are inserted in the function syntax. This format is most useful +when the descriptions are brief. ```powershell function Add-Extension @@ -640,7 +650,8 @@ Adds a file name extension to a supplied name. .DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. .INPUTS @@ -648,7 +659,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. .EXAMPLE @@ -678,12 +690,12 @@ Set-Item - Comment-based Help for a Script -The following sample script includes comment-based help. -Notice the blank lines between the closing "#>" and the "Param" statement. -In a script that does not have a Param statement, there must be at least -two blank lines between the final comment in the help topic and the first -function declaration. Without these blank lines, `Get-Help` associates the -help topic with the function, not the script. +The following sample script includes comment-based help. Notice the blank +lines between the closing "#>" and the "Param" statement. In a script that +does not have a Param statement, there must be at least two blank lines +between the final comment in the help topic and the first function +declaration. Without these blank lines, `Get-Help` associates the help topic +with the function, not the script. ```powershell <# @@ -722,7 +734,8 @@ C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv +C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +C:\Reports\2009\January.csv #> param ([string]$InputPath, [string]$OutPutPath) @@ -731,9 +744,9 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not -in a directory that is listed in the "Path" environment variable, the -`Get-Help` command that gets the script help must specify the script path. +The following command gets the script help. Because the script is not in a +directory that is listed in the "Path" environment variable, the `Get-Help` +command that gets the script help must specify the script path. ```powershell Get-Help -Path .\update-month.ps1 -Full @@ -813,12 +826,12 @@ C:\Reports\2009\January.csv - Redirecting to an XML File You can write XML-based help topics for functions and scripts. Although -comment-based help is easier to implement, XML-based help is required -for Updatable Help and to provide help topics in multiple languages. +comment-based help is easier to implement, XML-based help is required for +Updatable Help and to provide help topics in multiple languages. The following example shows the first few lines of the Update-Month.ps1 -script. The script uses the "ExternalHelp" keyword to specify the path to -an XML-based help topic for the script. +script. The script uses the "ExternalHelp" keyword to specify the path to an +XML-based help topic for the script. Note that the value of the "ExternalHelp" keyword appears on the same line as the keyword. Any other placement is ineffective. @@ -831,7 +844,8 @@ function Get-Data { } ... ``` -The following examples show three valid placements of the "ExternalHelp" keyword in a function. +The following examples show three valid placements of the "ExternalHelp" +keyword in a function. ```powershell function Add-Extension @@ -867,10 +881,10 @@ $name - Redirecting to a Different Help Topic -The following code is an excerpt from the beginning of the built-in -help function in Windows PowerShell, which displays one screen of help -text at a time. Because the help topic for the `Get-Help` cmdlet describes -the help function, the help function uses the "ForwardHelpTargetName" and +The following code is an excerpt from the beginning of the built-in help +function in Windows PowerShell, which displays one screen of help text at a +time. Because the help topic for the `Get-Help` cmdlet describes the help +function, the help function uses the "ForwardHelpTargetName" and "ForwardHelpCategory" keywords to redirect the user to the `Get-Help` cmdlet help topic. diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 4d6610ec5065..c7950b31389a 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -498,8 +498,8 @@ Are you sure you want to perform this action? Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is -"Y"): s +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default +is "Y"): s PS C:\ps-test> Get-Help New-Item -Parameter ItemType @@ -516,8 +516,10 @@ PS C:\ps-test> exit Confirm Are you sure you want to perform this action? -Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y +Performing operation "Create File" on Target "Destination: C:\ps-test\test +.txt". +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (defau +lt is "Y"): y Directory: C:\ps-test diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Aliases.md index ab4fb973409d..7384d76683c2 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -194,8 +194,8 @@ Get-Help about_Functions PowerShell aliases are represented by objects that are instances of the System.Management.Automation.AliasInfo class. For more information about this -type of object, see [AliasInfo Class](http://go.microsoft.com/fwlink/?LinkId=143644) -in the Microsoft Developer Network (MSDN) library. +type of object, see [AliasInfo Class][aliasinfo] in the Microsoft Developer +Network (MSDN) library. To view the properties and methods of the alias objects, get the aliases. Then, pipe them to the Get-Member cmdlet. For example: @@ -266,3 +266,6 @@ Get-Help Alias - [about_functions](about_functions.md) - [about_profiles](about_profiles.md) - [about_providers](about_providers.md) + + +[aliasinfo]: http://go.microsoft.com/fwlink/?LinkId=143644 \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 237a0e83b1cf..a08a495cb977 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -33,20 +33,29 @@ Beginning in PowerShell 3.0, the `-shr` (shift-right) and `-shl` PowerShell supports the following arithmetic operators: -|Operator|Description|Example| -|--------|-----------|-------| -| + |Adds integers; concatenates strings,
concatenates arrays, and hash tables.|`6 + 2`
`"file" + "name"`
`@(1, "one") + @(2.0, "two")`
`@{"one" = 1} + @{"two" = 2}`| -| - | Subtracts one value from another value | `6 - 2` | -| - | Makes a number a negative number | `-6`
`(Get-Date).AddDays(-1)` | -| * |Multiplies numbers, copies strings and
arrays the specified number of times.|`6 * 2`
`"!" * 3`
`@("!") * 4`| -| / |Divides two values.|`6 / 2`| -| % |Returns the remainder of a division operation.|`7 % 2`| -|-band|Bitwise AND|`5 -band 3`| -|-bnot|Bitwise NOT|`-bnot 5`| -|-bor|Bitwise OR|`5 -bor 0x03`| -|-bxor|Bitwise XOR|`5 -bxor 3`| -|-shl|Shifts bits to the left the specified number of times|`102 -shl 2`| -|-shr|Shifts bits to the right the specified number of times|`102 -shr 2`| +|Operator|Description |Example | +|--------|----------------------------------|-----------------------------| +| + |Adds integers; concatenates |`6 + 2` | +| |strings, arrays, and hash tables. |`"file" + "name"` | +| | |`@(1, "one") + @(2.0, "two")`| +| | |`@{"one" = 1} + @{"two" = 2}`| +| - |Subtracts one value from another |`6 - 2` | +| |value | | +| - |Makes a number a negative number |`-6` | +| | |`(Get-Date).AddDays(-1)` | +| * |Multiply numbers or copy strings |`6 * 2` | +| |and arrays the specified number |`@("!") * 4` | +| |of times. |`"!" * 3` | +| / |Divides two values. |`6 / 2` | +| % |Modulus - returns the remainder of|`7 % 2` | +| |a division operation. | | +|-band |Bitwise AND |`5 -band 3` | +|-bnot |Bitwise NOT |`-bnot 5` | +|-bor |Bitwise OR |`5 -bor 0x03` | +|-bxor |Bitwise XOR |`5 -bxor 3` | +|-shl |Shifts bits to the left the |`102 -shl 2` | +| |specified number of times | | +|-shr |Shifts bits to the right |`102 -shr 2` | The bitwise operators only work on integer types. @@ -54,22 +63,22 @@ The bitwise operators only work on integer types. PowerShell processes arithmetic operators in the following order: -| Precedence | Operator | Description | -|---|---|---| -|1 | `()` | Parentheses| -|2 | `-` | For a negative number or unary operator| -|3 | `*`, `/`, `%` | -|4 | `+`, `-` | For addition and subtraction| +|Precedence|Operator |Description | +|----------|---------------|---------------------------------------| +|1 | `()` |Parentheses | +|2 | `-` |For a negative number or unary operator| +|3 | `*`, `/`, `%` |For muliplication and division | +|4 | `+`, `-` |For addition and subtraction | PowerShell processes the expressions from left to right according to the precedence rules. The following examples show the effect of the precedence rules: -| Expression | Result | -|---|---| -| `3+6/3*4` | `11` | -|`3+6/(3*4)` | `3.5` | -|`(3+6)/3*4` | `12` | +|Expression |Result| +|-----------|------| +|`3+6/3*4` |`11` | +|`3+6/(3*4)`|`3.5` | +|`(3+6)/3*4`|`12` | The order in which PowerShell evaluates expressions might differ from other programming and scripting languages that you have used. The following @@ -110,10 +119,10 @@ nearest even integer. The following example shows the effect of rounding to the nearest even integer. -| Expression | Result | -|---|---| -|`[int]( 5 / 2 )` | `2` | -|`[int]( 7 / 2 )` | `4` | +|Expression |Result| +|----------------|------| +|`[int]( 5 / 2 )`|`2` | +|`[int]( 7 / 2 )`|`4` | Notice how **_5/2_ = 2.5** gets rounded to **2**. But, **_7/2_ = 3.5** gets rounded to **4**. @@ -159,13 +168,13 @@ The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object types. Assume `$array = 1,2,3`: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`$array + 16` | `1`
`2`
`3`
`16`| -|`$array + "file"` | `1`
`2`
`3`
`file`| -|`$array * 2` | `1`
`2`
`3`
`1`
`2`
`3`| -|`"file" * 3` | `filefilefile`| +|Expression |Result | +|-----------------|-----------------------| +|`"file" + 16` |`file16` | +|`$array + 16` |`1`,`2`,`3`,`16` | +|`$array + "file"`|`1`,`2`,`3`,`file` | +|`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| +|`"file" * 3` |`filefilefile` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -174,10 +183,13 @@ commutative. For example, `(a + b)` does not always equal `(b + a)`, and The following examples demonstrate this principle: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`16 + "file"` | `Cannot convert value "file" to type "System.Int32".`
`Error: "Input string was not in a correct format."`
`At line:1 char:1`
`+ 16 + "file"`| +|Expression |Result | +|-------------|-----------------------------------------------------| +|`"file" + 16`|`file16` | +|`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| +| |`Error: "Input string was not in a correct format."` | +| |`At line:1 char:1` | +| |+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -325,10 +337,11 @@ Decimal type, the result will be of the Decimal type. If the result is too large for the Decimal type, it will not be cast to Double. Instead, an error results. -| Expression | Result | -|---|---| -|`[Decimal]::maxvalue` | `79228162514264337593543950335`| -|`[Decimal]::maxvalue + 1` | `Value was either too large`
`or too small for a Decimal.`| +|Expression |Result | +|-------------------------|-----------------------------------------------| +|`[Decimal]::maxvalue` |`79228162514264337593543950335` | +|`[Decimal]::maxvalue + 1`|`Value was either too large or too small for a`| +| |`Decimal.` | ## ARITHMETIC OPERATORS AND VARIABLES @@ -336,10 +349,10 @@ You can also use arithmetic operators with variables. The operators act on the values of the variables. The following examples demonstrate the use of arithmetic operators with variables: -| Expression | Result | -|---|---| -|`$intA = 6`
`$intB = 4`
`$intA + $intB` | `10`| -|`$a = "Power"`
`$b = "Shell"`
`$a + $b` | `PowerShell`| +| Expression |Result | +|-----------------------------------------------|------------| +|`$intA = 6`
`$intB = 4`
`$intA + $intB`|`10` | +|`$a = "Power"`
`$b = "Shell"`
`$a + $b`|`PowerShell`| ## ARITHMETIC OPERATORS AND COMMANDS @@ -377,27 +390,6 @@ In the above expression, each process working space (`$_.ws`) is multiplied by `2`; and, the result, compared against `50mb` to see if it is greater than that. -### EXAMPLES - -The following examples show how to use the arithmetic operators in -PowerShell: - -|Expression|Result| -|----------|------| -|`1 + 1` | `2` | -|`1 - 1` | `0` | -|`-(6 + 3)`| `-9` | -|`6 * 2` | `12` | -|`7 / 2` | `3.5`| -|`7 % 2` | `1` | -|`'w' * 3` | `www`| -|`3 * 'w'` | `Cannot convert value "w" to type "System.Int32".`
` Error: "Input string was not in a correct format."`| -|`"Power" + "Shell"` | `PowerShell`| -|`$a = "Power" + "Shell"`
`$a[5]` | `S`| -|`$b = 1,2,3`
`$b + 4` | `1`
`2`
`3`
`4`| -|`$servers = @{`
  `0 = "LocalHost"`
  `1 = "Server01"`
  `2 = "Server02"`
`}`
`$servers + @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| -|`#Use assignment operator`
`$servers += @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| - ## Bitwise Operators PowerShell supports the standard bitwise operators, including bitwise-AND @@ -484,11 +476,11 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shl 0` | 21 | 0001 0101 | -|`21 -shl 1` | 42 | 0010 1010 | -|`21 -shl 2` | 84 | 0101 0100 | +|Expression |Result|Binary Result| +|-----------|------|-------------| +|`21 -shl 0`|21 |0001 0101 | +|`21 -shl 1`|42 |0010 1010 | +|`21 -shl 2`|84 |0101 0100 | In a bitwise shift-right operation, all bits are moved "n" places to the right, where "n" is specified by the right operand. The shift-right @@ -501,19 +493,19 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shr 0` | 21 | 0001 0101 | -|`21 -shr 1` | 10 | 0000 1010 | -|`21 -shr 2` | 5 | 0000 0101 | -|`21 -shr 31` | 0 | 0000 0000 | -|`21 -shr 32` | 21 | 0001 0101 | -|`21 -shr 64` | 21 | 0001 0101 | -|`21 -shr 65` | 10 | 0000 1010 | -|`21 -shr 66` | 5 | 0000 0101 | -|`[int]::MaxValue -shr 1` | 1073741823 | 0011 1111 1111 1111 1111 1111 1111 1111 | -|`[int]::MinValue -shr 1` | -1073741824 | 1100 0000 0000 0000 0000 0000 0000 0000 | -|`-1 -shr 1` | -1 | 1111 1111 1111 1111 1111 1111 1111 1111 | +|Expression |Result |Binary |Hex | +|------------------------|------------|-----------|------------| +|`21 -shr 0` | 21 | 0001 0101 | 0x15 | +|`21 -shr 1` | 10 | 0000 1010 | 0x0A | +|`21 -shr 2` | 5 | 0000 0101 | 0x05 | +|`21 -shr 31` | 0 | 0000 0000 | 0x00 | +|`21 -shr 32` | 21 | 0001 0101 | 0x15 | +|`21 -shr 64` | 21 | 0001 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x15 | +|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | +|`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | +|`-1 -shr 1` | -1 | | 0xFFFFFFFF | ## SEE ALSO diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index 0f8a7fb028c2..34af56c3eab2 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-24 +ms.date: 2017-11-27 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators @@ -18,16 +18,21 @@ perform numeric operations on the values before the assignment. Windows PowerShell supports the following assignment operators. -| Operator | Description | -| ------- | ----------- | -| = | Sets the value of a variable to the specified value. | -| += | Increases the value of a variable by the specified value, or appends the specified value to the existing value. | -|-= | Decreases the value of a variable by the specified value. | -| *= | Multiplies the value of a variable by the specified value, or appends the specified value to the existing value. | -| /= | Divides the value of a variable by the specified value. | -| %= | Divides the value of a variable by the specified value and then assigns the remainder (modulus) to the variable. | -| ++ | Increases the value of a variable, assignable property, or array element by 1. | -| -- | Decreases the value of a variable, assignable property, or array element by 1. | +|Operator|Description | +|--------|-------------------------------------------------------------| +|= |Sets the value of a variable to the specified value. | +|+= |Increases the value of a variable by the specified value, or | +| |appends the specified value to the existing value. | +|-= |Decreases the value of a variable by the specified value. | +|*= |Multiplies the value of a variable by the specified value, or| +| |appends the specified value to the existing value. | +|/= |Divides the value of a variable by the specified value. | +|%= |Divides the value of a variable by the specified value and | +| |then assigns the remainder (modulus) to the variable. | +|++ |Increases the value of a variable, assignable property, or | +| |array element by 1. | +|-- |Decreases the value of a variable, assignable property, or | +| |array element by 1. | ## SYNTAX @@ -335,8 +340,8 @@ $a You cannot use the `-=` operator to delete the values of a variable. To delete all the values that are assigned to a variable, use the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) or -[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) cmdlets -to assign a value of `$null` or `""` to the variable. +[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) +cmdlets to assign a value of `$null` or `""` to the variable. ```powershell $a = $null diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 85f7b0567465..0fe7b2fae3a1 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -251,7 +251,8 @@ were ignored. ```powershell $calendar = @($null, $null, “Meeting”, $null, $null, “Team Lunch”, $null) -$days = Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" +$days = "Sunday","Monday","Tuesday","Wednesday","Thursday", + "Friday","Saturday" $currentDay = 0 foreach($day in $calendar) { diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 223cd9bdde41..2c2792134daf 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -17,10 +17,11 @@ Describes how to write comment-based help topics for functions and scripts. You can write comment-based help topics for functions and scripts by using special help comment keywords. -The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same format in which -it displays the cmdlet help topics that are generated from XML files. Users -can use all of the parameters of `Get-Help`, such as **Detailed**, **Full**, **Example**, -and **Online**, to display the contents of comment-based help. +The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same +format in which it displays the cmdlet help topics that are generated from XML +files. Users can use all of the parameters of `Get-Help`, such as +**Detailed**, **Full**, **Example**, and **Online**, to display the contents +of comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function @@ -31,8 +32,9 @@ This topic explains how to write help topics for functions and scripts. For information about how to display help topics for functions and scripts, see `Get-Help`. -The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets work only on XML files. Updatable Help -does not support comment-based help topics. +The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets +work only on XML files. Updatable Help does not support comment-based help +topics. ## SYNTAX FOR COMMENT-BASED HELP @@ -52,8 +54,10 @@ or #> ``` -Comment-based help is written as a series of comments. You can type a -comment symbol `#` before each line of comments, or you can use the `<#` and `#>` symbols to create a comment block. All the lines within the comment block are interpreted as comments. +Comment-based help is written as a series of comments. You can type a comment +symbol `#` before each line of comments, or you can use the `<#` and `#>` +symbols to create a comment block. All the lines within the comment block are +interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a comment-based help topic follows a comment that is not part of the help @@ -84,10 +88,9 @@ multiple lines. Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - - At the end of the function body. - -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword. +- Before the Function keyword. There cannot be more than one blank line + between the last line of the function help and the Function keyword. For example: @@ -132,11 +135,17 @@ function Get-Function { } Comment-based help for a script can appear in one of the following two locations in the script. -- At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. +- At the beginning of the script file. Script help can be preceded in the + script only by comments and blank lines. -- If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. +- If the first item in the script body (after the help) is a function + declaration, there must be at least two blank lines between the end of the + script help and the function declaration. Otherwise, the help is interpreted + as being help for the function, not help for the script. -- At the end of the script file. However, if the script is signed, place Comment-based help at the beginning of the script file. The end of the script is occupied by the signature block. +- At the end of the script file. However, if the script is signed, place + Comment-based help at the beginning of the script file. The end of the script + is occupied by the signature block. For example: @@ -162,14 +171,13 @@ function Get-Function { } ## SYNTAX FOR COMMENT-BASED HELP IN SCRIPT MODULES -In a script module `.psm1`, comment-based help uses the syntax -for functions, not the syntax for scripts. You cannot use the -script syntax to provide help for all functions defined in a -script module. +In a script module `.psm1`, comment-based help uses the syntax for functions, +not the syntax for scripts. You cannot use the script syntax to provide help +for all functions defined in a script module. -For example, if you are using the "ExternalHelp" keyword to -identify the XML-based help files for the functions in a script -module, you must add an "ExternalHelp" comment to each function. +For example, if you are using the "ExternalHelp" keyword to identify the +XML-based help files for the functions in a script module, you must add an +"ExternalHelp" comment to each function. ```powershell .ExternalHelp @@ -182,10 +190,10 @@ function ## COMMENT-BASED HELP KEYWORDS -The following are valid comment-based help keywords. They are listed in the order in -which they typically appear in a help topic along with their intended use. -These keywords can appear in any order in the comment-based help, and they -are not case-sensitive. +The following are valid comment-based help keywords. They are listed in the +order in which they typically appear in a help topic along with their intended +use. These keywords can appear in any order in the comment-based help, and +they are not case-sensitive. ### .SYNOPSIS @@ -199,45 +207,44 @@ used only once in each topic. ### .PARAMETER -The description of a parameter. Add a ".PARAMETER" keyword for -each parameter in the function or script syntax. +The description of a parameter. Add a ".PARAMETER" keyword for each parameter +in the function or script syntax. -Type the parameter name on the same line as the ".PARAMETER" keyword. -Type the parameter description on the lines following the ".PARAMETER" -keyword. Windows PowerShell interprets all text between the ".PARAMETER" -line and the next keyword or the end of the comment block as part of -the parameter description. The description can include paragraph breaks. +Type the parameter name on the same line as the ".PARAMETER" keyword. Type the +parameter description on the lines following the ".PARAMETER" keyword. Windows +PowerShell interprets all text between the ".PARAMETER" line and the next +keyword or the end of the comment block as part of the parameter description. +The description can include paragraph breaks. ``` .PARAMETER ``` -The Parameter keywords can appear in any order in the comment block, but -the function or script syntax determines the order in which the parameters -(and their descriptions) appear in help topic. To change the order, -change the syntax. +The Parameter keywords can appear in any order in the comment block, but the +function or script syntax determines the order in which the parameters (and +their descriptions) appear in help topic. To change the order, change the +syntax. You can also specify a parameter description by placing a comment in the -function or script syntax immediately before the parameter variable name. -If you use both a syntax comment and a Parameter keyword, the description +function or script syntax immediately before the parameter variable name. If +you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored. ### .EXAMPLE -A sample command that uses the function or script, optionally followed -by sample output and a description. Repeat this keyword for each example. +A sample command that uses the function or script, optionally followed by +sample output and a description. Repeat this keyword for each example. ### .INPUTS The Microsoft .NET Framework types of objects that can be piped to the -function or script. You can also include a description of the input -objects. +function or script. You can also include a description of the input objects. ### .OUTPUTS -The .NET Framework type of the objects that the cmdlet returns. You can -also include a description of the returned objects. +The .NET Framework type of the objects that the cmdlet returns. You can also +include a description of the returned objects. ### .NOTES @@ -245,24 +252,24 @@ Additional information about the function or script. ### .LINK -The name of a related topic. The value appears on the line below -the ".LINK" keyword and must be preceded by a comment symbol `#` or -included in the comment block. +The name of a related topic. The value appears on the line below the ".LINK" +keyword and must be preceded by a comment symbol `#` or included in the +comment block. Repeat the ".LINK" keyword for each related topic. This content appears in the Related Links section of the help topic. The "Link" keyword content can also include a Uniform Resource Identifier -(URI) to an online version of the same help topic. The online version -opens when you use the **Online** parameter of `Get-Help`. The URI must begin -with "http" or "https". +(URI) to an online version of the same help topic. The online version opens +when you use the **Online** parameter of `Get-Help`. The URI must begin with +"http" or "https". ### .COMPONENT -The technology or feature that the function or script uses, or to which -it is related. This content appears when the `Get-Help` command includes -the **Component** parameter of `Get-Help`. +The technology or feature that the function or script uses, or to which it is +related. This content appears when the `Get-Help` command includes the +**Component** parameter of `Get-Help`. ### .ROLE @@ -276,9 +283,9 @@ command includes the **Functionality** parameter of `Get-Help`. ### .FORWARDHELPTARGETNAME -Redirects to the help topic for the specified command. You can redirect -users to any help topic, including help topics for a function, script, -cmdlet, or provider. +Redirects to the help topic for the specified command. You can redirect users +to any help topic, including help topics for a function, script, cmdlet, or +provider. ``` .FORWARDHELPTARGETNAME @@ -286,10 +293,10 @@ cmdlet, or provider. ### .FORWARDHELPCATEGORY -Specifies the help category of the item in "ForwardHelpTargetName". -Valid values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", -"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use this -keyword to avoid conflicts when there are commands with the same name. +Specifies the help category of the item in "ForwardHelpTargetName". Valid +values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", +"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use +this keyword to avoid conflicts when there are commands with the same name. ``` .FORWARDHELPCATEGORY @@ -298,7 +305,8 @@ keyword to avoid conflicts when there are commands with the same name. ### .REMOTEHELPRUNSPACE Specifies a session that contains the help topic. Enter a variable that -contains a "PSSession". This keyword is used by the [Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) +contains a "PSSession". This keyword is used by the +[Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) cmdlet to find the help topics for the exported commands. ``` @@ -313,34 +321,35 @@ Specifies an XML-based help file for the script or function. .EXTERNALHELP ``` -The "ExternalHelp" keyword is required when a function or script -is documented in XML files. Without this keyword, `Get-Help` cannot -find the XML-based help file for the function or script. +The "ExternalHelp" keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +file for the function or script. -The "ExternalHelp" keyword takes precedence over other comment-based -help keywords. If "ExternalHelp" is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches -the value of the "ExternalHelp" keyword. +The "ExternalHelp" keyword takes precedence over other comment-based help +keywords. If "ExternalHelp" is present, `Get-Help` does not display +comment-based help, even if it cannot find a help topic that matches the value +of the "ExternalHelp" keyword. -If the function is exported by a module, set the value of the -"ExternalHelp" keyword to a file name without a path. `Get-Help` looks for -the specified file name in a language-specific subdirectory of the module -directory. There are no requirements for the name of the XML-based help -file for a function, but a best practice is to use the following format: +If the function is exported by a module, set the value of the "ExternalHelp" +keyword to a file name without a path. `Get-Help` looks for the specified file +name in a language-specific subdirectory of the module directory. There are no +requirements for the name of the XML-based help file for a function, but a +best practice is to use the following format: ``` -help.xml ``` -If the function is not included in a module, include a path to the -XML-based help file. If the value includes a path and the path contains +If the function is not included in a module, include a path to the XML-based +help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in -accordance with the language fallback standards established for Windows, -just as it does in a module directory. +accordance with the language fallback standards established for Windows, just +as it does in a module directory. -For more information about the cmdlet help XML-based help file format, -see [How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in the MSDN library. +For more information about the cmdlet help XML-based help file format, see +[How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in +the MSDN library. ## AUTOGENERATED CONTENT @@ -349,41 +358,40 @@ parameters, and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The "Name" section of a function help topic is taken from the function -name in the function syntax. The "Name" of a script help topic is -taken from the script file name. To change the name or its -capitalization, change the function syntax or the script file name. +The "Name" section of a function help topic is taken from the function name in +the function syntax. The "Name" of a script help topic is taken from the +script file name. To change the name or its capitalization, change the +function syntax or the script file name. ### Syntax -The "Syntax" section of the help topic is generated from the function -or script syntax. To add detail to the help topic syntax, such as -the .NET Framework type of a parameter, add the detail to the syntax. -If you do not specify a parameter type, the "Object" type is -inserted as the default value. +The "Syntax" section of the help topic is generated from the function or +script syntax. To add detail to the help topic syntax, such as the .NET +Framework type of a parameter, add the detail to the syntax. If you do not +specify a parameter type, the "Object" type is inserted as the default value. ### Parameter List -The "Parameter list" in the help topic is generated from the function -or script syntax and from the descriptions that you add by using the -"Parameters" keyword. The function parameters appear in the "Parameters" -section of the help topic in the same order that they appear in -the function or script syntax. The spelling and capitalization of -parameter names is also taken from the syntax; it is not affected -by the parameter name specified by the "Parameter" keyword. +The "Parameter list" in the help topic is generated from the function or +script syntax and from the descriptions that you add by using the "Parameters" +keyword. The function parameters appear in the "Parameters" section of the +help topic in the same order that they appear in the function or script +syntax. The spelling and capitalization of parameter names is also taken from +the syntax; it is not affected by the parameter name specified by the +"Parameter" keyword. ### Common Parameters -The "Common parameters" are added to the syntax and parameter list -of the help topic, even if they have no effect. For more information -about the common parameters, see [about_CommonParameters](about_CommonParameters.md). +The "Common parameters" are added to the syntax and parameter list of the help +topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters](about_CommonParameters.md). ### Parameter Attribute Table -`Get-Help` generates the table of parameter attributes that appears -when you use the **Full** or **Parameter** parameter of `Get-help`. The value -of the "Required", "Position", and "Default" value attributes is taken -from the function or script syntax. +`Get-Help` generates the table of parameter attributes that appears when you +use the **Full** or **Parameter** parameter of `Get-help`. The value of the +"Required", "Position", and "Default" value attributes is taken from the +function or script syntax. Default values and a value for "Accept Wildcard characters" do not appear in the "Parameter attribute table" even when they are defined in the function or @@ -391,21 +399,19 @@ script. To help users, provide this information in the parameter description. ### Remarks -The "Remarks" section of the help topic is automatically generated -from the function or script name. You cannot change or affect its -content. +The "Remarks" section of the help topic is automatically generated from the +function or script name. You cannot change or affect its content. ## DISABLING COMMENT-BASED HELP -[This technique was suggested by Rich Prescott, a Windows engineer -from New York, NY.] +[This technique was suggested by Rich Prescott, a Windows engineer from New +York, NY.] -You can disable comment-based help. This makes the comment-based -help ineffective without deleting it. +You can disable comment-based help. This makes the comment-based help +ineffective without deleting it. -To disable comment-based help, enclose the comments in a here-string. To -hide the here-string, assign it to a variable or pipe it to the Out-Null -cmdlet. +To disable comment-based help, enclose the comments in a here-string. To hide +the here-string, assign it to a variable or pipe it to the Out-Null cmdlet. While it is disabled, the comment-based help has no effect. @@ -425,8 +431,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To disable the comment-based help, enclose it in a here-string, -as shown in the following example. +To disable the comment-based help, enclose it in a here-string, as shown in +the following example. ```powershell @" @@ -445,10 +451,9 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To hide the disabled comment-based help, assign the here-string to -a local variable that is not otherwise used in the function, as -shown in the following example. You can also pipe it to the [Out-Null](../Out-Null.md) -cmdlet. +To hide the disabled comment-based help, assign the here-string to a local +variable that is not otherwise used in the function, as shown in the following +example. You can also pipe it to the [Out-Null](../Out-Null.md) cmdlet. ```powershell $x = @" @@ -467,7 +472,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ## EXAMPLES @@ -504,7 +510,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension +or file name. .EXAMPLE @@ -549,11 +556,13 @@ Adds a file name extension to a supplied name. SYNTAX -Add-Extension [[-Name] ] [[-Extension] ] [] +Add-Extension [[-Name] ] [[-Extension] ] +[] DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. PARAMETERS @@ -586,7 +595,8 @@ None. You cannot pipe objects to Add-Extension. OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. Example 1 @@ -612,8 +622,8 @@ Set-Item - Parameter Descriptions in Function Syntax This example is the same as the previous one, except that the parameter -descriptions are inserted in the function syntax. This format is most -useful when the descriptions are brief. +descriptions are inserted in the function syntax. This format is most useful +when the descriptions are brief. ```powershell function Add-Extension @@ -640,7 +650,8 @@ Adds a file name extension to a supplied name. .DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. .INPUTS @@ -648,7 +659,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. .EXAMPLE @@ -678,12 +690,12 @@ Set-Item - Comment-based Help for a Script -The following sample script includes comment-based help. -Notice the blank lines between the closing "#>" and the "Param" statement. -In a script that does not have a Param statement, there must be at least -two blank lines between the final comment in the help topic and the first -function declaration. Without these blank lines, `Get-Help` associates the -help topic with the function, not the script. +The following sample script includes comment-based help. Notice the blank +lines between the closing "#>" and the "Param" statement. In a script that +does not have a Param statement, there must be at least two blank lines +between the final comment in the help topic and the first function +declaration. Without these blank lines, `Get-Help` associates the help topic +with the function, not the script. ```powershell <# @@ -722,7 +734,8 @@ C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv +C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +C:\Reports\2009\January.csv #> param ([string]$InputPath, [string]$OutPutPath) @@ -731,9 +744,9 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not -in a directory that is listed in the "Path" environment variable, the -`Get-Help` command that gets the script help must specify the script path. +The following command gets the script help. Because the script is not in a +directory that is listed in the "Path" environment variable, the `Get-Help` +command that gets the script help must specify the script path. ```powershell Get-Help -Path .\update-month.ps1 -Full @@ -813,12 +826,12 @@ C:\Reports\2009\January.csv - Redirecting to an XML File You can write XML-based help topics for functions and scripts. Although -comment-based help is easier to implement, XML-based help is required -for Updatable Help and to provide help topics in multiple languages. +comment-based help is easier to implement, XML-based help is required for +Updatable Help and to provide help topics in multiple languages. The following example shows the first few lines of the Update-Month.ps1 -script. The script uses the "ExternalHelp" keyword to specify the path to -an XML-based help topic for the script. +script. The script uses the "ExternalHelp" keyword to specify the path to an +XML-based help topic for the script. Note that the value of the "ExternalHelp" keyword appears on the same line as the keyword. Any other placement is ineffective. @@ -831,7 +844,8 @@ function Get-Data { } ... ``` -The following examples show three valid placements of the "ExternalHelp" keyword in a function. +The following examples show three valid placements of the "ExternalHelp" +keyword in a function. ```powershell function Add-Extension @@ -867,10 +881,10 @@ $name - Redirecting to a Different Help Topic -The following code is an excerpt from the beginning of the built-in -help function in Windows PowerShell, which displays one screen of help -text at a time. Because the help topic for the `Get-Help` cmdlet describes -the help function, the help function uses the "ForwardHelpTargetName" and +The following code is an excerpt from the beginning of the built-in help +function in Windows PowerShell, which displays one screen of help text at a +time. Because the help topic for the `Get-Help` cmdlet describes the help +function, the help function uses the "ForwardHelpTargetName" and "ForwardHelpCategory" keywords to redirect the user to the `Get-Help` cmdlet help topic. diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 4d6610ec5065..c7950b31389a 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -498,8 +498,8 @@ Are you sure you want to perform this action? Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is -"Y"): s +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default +is "Y"): s PS C:\ps-test> Get-Help New-Item -Parameter ItemType @@ -516,8 +516,10 @@ PS C:\ps-test> exit Confirm Are you sure you want to perform this action? -Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y +Performing operation "Create File" on Target "Destination: C:\ps-test\test +.txt". +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (defau +lt is "Y"): y Directory: C:\ps-test diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_classes.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_classes.md index e4021b159b37..7b1b33a3bcd3 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_classes.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_classes.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -8,7 +8,6 @@ description: Describes how you can use classes to create your own custom types. --- # About Classes -## about\_Classes # SHORT DESCRIPTION @@ -34,10 +33,14 @@ and each instance can have different values in its properties. ## SUPPORTED SCENARIOS -- Define custom types in Windows PowerShell by using familiar object-oriented programming constructs, such as classes, properties, methods, inheritance, etc. +- Define custom types in Windows PowerShell by using familiar object-oriented + programming constructs, such as classes, properties, methods, inheritance, + etc. - Debug types by using the Windows PowerShell language. -- Generate and handle exceptions by using formal mechanisms, and at the right level. -- Define DSC resources and their associated types by using the Windows PowerShell language. +- Generate and handle exceptions by using formal mechanisms, and at the right + level. +- Define DSC resources and their associated types by using the PowerShell + language. ## SYNTAX @@ -46,7 +49,8 @@ Classes are declared using the following syntax: ```syntax class [: [][,] [hidden] [static] ...] - [([]) {} ...] + [([]) + {} ...] [[] [hidden] [static] ...] } ``` @@ -54,7 +58,8 @@ class [: [][, =] New-Object -TypeName [[-ArgumentList] ] +[$ =] New-Object -TypeName [ + [-ArgumentList] ] ``` ```syntax @@ -459,8 +464,9 @@ Microsoft Surface Pro 4 {$null, $null, $null, $null...} ``` -Notice `Slots` property is not reported in `$r1` output; but, the size was changed. -Also, the property is available in all scopes the object is available. +Notice `Slots` property is not reported in `$r1` output; but, the size was +changed. Also, the property is available in all scopes the object is +available. ## STATIC ATTRIBUTE @@ -518,7 +524,10 @@ class Rack { [Rack]::InstalledRacks.Length [Rack]::PowerOffRacks() -(1..10).foreach({[Rack]::new("Adatum Corporation", "Standard-16", $_.ToString("Std0000"), 16)}) > $null +(1..10) | ForEach-Object { + [Rack]::new("Adatum Corporation", "Standard-16", + $_.ToString("Std0000"), 16) +} > $null ## Testing static property and method [Rack]::InstalledRacks.Length @@ -526,7 +535,6 @@ class Rack { [Rack]::InstalledRacks[3] [Rack]::PowerOffRacks() - ``` ```output @@ -559,7 +567,8 @@ keeps increasing. Validation attributes allow to test values given to properties meet defined requirements. Validations are triggered at the moment the property assignment -is invoked, except at moment the class is instantiated. See [about_functions_advanced_parameters](about_functions_advanced_parameters.md). +is invoked, except at moment the class is instantiated. See +[about_functions_advanced_parameters](about_functions_advanced_parameters.md). ### EXAMPLE: Validation Attributes @@ -584,14 +593,14 @@ Testing dev Brand Model ----- ----- -Exception setting "Brand": "The argument is null or empty. Provide an argument that is not null or empty, and then try the command again." +Exception setting "Brand": "The argument is null or empty. Provide an +argument that is not null or empty, and then try the command again." At C:\tmp\Untitled-5.ps1:11 char:1 + $dev.Brand = "" + ~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], SetValueInvocationException + + CategoryInfo : NotSpecified: (:) [], SetValueInvocationExcep +tion + FullyQualifiedErrorId : ExceptionWhenSetting - - ``` ## INHERITANCE IN POWERSHELL CLASSES @@ -694,8 +703,8 @@ $FirstRack.Location = "F03R02.J10" $ComputeServer.Brand = "Fabrikam, Inc." ## Inherited from Asset $ComputeServer.Model = "Fbk5040" ## Inherited from Asset $ComputeServer.Status = "Installed" ## Inherited from Device - $ComputeServer.ProcessorIdentifier = "x64" ## ComputeServer property - $ComputeServer.Hostname = ("r1s" + $_.ToString("000")) ## ComputeServer property + $ComputeServer.ProcessorIdentifier = "x64" ## ComputeServer + $ComputeServer.Hostname = ("r1s" + $_.ToString("000")) ## ComputeServer $FirstRack.AddDevice($ComputeServer, $_) }) @@ -710,8 +719,8 @@ Datacenter : PNW Location : F03R02.J10 Devices : {r1s000, r1s001, r1s002, r1s003...} Status : Operational -Brand : -Model : +Brand : +Model : ProcessorIdentifier : x64 Hostname : r1s000 @@ -826,4 +835,3 @@ There is no syntax to declare interfaces in PowerShell. - [about_Enum](about_Enum.md) - [about_Language_Keywords](about_language_keywords.md) - [about_Methods](about_methods.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Aliases.md index ab4fb973409d..7384d76683c2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -194,8 +194,8 @@ Get-Help about_Functions PowerShell aliases are represented by objects that are instances of the System.Management.Automation.AliasInfo class. For more information about this -type of object, see [AliasInfo Class](http://go.microsoft.com/fwlink/?LinkId=143644) -in the Microsoft Developer Network (MSDN) library. +type of object, see [AliasInfo Class][aliasinfo] in the Microsoft Developer +Network (MSDN) library. To view the properties and methods of the alias objects, get the aliases. Then, pipe them to the Get-Member cmdlet. For example: @@ -266,3 +266,6 @@ Get-Help Alias - [about_functions](about_functions.md) - [about_profiles](about_profiles.md) - [about_providers](about_providers.md) + + +[aliasinfo]: http://go.microsoft.com/fwlink/?LinkId=143644 \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 237a0e83b1cf..a08a495cb977 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -33,20 +33,29 @@ Beginning in PowerShell 3.0, the `-shr` (shift-right) and `-shl` PowerShell supports the following arithmetic operators: -|Operator|Description|Example| -|--------|-----------|-------| -| + |Adds integers; concatenates strings,
concatenates arrays, and hash tables.|`6 + 2`
`"file" + "name"`
`@(1, "one") + @(2.0, "two")`
`@{"one" = 1} + @{"two" = 2}`| -| - | Subtracts one value from another value | `6 - 2` | -| - | Makes a number a negative number | `-6`
`(Get-Date).AddDays(-1)` | -| * |Multiplies numbers, copies strings and
arrays the specified number of times.|`6 * 2`
`"!" * 3`
`@("!") * 4`| -| / |Divides two values.|`6 / 2`| -| % |Returns the remainder of a division operation.|`7 % 2`| -|-band|Bitwise AND|`5 -band 3`| -|-bnot|Bitwise NOT|`-bnot 5`| -|-bor|Bitwise OR|`5 -bor 0x03`| -|-bxor|Bitwise XOR|`5 -bxor 3`| -|-shl|Shifts bits to the left the specified number of times|`102 -shl 2`| -|-shr|Shifts bits to the right the specified number of times|`102 -shr 2`| +|Operator|Description |Example | +|--------|----------------------------------|-----------------------------| +| + |Adds integers; concatenates |`6 + 2` | +| |strings, arrays, and hash tables. |`"file" + "name"` | +| | |`@(1, "one") + @(2.0, "two")`| +| | |`@{"one" = 1} + @{"two" = 2}`| +| - |Subtracts one value from another |`6 - 2` | +| |value | | +| - |Makes a number a negative number |`-6` | +| | |`(Get-Date).AddDays(-1)` | +| * |Multiply numbers or copy strings |`6 * 2` | +| |and arrays the specified number |`@("!") * 4` | +| |of times. |`"!" * 3` | +| / |Divides two values. |`6 / 2` | +| % |Modulus - returns the remainder of|`7 % 2` | +| |a division operation. | | +|-band |Bitwise AND |`5 -band 3` | +|-bnot |Bitwise NOT |`-bnot 5` | +|-bor |Bitwise OR |`5 -bor 0x03` | +|-bxor |Bitwise XOR |`5 -bxor 3` | +|-shl |Shifts bits to the left the |`102 -shl 2` | +| |specified number of times | | +|-shr |Shifts bits to the right |`102 -shr 2` | The bitwise operators only work on integer types. @@ -54,22 +63,22 @@ The bitwise operators only work on integer types. PowerShell processes arithmetic operators in the following order: -| Precedence | Operator | Description | -|---|---|---| -|1 | `()` | Parentheses| -|2 | `-` | For a negative number or unary operator| -|3 | `*`, `/`, `%` | -|4 | `+`, `-` | For addition and subtraction| +|Precedence|Operator |Description | +|----------|---------------|---------------------------------------| +|1 | `()` |Parentheses | +|2 | `-` |For a negative number or unary operator| +|3 | `*`, `/`, `%` |For muliplication and division | +|4 | `+`, `-` |For addition and subtraction | PowerShell processes the expressions from left to right according to the precedence rules. The following examples show the effect of the precedence rules: -| Expression | Result | -|---|---| -| `3+6/3*4` | `11` | -|`3+6/(3*4)` | `3.5` | -|`(3+6)/3*4` | `12` | +|Expression |Result| +|-----------|------| +|`3+6/3*4` |`11` | +|`3+6/(3*4)`|`3.5` | +|`(3+6)/3*4`|`12` | The order in which PowerShell evaluates expressions might differ from other programming and scripting languages that you have used. The following @@ -110,10 +119,10 @@ nearest even integer. The following example shows the effect of rounding to the nearest even integer. -| Expression | Result | -|---|---| -|`[int]( 5 / 2 )` | `2` | -|`[int]( 7 / 2 )` | `4` | +|Expression |Result| +|----------------|------| +|`[int]( 5 / 2 )`|`2` | +|`[int]( 7 / 2 )`|`4` | Notice how **_5/2_ = 2.5** gets rounded to **2**. But, **_7/2_ = 3.5** gets rounded to **4**. @@ -159,13 +168,13 @@ The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object types. Assume `$array = 1,2,3`: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`$array + 16` | `1`
`2`
`3`
`16`| -|`$array + "file"` | `1`
`2`
`3`
`file`| -|`$array * 2` | `1`
`2`
`3`
`1`
`2`
`3`| -|`"file" * 3` | `filefilefile`| +|Expression |Result | +|-----------------|-----------------------| +|`"file" + 16` |`file16` | +|`$array + 16` |`1`,`2`,`3`,`16` | +|`$array + "file"`|`1`,`2`,`3`,`file` | +|`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| +|`"file" * 3` |`filefilefile` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -174,10 +183,13 @@ commutative. For example, `(a + b)` does not always equal `(b + a)`, and The following examples demonstrate this principle: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`16 + "file"` | `Cannot convert value "file" to type "System.Int32".`
`Error: "Input string was not in a correct format."`
`At line:1 char:1`
`+ 16 + "file"`| +|Expression |Result | +|-------------|-----------------------------------------------------| +|`"file" + 16`|`file16` | +|`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| +| |`Error: "Input string was not in a correct format."` | +| |`At line:1 char:1` | +| |+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -325,10 +337,11 @@ Decimal type, the result will be of the Decimal type. If the result is too large for the Decimal type, it will not be cast to Double. Instead, an error results. -| Expression | Result | -|---|---| -|`[Decimal]::maxvalue` | `79228162514264337593543950335`| -|`[Decimal]::maxvalue + 1` | `Value was either too large`
`or too small for a Decimal.`| +|Expression |Result | +|-------------------------|-----------------------------------------------| +|`[Decimal]::maxvalue` |`79228162514264337593543950335` | +|`[Decimal]::maxvalue + 1`|`Value was either too large or too small for a`| +| |`Decimal.` | ## ARITHMETIC OPERATORS AND VARIABLES @@ -336,10 +349,10 @@ You can also use arithmetic operators with variables. The operators act on the values of the variables. The following examples demonstrate the use of arithmetic operators with variables: -| Expression | Result | -|---|---| -|`$intA = 6`
`$intB = 4`
`$intA + $intB` | `10`| -|`$a = "Power"`
`$b = "Shell"`
`$a + $b` | `PowerShell`| +| Expression |Result | +|-----------------------------------------------|------------| +|`$intA = 6`
`$intB = 4`
`$intA + $intB`|`10` | +|`$a = "Power"`
`$b = "Shell"`
`$a + $b`|`PowerShell`| ## ARITHMETIC OPERATORS AND COMMANDS @@ -377,27 +390,6 @@ In the above expression, each process working space (`$_.ws`) is multiplied by `2`; and, the result, compared against `50mb` to see if it is greater than that. -### EXAMPLES - -The following examples show how to use the arithmetic operators in -PowerShell: - -|Expression|Result| -|----------|------| -|`1 + 1` | `2` | -|`1 - 1` | `0` | -|`-(6 + 3)`| `-9` | -|`6 * 2` | `12` | -|`7 / 2` | `3.5`| -|`7 % 2` | `1` | -|`'w' * 3` | `www`| -|`3 * 'w'` | `Cannot convert value "w" to type "System.Int32".`
` Error: "Input string was not in a correct format."`| -|`"Power" + "Shell"` | `PowerShell`| -|`$a = "Power" + "Shell"`
`$a[5]` | `S`| -|`$b = 1,2,3`
`$b + 4` | `1`
`2`
`3`
`4`| -|`$servers = @{`
  `0 = "LocalHost"`
  `1 = "Server01"`
  `2 = "Server02"`
`}`
`$servers + @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| -|`#Use assignment operator`
`$servers += @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| - ## Bitwise Operators PowerShell supports the standard bitwise operators, including bitwise-AND @@ -484,11 +476,11 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shl 0` | 21 | 0001 0101 | -|`21 -shl 1` | 42 | 0010 1010 | -|`21 -shl 2` | 84 | 0101 0100 | +|Expression |Result|Binary Result| +|-----------|------|-------------| +|`21 -shl 0`|21 |0001 0101 | +|`21 -shl 1`|42 |0010 1010 | +|`21 -shl 2`|84 |0101 0100 | In a bitwise shift-right operation, all bits are moved "n" places to the right, where "n" is specified by the right operand. The shift-right @@ -501,19 +493,19 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shr 0` | 21 | 0001 0101 | -|`21 -shr 1` | 10 | 0000 1010 | -|`21 -shr 2` | 5 | 0000 0101 | -|`21 -shr 31` | 0 | 0000 0000 | -|`21 -shr 32` | 21 | 0001 0101 | -|`21 -shr 64` | 21 | 0001 0101 | -|`21 -shr 65` | 10 | 0000 1010 | -|`21 -shr 66` | 5 | 0000 0101 | -|`[int]::MaxValue -shr 1` | 1073741823 | 0011 1111 1111 1111 1111 1111 1111 1111 | -|`[int]::MinValue -shr 1` | -1073741824 | 1100 0000 0000 0000 0000 0000 0000 0000 | -|`-1 -shr 1` | -1 | 1111 1111 1111 1111 1111 1111 1111 1111 | +|Expression |Result |Binary |Hex | +|------------------------|------------|-----------|------------| +|`21 -shr 0` | 21 | 0001 0101 | 0x15 | +|`21 -shr 1` | 10 | 0000 1010 | 0x0A | +|`21 -shr 2` | 5 | 0000 0101 | 0x05 | +|`21 -shr 31` | 0 | 0000 0000 | 0x00 | +|`21 -shr 32` | 21 | 0001 0101 | 0x15 | +|`21 -shr 64` | 21 | 0001 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x15 | +|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | +|`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | +|`-1 -shr 1` | -1 | | 0xFFFFFFFF | ## SEE ALSO diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index 0f8a7fb028c2..34af56c3eab2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-24 +ms.date: 2017-11-27 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators @@ -18,16 +18,21 @@ perform numeric operations on the values before the assignment. Windows PowerShell supports the following assignment operators. -| Operator | Description | -| ------- | ----------- | -| = | Sets the value of a variable to the specified value. | -| += | Increases the value of a variable by the specified value, or appends the specified value to the existing value. | -|-= | Decreases the value of a variable by the specified value. | -| *= | Multiplies the value of a variable by the specified value, or appends the specified value to the existing value. | -| /= | Divides the value of a variable by the specified value. | -| %= | Divides the value of a variable by the specified value and then assigns the remainder (modulus) to the variable. | -| ++ | Increases the value of a variable, assignable property, or array element by 1. | -| -- | Decreases the value of a variable, assignable property, or array element by 1. | +|Operator|Description | +|--------|-------------------------------------------------------------| +|= |Sets the value of a variable to the specified value. | +|+= |Increases the value of a variable by the specified value, or | +| |appends the specified value to the existing value. | +|-= |Decreases the value of a variable by the specified value. | +|*= |Multiplies the value of a variable by the specified value, or| +| |appends the specified value to the existing value. | +|/= |Divides the value of a variable by the specified value. | +|%= |Divides the value of a variable by the specified value and | +| |then assigns the remainder (modulus) to the variable. | +|++ |Increases the value of a variable, assignable property, or | +| |array element by 1. | +|-- |Decreases the value of a variable, assignable property, or | +| |array element by 1. | ## SYNTAX @@ -335,8 +340,8 @@ $a You cannot use the `-=` operator to delete the values of a variable. To delete all the values that are assigned to a variable, use the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) or -[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) cmdlets -to assign a value of `$null` or `""` to the variable. +[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) +cmdlets to assign a value of `$null` or `""` to the variable. ```powershell $a = $null diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 85f7b0567465..0fe7b2fae3a1 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -251,7 +251,8 @@ were ignored. ```powershell $calendar = @($null, $null, “Meeting”, $null, $null, “Team Lunch”, $null) -$days = Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" +$days = "Sunday","Monday","Tuesday","Wednesday","Thursday", + "Friday","Saturday" $currentDay = 0 foreach($day in $calendar) { diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md index e4021b159b37..1b1047daace5 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -8,7 +8,6 @@ description: Describes how you can use classes to create your own custom types. --- # About Classes -## about\_Classes # SHORT DESCRIPTION @@ -34,10 +33,14 @@ and each instance can have different values in its properties. ## SUPPORTED SCENARIOS -- Define custom types in Windows PowerShell by using familiar object-oriented programming constructs, such as classes, properties, methods, inheritance, etc. +- Define custom types in Windows PowerShell by using familiar object-oriented + programming constructs, such as classes, properties, methods, inheritance, + etc. - Debug types by using the Windows PowerShell language. -- Generate and handle exceptions by using formal mechanisms, and at the right level. -- Define DSC resources and their associated types by using the Windows PowerShell language. +- Generate and handle exceptions by using formal mechanisms, and at the right + level. +- Define DSC resources and their associated types by using the PowerShell + language. ## SYNTAX @@ -46,7 +49,8 @@ Classes are declared using the following syntax: ```syntax class [: [][,] [hidden] [static] ...] - [([]) {} ...] + [([]) + {} ...] [[] [hidden] [static] ...] } ``` @@ -54,7 +58,8 @@ class [: [][, =] New-Object -TypeName [[-ArgumentList] ] +[$ =] New-Object -TypeName [ + [-ArgumentList] ] ``` ```syntax @@ -459,8 +464,9 @@ Microsoft Surface Pro 4 {$null, $null, $null, $null...} ``` -Notice `Slots` property is not reported in `$r1` output; but, the size was changed. -Also, the property is available in all scopes the object is available. +Notice `Slots` property is not reported in `$r1` output; but, the size was +changed. Also, the property is available in all scopes the object is +available. ## STATIC ATTRIBUTE @@ -518,7 +524,10 @@ class Rack { [Rack]::InstalledRacks.Length [Rack]::PowerOffRacks() -(1..10).foreach({[Rack]::new("Adatum Corporation", "Standard-16", $_.ToString("Std0000"), 16)}) > $null +(1..10) | ForEach-Object { + [Rack]::new("Adatum Corporation", "Standard-16", + $_.ToString("Std0000"), 16) +} > $null ## Testing static property and method [Rack]::InstalledRacks.Length @@ -526,7 +535,6 @@ class Rack { [Rack]::InstalledRacks[3] [Rack]::PowerOffRacks() - ``` ```output @@ -559,7 +567,8 @@ keeps increasing. Validation attributes allow to test values given to properties meet defined requirements. Validations are triggered at the moment the property assignment -is invoked, except at moment the class is instantiated. See [about_functions_advanced_parameters](about_functions_advanced_parameters.md). +is invoked, except at moment the class is instantiated. See +[about_functions_advanced_parameters](about_functions_advanced_parameters.md). ### EXAMPLE: Validation Attributes @@ -584,14 +593,14 @@ Testing dev Brand Model ----- ----- -Exception setting "Brand": "The argument is null or empty. Provide an argument that is not null or empty, and then try the command again." +Exception setting "Brand": "The argument is null or empty. Provide an +argument that is not null or empty, and then try the command again." At C:\tmp\Untitled-5.ps1:11 char:1 + $dev.Brand = "" + ~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], SetValueInvocationException + + CategoryInfo : NotSpecified: (:) [], SetValueInvocationExcep +tion + FullyQualifiedErrorId : ExceptionWhenSetting - - ``` ## INHERITANCE IN POWERSHELL CLASSES @@ -694,8 +703,8 @@ $FirstRack.Location = "F03R02.J10" $ComputeServer.Brand = "Fabrikam, Inc." ## Inherited from Asset $ComputeServer.Model = "Fbk5040" ## Inherited from Asset $ComputeServer.Status = "Installed" ## Inherited from Device - $ComputeServer.ProcessorIdentifier = "x64" ## ComputeServer property - $ComputeServer.Hostname = ("r1s" + $_.ToString("000")) ## ComputeServer property + $ComputeServer.ProcessorIdentifier = "x64" ## ComputeServer + $ComputeServer.Hostname = ("r1s" + $_.ToString("000")) ## ComputeServer $FirstRack.AddDevice($ComputeServer, $_) }) @@ -710,8 +719,8 @@ Datacenter : PNW Location : F03R02.J10 Devices : {r1s000, r1s001, r1s002, r1s003...} Status : Operational -Brand : -Model : +Brand : +Model : ProcessorIdentifier : x64 Hostname : r1s000 @@ -825,5 +834,4 @@ There is no syntax to declare interfaces in PowerShell. - [about_Enum](about_Enum.md) - [about_Language_Keywords](about_language_keywords.md) -- [about_Methods](about_methods.md) - +- [about_Methods](about_methods.md) \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 223cd9bdde41..2c2792134daf 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -17,10 +17,11 @@ Describes how to write comment-based help topics for functions and scripts. You can write comment-based help topics for functions and scripts by using special help comment keywords. -The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same format in which -it displays the cmdlet help topics that are generated from XML files. Users -can use all of the parameters of `Get-Help`, such as **Detailed**, **Full**, **Example**, -and **Online**, to display the contents of comment-based help. +The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same +format in which it displays the cmdlet help topics that are generated from XML +files. Users can use all of the parameters of `Get-Help`, such as +**Detailed**, **Full**, **Example**, and **Online**, to display the contents +of comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function @@ -31,8 +32,9 @@ This topic explains how to write help topics for functions and scripts. For information about how to display help topics for functions and scripts, see `Get-Help`. -The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets work only on XML files. Updatable Help -does not support comment-based help topics. +The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets +work only on XML files. Updatable Help does not support comment-based help +topics. ## SYNTAX FOR COMMENT-BASED HELP @@ -52,8 +54,10 @@ or #> ``` -Comment-based help is written as a series of comments. You can type a -comment symbol `#` before each line of comments, or you can use the `<#` and `#>` symbols to create a comment block. All the lines within the comment block are interpreted as comments. +Comment-based help is written as a series of comments. You can type a comment +symbol `#` before each line of comments, or you can use the `<#` and `#>` +symbols to create a comment block. All the lines within the comment block are +interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a comment-based help topic follows a comment that is not part of the help @@ -84,10 +88,9 @@ multiple lines. Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - - At the end of the function body. - -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword. +- Before the Function keyword. There cannot be more than one blank line + between the last line of the function help and the Function keyword. For example: @@ -132,11 +135,17 @@ function Get-Function { } Comment-based help for a script can appear in one of the following two locations in the script. -- At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. +- At the beginning of the script file. Script help can be preceded in the + script only by comments and blank lines. -- If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. +- If the first item in the script body (after the help) is a function + declaration, there must be at least two blank lines between the end of the + script help and the function declaration. Otherwise, the help is interpreted + as being help for the function, not help for the script. -- At the end of the script file. However, if the script is signed, place Comment-based help at the beginning of the script file. The end of the script is occupied by the signature block. +- At the end of the script file. However, if the script is signed, place + Comment-based help at the beginning of the script file. The end of the script + is occupied by the signature block. For example: @@ -162,14 +171,13 @@ function Get-Function { } ## SYNTAX FOR COMMENT-BASED HELP IN SCRIPT MODULES -In a script module `.psm1`, comment-based help uses the syntax -for functions, not the syntax for scripts. You cannot use the -script syntax to provide help for all functions defined in a -script module. +In a script module `.psm1`, comment-based help uses the syntax for functions, +not the syntax for scripts. You cannot use the script syntax to provide help +for all functions defined in a script module. -For example, if you are using the "ExternalHelp" keyword to -identify the XML-based help files for the functions in a script -module, you must add an "ExternalHelp" comment to each function. +For example, if you are using the "ExternalHelp" keyword to identify the +XML-based help files for the functions in a script module, you must add an +"ExternalHelp" comment to each function. ```powershell .ExternalHelp @@ -182,10 +190,10 @@ function ## COMMENT-BASED HELP KEYWORDS -The following are valid comment-based help keywords. They are listed in the order in -which they typically appear in a help topic along with their intended use. -These keywords can appear in any order in the comment-based help, and they -are not case-sensitive. +The following are valid comment-based help keywords. They are listed in the +order in which they typically appear in a help topic along with their intended +use. These keywords can appear in any order in the comment-based help, and +they are not case-sensitive. ### .SYNOPSIS @@ -199,45 +207,44 @@ used only once in each topic. ### .PARAMETER -The description of a parameter. Add a ".PARAMETER" keyword for -each parameter in the function or script syntax. +The description of a parameter. Add a ".PARAMETER" keyword for each parameter +in the function or script syntax. -Type the parameter name on the same line as the ".PARAMETER" keyword. -Type the parameter description on the lines following the ".PARAMETER" -keyword. Windows PowerShell interprets all text between the ".PARAMETER" -line and the next keyword or the end of the comment block as part of -the parameter description. The description can include paragraph breaks. +Type the parameter name on the same line as the ".PARAMETER" keyword. Type the +parameter description on the lines following the ".PARAMETER" keyword. Windows +PowerShell interprets all text between the ".PARAMETER" line and the next +keyword or the end of the comment block as part of the parameter description. +The description can include paragraph breaks. ``` .PARAMETER ``` -The Parameter keywords can appear in any order in the comment block, but -the function or script syntax determines the order in which the parameters -(and their descriptions) appear in help topic. To change the order, -change the syntax. +The Parameter keywords can appear in any order in the comment block, but the +function or script syntax determines the order in which the parameters (and +their descriptions) appear in help topic. To change the order, change the +syntax. You can also specify a parameter description by placing a comment in the -function or script syntax immediately before the parameter variable name. -If you use both a syntax comment and a Parameter keyword, the description +function or script syntax immediately before the parameter variable name. If +you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored. ### .EXAMPLE -A sample command that uses the function or script, optionally followed -by sample output and a description. Repeat this keyword for each example. +A sample command that uses the function or script, optionally followed by +sample output and a description. Repeat this keyword for each example. ### .INPUTS The Microsoft .NET Framework types of objects that can be piped to the -function or script. You can also include a description of the input -objects. +function or script. You can also include a description of the input objects. ### .OUTPUTS -The .NET Framework type of the objects that the cmdlet returns. You can -also include a description of the returned objects. +The .NET Framework type of the objects that the cmdlet returns. You can also +include a description of the returned objects. ### .NOTES @@ -245,24 +252,24 @@ Additional information about the function or script. ### .LINK -The name of a related topic. The value appears on the line below -the ".LINK" keyword and must be preceded by a comment symbol `#` or -included in the comment block. +The name of a related topic. The value appears on the line below the ".LINK" +keyword and must be preceded by a comment symbol `#` or included in the +comment block. Repeat the ".LINK" keyword for each related topic. This content appears in the Related Links section of the help topic. The "Link" keyword content can also include a Uniform Resource Identifier -(URI) to an online version of the same help topic. The online version -opens when you use the **Online** parameter of `Get-Help`. The URI must begin -with "http" or "https". +(URI) to an online version of the same help topic. The online version opens +when you use the **Online** parameter of `Get-Help`. The URI must begin with +"http" or "https". ### .COMPONENT -The technology or feature that the function or script uses, or to which -it is related. This content appears when the `Get-Help` command includes -the **Component** parameter of `Get-Help`. +The technology or feature that the function or script uses, or to which it is +related. This content appears when the `Get-Help` command includes the +**Component** parameter of `Get-Help`. ### .ROLE @@ -276,9 +283,9 @@ command includes the **Functionality** parameter of `Get-Help`. ### .FORWARDHELPTARGETNAME -Redirects to the help topic for the specified command. You can redirect -users to any help topic, including help topics for a function, script, -cmdlet, or provider. +Redirects to the help topic for the specified command. You can redirect users +to any help topic, including help topics for a function, script, cmdlet, or +provider. ``` .FORWARDHELPTARGETNAME @@ -286,10 +293,10 @@ cmdlet, or provider. ### .FORWARDHELPCATEGORY -Specifies the help category of the item in "ForwardHelpTargetName". -Valid values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", -"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use this -keyword to avoid conflicts when there are commands with the same name. +Specifies the help category of the item in "ForwardHelpTargetName". Valid +values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", +"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use +this keyword to avoid conflicts when there are commands with the same name. ``` .FORWARDHELPCATEGORY @@ -298,7 +305,8 @@ keyword to avoid conflicts when there are commands with the same name. ### .REMOTEHELPRUNSPACE Specifies a session that contains the help topic. Enter a variable that -contains a "PSSession". This keyword is used by the [Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) +contains a "PSSession". This keyword is used by the +[Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) cmdlet to find the help topics for the exported commands. ``` @@ -313,34 +321,35 @@ Specifies an XML-based help file for the script or function. .EXTERNALHELP ``` -The "ExternalHelp" keyword is required when a function or script -is documented in XML files. Without this keyword, `Get-Help` cannot -find the XML-based help file for the function or script. +The "ExternalHelp" keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +file for the function or script. -The "ExternalHelp" keyword takes precedence over other comment-based -help keywords. If "ExternalHelp" is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches -the value of the "ExternalHelp" keyword. +The "ExternalHelp" keyword takes precedence over other comment-based help +keywords. If "ExternalHelp" is present, `Get-Help` does not display +comment-based help, even if it cannot find a help topic that matches the value +of the "ExternalHelp" keyword. -If the function is exported by a module, set the value of the -"ExternalHelp" keyword to a file name without a path. `Get-Help` looks for -the specified file name in a language-specific subdirectory of the module -directory. There are no requirements for the name of the XML-based help -file for a function, but a best practice is to use the following format: +If the function is exported by a module, set the value of the "ExternalHelp" +keyword to a file name without a path. `Get-Help` looks for the specified file +name in a language-specific subdirectory of the module directory. There are no +requirements for the name of the XML-based help file for a function, but a +best practice is to use the following format: ``` -help.xml ``` -If the function is not included in a module, include a path to the -XML-based help file. If the value includes a path and the path contains +If the function is not included in a module, include a path to the XML-based +help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in -accordance with the language fallback standards established for Windows, -just as it does in a module directory. +accordance with the language fallback standards established for Windows, just +as it does in a module directory. -For more information about the cmdlet help XML-based help file format, -see [How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in the MSDN library. +For more information about the cmdlet help XML-based help file format, see +[How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in +the MSDN library. ## AUTOGENERATED CONTENT @@ -349,41 +358,40 @@ parameters, and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The "Name" section of a function help topic is taken from the function -name in the function syntax. The "Name" of a script help topic is -taken from the script file name. To change the name or its -capitalization, change the function syntax or the script file name. +The "Name" section of a function help topic is taken from the function name in +the function syntax. The "Name" of a script help topic is taken from the +script file name. To change the name or its capitalization, change the +function syntax or the script file name. ### Syntax -The "Syntax" section of the help topic is generated from the function -or script syntax. To add detail to the help topic syntax, such as -the .NET Framework type of a parameter, add the detail to the syntax. -If you do not specify a parameter type, the "Object" type is -inserted as the default value. +The "Syntax" section of the help topic is generated from the function or +script syntax. To add detail to the help topic syntax, such as the .NET +Framework type of a parameter, add the detail to the syntax. If you do not +specify a parameter type, the "Object" type is inserted as the default value. ### Parameter List -The "Parameter list" in the help topic is generated from the function -or script syntax and from the descriptions that you add by using the -"Parameters" keyword. The function parameters appear in the "Parameters" -section of the help topic in the same order that they appear in -the function or script syntax. The spelling and capitalization of -parameter names is also taken from the syntax; it is not affected -by the parameter name specified by the "Parameter" keyword. +The "Parameter list" in the help topic is generated from the function or +script syntax and from the descriptions that you add by using the "Parameters" +keyword. The function parameters appear in the "Parameters" section of the +help topic in the same order that they appear in the function or script +syntax. The spelling and capitalization of parameter names is also taken from +the syntax; it is not affected by the parameter name specified by the +"Parameter" keyword. ### Common Parameters -The "Common parameters" are added to the syntax and parameter list -of the help topic, even if they have no effect. For more information -about the common parameters, see [about_CommonParameters](about_CommonParameters.md). +The "Common parameters" are added to the syntax and parameter list of the help +topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters](about_CommonParameters.md). ### Parameter Attribute Table -`Get-Help` generates the table of parameter attributes that appears -when you use the **Full** or **Parameter** parameter of `Get-help`. The value -of the "Required", "Position", and "Default" value attributes is taken -from the function or script syntax. +`Get-Help` generates the table of parameter attributes that appears when you +use the **Full** or **Parameter** parameter of `Get-help`. The value of the +"Required", "Position", and "Default" value attributes is taken from the +function or script syntax. Default values and a value for "Accept Wildcard characters" do not appear in the "Parameter attribute table" even when they are defined in the function or @@ -391,21 +399,19 @@ script. To help users, provide this information in the parameter description. ### Remarks -The "Remarks" section of the help topic is automatically generated -from the function or script name. You cannot change or affect its -content. +The "Remarks" section of the help topic is automatically generated from the +function or script name. You cannot change or affect its content. ## DISABLING COMMENT-BASED HELP -[This technique was suggested by Rich Prescott, a Windows engineer -from New York, NY.] +[This technique was suggested by Rich Prescott, a Windows engineer from New +York, NY.] -You can disable comment-based help. This makes the comment-based -help ineffective without deleting it. +You can disable comment-based help. This makes the comment-based help +ineffective without deleting it. -To disable comment-based help, enclose the comments in a here-string. To -hide the here-string, assign it to a variable or pipe it to the Out-Null -cmdlet. +To disable comment-based help, enclose the comments in a here-string. To hide +the here-string, assign it to a variable or pipe it to the Out-Null cmdlet. While it is disabled, the comment-based help has no effect. @@ -425,8 +431,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To disable the comment-based help, enclose it in a here-string, -as shown in the following example. +To disable the comment-based help, enclose it in a here-string, as shown in +the following example. ```powershell @" @@ -445,10 +451,9 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To hide the disabled comment-based help, assign the here-string to -a local variable that is not otherwise used in the function, as -shown in the following example. You can also pipe it to the [Out-Null](../Out-Null.md) -cmdlet. +To hide the disabled comment-based help, assign the here-string to a local +variable that is not otherwise used in the function, as shown in the following +example. You can also pipe it to the [Out-Null](../Out-Null.md) cmdlet. ```powershell $x = @" @@ -467,7 +472,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ## EXAMPLES @@ -504,7 +510,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension +or file name. .EXAMPLE @@ -549,11 +556,13 @@ Adds a file name extension to a supplied name. SYNTAX -Add-Extension [[-Name] ] [[-Extension] ] [] +Add-Extension [[-Name] ] [[-Extension] ] +[] DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. PARAMETERS @@ -586,7 +595,8 @@ None. You cannot pipe objects to Add-Extension. OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. Example 1 @@ -612,8 +622,8 @@ Set-Item - Parameter Descriptions in Function Syntax This example is the same as the previous one, except that the parameter -descriptions are inserted in the function syntax. This format is most -useful when the descriptions are brief. +descriptions are inserted in the function syntax. This format is most useful +when the descriptions are brief. ```powershell function Add-Extension @@ -640,7 +650,8 @@ Adds a file name extension to a supplied name. .DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. .INPUTS @@ -648,7 +659,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. .EXAMPLE @@ -678,12 +690,12 @@ Set-Item - Comment-based Help for a Script -The following sample script includes comment-based help. -Notice the blank lines between the closing "#>" and the "Param" statement. -In a script that does not have a Param statement, there must be at least -two blank lines between the final comment in the help topic and the first -function declaration. Without these blank lines, `Get-Help` associates the -help topic with the function, not the script. +The following sample script includes comment-based help. Notice the blank +lines between the closing "#>" and the "Param" statement. In a script that +does not have a Param statement, there must be at least two blank lines +between the final comment in the help topic and the first function +declaration. Without these blank lines, `Get-Help` associates the help topic +with the function, not the script. ```powershell <# @@ -722,7 +734,8 @@ C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv +C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +C:\Reports\2009\January.csv #> param ([string]$InputPath, [string]$OutPutPath) @@ -731,9 +744,9 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not -in a directory that is listed in the "Path" environment variable, the -`Get-Help` command that gets the script help must specify the script path. +The following command gets the script help. Because the script is not in a +directory that is listed in the "Path" environment variable, the `Get-Help` +command that gets the script help must specify the script path. ```powershell Get-Help -Path .\update-month.ps1 -Full @@ -813,12 +826,12 @@ C:\Reports\2009\January.csv - Redirecting to an XML File You can write XML-based help topics for functions and scripts. Although -comment-based help is easier to implement, XML-based help is required -for Updatable Help and to provide help topics in multiple languages. +comment-based help is easier to implement, XML-based help is required for +Updatable Help and to provide help topics in multiple languages. The following example shows the first few lines of the Update-Month.ps1 -script. The script uses the "ExternalHelp" keyword to specify the path to -an XML-based help topic for the script. +script. The script uses the "ExternalHelp" keyword to specify the path to an +XML-based help topic for the script. Note that the value of the "ExternalHelp" keyword appears on the same line as the keyword. Any other placement is ineffective. @@ -831,7 +844,8 @@ function Get-Data { } ... ``` -The following examples show three valid placements of the "ExternalHelp" keyword in a function. +The following examples show three valid placements of the "ExternalHelp" +keyword in a function. ```powershell function Add-Extension @@ -867,10 +881,10 @@ $name - Redirecting to a Different Help Topic -The following code is an excerpt from the beginning of the built-in -help function in Windows PowerShell, which displays one screen of help -text at a time. Because the help topic for the `Get-Help` cmdlet describes -the help function, the help function uses the "ForwardHelpTargetName" and +The following code is an excerpt from the beginning of the built-in help +function in Windows PowerShell, which displays one screen of help text at a +time. Because the help topic for the `Get-Help` cmdlet describes the help +function, the help function uses the "ForwardHelpTargetName" and "ForwardHelpCategory" keywords to redirect the user to the `Get-Help` cmdlet help topic. diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 4d6610ec5065..c7950b31389a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -498,8 +498,8 @@ Are you sure you want to perform this action? Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is -"Y"): s +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default +is "Y"): s PS C:\ps-test> Get-Help New-Item -Parameter ItemType @@ -516,8 +516,10 @@ PS C:\ps-test> exit Confirm Are you sure you want to perform this action? -Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y +Performing operation "Create File" on Target "Destination: C:\ps-test\test +.txt". +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (defau +lt is "Y"): y Directory: C:\ps-test diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/6/Microsoft.PowerShell.Core/About/about_Aliases.md index ab4fb973409d..7384d76683c2 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -194,8 +194,8 @@ Get-Help about_Functions PowerShell aliases are represented by objects that are instances of the System.Management.Automation.AliasInfo class. For more information about this -type of object, see [AliasInfo Class](http://go.microsoft.com/fwlink/?LinkId=143644) -in the Microsoft Developer Network (MSDN) library. +type of object, see [AliasInfo Class][aliasinfo] in the Microsoft Developer +Network (MSDN) library. To view the properties and methods of the alias objects, get the aliases. Then, pipe them to the Get-Member cmdlet. For example: @@ -266,3 +266,6 @@ Get-Help Alias - [about_functions](about_functions.md) - [about_profiles](about_profiles.md) - [about_providers](about_providers.md) + + +[aliasinfo]: http://go.microsoft.com/fwlink/?LinkId=143644 \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 237a0e83b1cf..a08a495cb977 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -33,20 +33,29 @@ Beginning in PowerShell 3.0, the `-shr` (shift-right) and `-shl` PowerShell supports the following arithmetic operators: -|Operator|Description|Example| -|--------|-----------|-------| -| + |Adds integers; concatenates strings,
concatenates arrays, and hash tables.|`6 + 2`
`"file" + "name"`
`@(1, "one") + @(2.0, "two")`
`@{"one" = 1} + @{"two" = 2}`| -| - | Subtracts one value from another value | `6 - 2` | -| - | Makes a number a negative number | `-6`
`(Get-Date).AddDays(-1)` | -| * |Multiplies numbers, copies strings and
arrays the specified number of times.|`6 * 2`
`"!" * 3`
`@("!") * 4`| -| / |Divides two values.|`6 / 2`| -| % |Returns the remainder of a division operation.|`7 % 2`| -|-band|Bitwise AND|`5 -band 3`| -|-bnot|Bitwise NOT|`-bnot 5`| -|-bor|Bitwise OR|`5 -bor 0x03`| -|-bxor|Bitwise XOR|`5 -bxor 3`| -|-shl|Shifts bits to the left the specified number of times|`102 -shl 2`| -|-shr|Shifts bits to the right the specified number of times|`102 -shr 2`| +|Operator|Description |Example | +|--------|----------------------------------|-----------------------------| +| + |Adds integers; concatenates |`6 + 2` | +| |strings, arrays, and hash tables. |`"file" + "name"` | +| | |`@(1, "one") + @(2.0, "two")`| +| | |`@{"one" = 1} + @{"two" = 2}`| +| - |Subtracts one value from another |`6 - 2` | +| |value | | +| - |Makes a number a negative number |`-6` | +| | |`(Get-Date).AddDays(-1)` | +| * |Multiply numbers or copy strings |`6 * 2` | +| |and arrays the specified number |`@("!") * 4` | +| |of times. |`"!" * 3` | +| / |Divides two values. |`6 / 2` | +| % |Modulus - returns the remainder of|`7 % 2` | +| |a division operation. | | +|-band |Bitwise AND |`5 -band 3` | +|-bnot |Bitwise NOT |`-bnot 5` | +|-bor |Bitwise OR |`5 -bor 0x03` | +|-bxor |Bitwise XOR |`5 -bxor 3` | +|-shl |Shifts bits to the left the |`102 -shl 2` | +| |specified number of times | | +|-shr |Shifts bits to the right |`102 -shr 2` | The bitwise operators only work on integer types. @@ -54,22 +63,22 @@ The bitwise operators only work on integer types. PowerShell processes arithmetic operators in the following order: -| Precedence | Operator | Description | -|---|---|---| -|1 | `()` | Parentheses| -|2 | `-` | For a negative number or unary operator| -|3 | `*`, `/`, `%` | -|4 | `+`, `-` | For addition and subtraction| +|Precedence|Operator |Description | +|----------|---------------|---------------------------------------| +|1 | `()` |Parentheses | +|2 | `-` |For a negative number or unary operator| +|3 | `*`, `/`, `%` |For muliplication and division | +|4 | `+`, `-` |For addition and subtraction | PowerShell processes the expressions from left to right according to the precedence rules. The following examples show the effect of the precedence rules: -| Expression | Result | -|---|---| -| `3+6/3*4` | `11` | -|`3+6/(3*4)` | `3.5` | -|`(3+6)/3*4` | `12` | +|Expression |Result| +|-----------|------| +|`3+6/3*4` |`11` | +|`3+6/(3*4)`|`3.5` | +|`(3+6)/3*4`|`12` | The order in which PowerShell evaluates expressions might differ from other programming and scripting languages that you have used. The following @@ -110,10 +119,10 @@ nearest even integer. The following example shows the effect of rounding to the nearest even integer. -| Expression | Result | -|---|---| -|`[int]( 5 / 2 )` | `2` | -|`[int]( 7 / 2 )` | `4` | +|Expression |Result| +|----------------|------| +|`[int]( 5 / 2 )`|`2` | +|`[int]( 7 / 2 )`|`4` | Notice how **_5/2_ = 2.5** gets rounded to **2**. But, **_7/2_ = 3.5** gets rounded to **4**. @@ -159,13 +168,13 @@ The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object types. Assume `$array = 1,2,3`: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`$array + 16` | `1`
`2`
`3`
`16`| -|`$array + "file"` | `1`
`2`
`3`
`file`| -|`$array * 2` | `1`
`2`
`3`
`1`
`2`
`3`| -|`"file" * 3` | `filefilefile`| +|Expression |Result | +|-----------------|-----------------------| +|`"file" + 16` |`file16` | +|`$array + 16` |`1`,`2`,`3`,`16` | +|`$array + "file"`|`1`,`2`,`3`,`file` | +|`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| +|`"file" * 3` |`filefilefile` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -174,10 +183,13 @@ commutative. For example, `(a + b)` does not always equal `(b + a)`, and The following examples demonstrate this principle: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`16 + "file"` | `Cannot convert value "file" to type "System.Int32".`
`Error: "Input string was not in a correct format."`
`At line:1 char:1`
`+ 16 + "file"`| +|Expression |Result | +|-------------|-----------------------------------------------------| +|`"file" + 16`|`file16` | +|`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| +| |`Error: "Input string was not in a correct format."` | +| |`At line:1 char:1` | +| |+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -325,10 +337,11 @@ Decimal type, the result will be of the Decimal type. If the result is too large for the Decimal type, it will not be cast to Double. Instead, an error results. -| Expression | Result | -|---|---| -|`[Decimal]::maxvalue` | `79228162514264337593543950335`| -|`[Decimal]::maxvalue + 1` | `Value was either too large`
`or too small for a Decimal.`| +|Expression |Result | +|-------------------------|-----------------------------------------------| +|`[Decimal]::maxvalue` |`79228162514264337593543950335` | +|`[Decimal]::maxvalue + 1`|`Value was either too large or too small for a`| +| |`Decimal.` | ## ARITHMETIC OPERATORS AND VARIABLES @@ -336,10 +349,10 @@ You can also use arithmetic operators with variables. The operators act on the values of the variables. The following examples demonstrate the use of arithmetic operators with variables: -| Expression | Result | -|---|---| -|`$intA = 6`
`$intB = 4`
`$intA + $intB` | `10`| -|`$a = "Power"`
`$b = "Shell"`
`$a + $b` | `PowerShell`| +| Expression |Result | +|-----------------------------------------------|------------| +|`$intA = 6`
`$intB = 4`
`$intA + $intB`|`10` | +|`$a = "Power"`
`$b = "Shell"`
`$a + $b`|`PowerShell`| ## ARITHMETIC OPERATORS AND COMMANDS @@ -377,27 +390,6 @@ In the above expression, each process working space (`$_.ws`) is multiplied by `2`; and, the result, compared against `50mb` to see if it is greater than that. -### EXAMPLES - -The following examples show how to use the arithmetic operators in -PowerShell: - -|Expression|Result| -|----------|------| -|`1 + 1` | `2` | -|`1 - 1` | `0` | -|`-(6 + 3)`| `-9` | -|`6 * 2` | `12` | -|`7 / 2` | `3.5`| -|`7 % 2` | `1` | -|`'w' * 3` | `www`| -|`3 * 'w'` | `Cannot convert value "w" to type "System.Int32".`
` Error: "Input string was not in a correct format."`| -|`"Power" + "Shell"` | `PowerShell`| -|`$a = "Power" + "Shell"`
`$a[5]` | `S`| -|`$b = 1,2,3`
`$b + 4` | `1`
`2`
`3`
`4`| -|`$servers = @{`
  `0 = "LocalHost"`
  `1 = "Server01"`
  `2 = "Server02"`
`}`
`$servers + @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| -|`#Use assignment operator`
`$servers += @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| - ## Bitwise Operators PowerShell supports the standard bitwise operators, including bitwise-AND @@ -484,11 +476,11 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shl 0` | 21 | 0001 0101 | -|`21 -shl 1` | 42 | 0010 1010 | -|`21 -shl 2` | 84 | 0101 0100 | +|Expression |Result|Binary Result| +|-----------|------|-------------| +|`21 -shl 0`|21 |0001 0101 | +|`21 -shl 1`|42 |0010 1010 | +|`21 -shl 2`|84 |0101 0100 | In a bitwise shift-right operation, all bits are moved "n" places to the right, where "n" is specified by the right operand. The shift-right @@ -501,19 +493,19 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shr 0` | 21 | 0001 0101 | -|`21 -shr 1` | 10 | 0000 1010 | -|`21 -shr 2` | 5 | 0000 0101 | -|`21 -shr 31` | 0 | 0000 0000 | -|`21 -shr 32` | 21 | 0001 0101 | -|`21 -shr 64` | 21 | 0001 0101 | -|`21 -shr 65` | 10 | 0000 1010 | -|`21 -shr 66` | 5 | 0000 0101 | -|`[int]::MaxValue -shr 1` | 1073741823 | 0011 1111 1111 1111 1111 1111 1111 1111 | -|`[int]::MinValue -shr 1` | -1073741824 | 1100 0000 0000 0000 0000 0000 0000 0000 | -|`-1 -shr 1` | -1 | 1111 1111 1111 1111 1111 1111 1111 1111 | +|Expression |Result |Binary |Hex | +|------------------------|------------|-----------|------------| +|`21 -shr 0` | 21 | 0001 0101 | 0x15 | +|`21 -shr 1` | 10 | 0000 1010 | 0x0A | +|`21 -shr 2` | 5 | 0000 0101 | 0x05 | +|`21 -shr 31` | 0 | 0000 0000 | 0x00 | +|`21 -shr 32` | 21 | 0001 0101 | 0x15 | +|`21 -shr 64` | 21 | 0001 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x15 | +|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | +|`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | +|`-1 -shr 1` | -1 | | 0xFFFFFFFF | ## SEE ALSO diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/6/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index 0f8a7fb028c2..34af56c3eab2 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-24 +ms.date: 2017-11-27 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators @@ -18,16 +18,21 @@ perform numeric operations on the values before the assignment. Windows PowerShell supports the following assignment operators. -| Operator | Description | -| ------- | ----------- | -| = | Sets the value of a variable to the specified value. | -| += | Increases the value of a variable by the specified value, or appends the specified value to the existing value. | -|-= | Decreases the value of a variable by the specified value. | -| *= | Multiplies the value of a variable by the specified value, or appends the specified value to the existing value. | -| /= | Divides the value of a variable by the specified value. | -| %= | Divides the value of a variable by the specified value and then assigns the remainder (modulus) to the variable. | -| ++ | Increases the value of a variable, assignable property, or array element by 1. | -| -- | Decreases the value of a variable, assignable property, or array element by 1. | +|Operator|Description | +|--------|-------------------------------------------------------------| +|= |Sets the value of a variable to the specified value. | +|+= |Increases the value of a variable by the specified value, or | +| |appends the specified value to the existing value. | +|-= |Decreases the value of a variable by the specified value. | +|*= |Multiplies the value of a variable by the specified value, or| +| |appends the specified value to the existing value. | +|/= |Divides the value of a variable by the specified value. | +|%= |Divides the value of a variable by the specified value and | +| |then assigns the remainder (modulus) to the variable. | +|++ |Increases the value of a variable, assignable property, or | +| |array element by 1. | +|-- |Decreases the value of a variable, assignable property, or | +| |array element by 1. | ## SYNTAX @@ -335,8 +340,8 @@ $a You cannot use the `-=` operator to delete the values of a variable. To delete all the values that are assigned to a variable, use the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) or -[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) cmdlets -to assign a value of `$null` or `""` to the variable. +[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) +cmdlets to assign a value of `$null` or `""` to the variable. ```powershell $a = $null diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 275f0db3c179..0fe7b2fae3a1 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -251,7 +251,8 @@ were ignored. ```powershell $calendar = @($null, $null, “Meeting”, $null, $null, “Team Lunch”, $null) -$days = "Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" +$days = "Sunday","Monday","Tuesday","Wednesday","Thursday", + "Friday","Saturday" $currentDay = 0 foreach($day in $calendar) { diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Classes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Classes.md index e4021b159b37..1b1047daace5 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Classes.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Classes.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -8,7 +8,6 @@ description: Describes how you can use classes to create your own custom types. --- # About Classes -## about\_Classes # SHORT DESCRIPTION @@ -34,10 +33,14 @@ and each instance can have different values in its properties. ## SUPPORTED SCENARIOS -- Define custom types in Windows PowerShell by using familiar object-oriented programming constructs, such as classes, properties, methods, inheritance, etc. +- Define custom types in Windows PowerShell by using familiar object-oriented + programming constructs, such as classes, properties, methods, inheritance, + etc. - Debug types by using the Windows PowerShell language. -- Generate and handle exceptions by using formal mechanisms, and at the right level. -- Define DSC resources and their associated types by using the Windows PowerShell language. +- Generate and handle exceptions by using formal mechanisms, and at the right + level. +- Define DSC resources and their associated types by using the PowerShell + language. ## SYNTAX @@ -46,7 +49,8 @@ Classes are declared using the following syntax: ```syntax class [: [][,] [hidden] [static] ...] - [([]) {} ...] + [([]) + {} ...] [[] [hidden] [static] ...] } ``` @@ -54,7 +58,8 @@ class [: [][, =] New-Object -TypeName [[-ArgumentList] ] +[$ =] New-Object -TypeName [ + [-ArgumentList] ] ``` ```syntax @@ -459,8 +464,9 @@ Microsoft Surface Pro 4 {$null, $null, $null, $null...} ``` -Notice `Slots` property is not reported in `$r1` output; but, the size was changed. -Also, the property is available in all scopes the object is available. +Notice `Slots` property is not reported in `$r1` output; but, the size was +changed. Also, the property is available in all scopes the object is +available. ## STATIC ATTRIBUTE @@ -518,7 +524,10 @@ class Rack { [Rack]::InstalledRacks.Length [Rack]::PowerOffRacks() -(1..10).foreach({[Rack]::new("Adatum Corporation", "Standard-16", $_.ToString("Std0000"), 16)}) > $null +(1..10) | ForEach-Object { + [Rack]::new("Adatum Corporation", "Standard-16", + $_.ToString("Std0000"), 16) +} > $null ## Testing static property and method [Rack]::InstalledRacks.Length @@ -526,7 +535,6 @@ class Rack { [Rack]::InstalledRacks[3] [Rack]::PowerOffRacks() - ``` ```output @@ -559,7 +567,8 @@ keeps increasing. Validation attributes allow to test values given to properties meet defined requirements. Validations are triggered at the moment the property assignment -is invoked, except at moment the class is instantiated. See [about_functions_advanced_parameters](about_functions_advanced_parameters.md). +is invoked, except at moment the class is instantiated. See +[about_functions_advanced_parameters](about_functions_advanced_parameters.md). ### EXAMPLE: Validation Attributes @@ -584,14 +593,14 @@ Testing dev Brand Model ----- ----- -Exception setting "Brand": "The argument is null or empty. Provide an argument that is not null or empty, and then try the command again." +Exception setting "Brand": "The argument is null or empty. Provide an +argument that is not null or empty, and then try the command again." At C:\tmp\Untitled-5.ps1:11 char:1 + $dev.Brand = "" + ~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], SetValueInvocationException + + CategoryInfo : NotSpecified: (:) [], SetValueInvocationExcep +tion + FullyQualifiedErrorId : ExceptionWhenSetting - - ``` ## INHERITANCE IN POWERSHELL CLASSES @@ -694,8 +703,8 @@ $FirstRack.Location = "F03R02.J10" $ComputeServer.Brand = "Fabrikam, Inc." ## Inherited from Asset $ComputeServer.Model = "Fbk5040" ## Inherited from Asset $ComputeServer.Status = "Installed" ## Inherited from Device - $ComputeServer.ProcessorIdentifier = "x64" ## ComputeServer property - $ComputeServer.Hostname = ("r1s" + $_.ToString("000")) ## ComputeServer property + $ComputeServer.ProcessorIdentifier = "x64" ## ComputeServer + $ComputeServer.Hostname = ("r1s" + $_.ToString("000")) ## ComputeServer $FirstRack.AddDevice($ComputeServer, $_) }) @@ -710,8 +719,8 @@ Datacenter : PNW Location : F03R02.J10 Devices : {r1s000, r1s001, r1s002, r1s003...} Status : Operational -Brand : -Model : +Brand : +Model : ProcessorIdentifier : x64 Hostname : r1s000 @@ -825,5 +834,4 @@ There is no syntax to declare interfaces in PowerShell. - [about_Enum](about_Enum.md) - [about_Language_Keywords](about_language_keywords.md) -- [about_Methods](about_methods.md) - +- [about_Methods](about_methods.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 223cd9bdde41..2c2792134daf 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -17,10 +17,11 @@ Describes how to write comment-based help topics for functions and scripts. You can write comment-based help topics for functions and scripts by using special help comment keywords. -The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same format in which -it displays the cmdlet help topics that are generated from XML files. Users -can use all of the parameters of `Get-Help`, such as **Detailed**, **Full**, **Example**, -and **Online**, to display the contents of comment-based help. +The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same +format in which it displays the cmdlet help topics that are generated from XML +files. Users can use all of the parameters of `Get-Help`, such as +**Detailed**, **Full**, **Example**, and **Online**, to display the contents +of comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function @@ -31,8 +32,9 @@ This topic explains how to write help topics for functions and scripts. For information about how to display help topics for functions and scripts, see `Get-Help`. -The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets work only on XML files. Updatable Help -does not support comment-based help topics. +The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets +work only on XML files. Updatable Help does not support comment-based help +topics. ## SYNTAX FOR COMMENT-BASED HELP @@ -52,8 +54,10 @@ or #> ``` -Comment-based help is written as a series of comments. You can type a -comment symbol `#` before each line of comments, or you can use the `<#` and `#>` symbols to create a comment block. All the lines within the comment block are interpreted as comments. +Comment-based help is written as a series of comments. You can type a comment +symbol `#` before each line of comments, or you can use the `<#` and `#>` +symbols to create a comment block. All the lines within the comment block are +interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a comment-based help topic follows a comment that is not part of the help @@ -84,10 +88,9 @@ multiple lines. Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - - At the end of the function body. - -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword. +- Before the Function keyword. There cannot be more than one blank line + between the last line of the function help and the Function keyword. For example: @@ -132,11 +135,17 @@ function Get-Function { } Comment-based help for a script can appear in one of the following two locations in the script. -- At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. +- At the beginning of the script file. Script help can be preceded in the + script only by comments and blank lines. -- If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. +- If the first item in the script body (after the help) is a function + declaration, there must be at least two blank lines between the end of the + script help and the function declaration. Otherwise, the help is interpreted + as being help for the function, not help for the script. -- At the end of the script file. However, if the script is signed, place Comment-based help at the beginning of the script file. The end of the script is occupied by the signature block. +- At the end of the script file. However, if the script is signed, place + Comment-based help at the beginning of the script file. The end of the script + is occupied by the signature block. For example: @@ -162,14 +171,13 @@ function Get-Function { } ## SYNTAX FOR COMMENT-BASED HELP IN SCRIPT MODULES -In a script module `.psm1`, comment-based help uses the syntax -for functions, not the syntax for scripts. You cannot use the -script syntax to provide help for all functions defined in a -script module. +In a script module `.psm1`, comment-based help uses the syntax for functions, +not the syntax for scripts. You cannot use the script syntax to provide help +for all functions defined in a script module. -For example, if you are using the "ExternalHelp" keyword to -identify the XML-based help files for the functions in a script -module, you must add an "ExternalHelp" comment to each function. +For example, if you are using the "ExternalHelp" keyword to identify the +XML-based help files for the functions in a script module, you must add an +"ExternalHelp" comment to each function. ```powershell .ExternalHelp @@ -182,10 +190,10 @@ function ## COMMENT-BASED HELP KEYWORDS -The following are valid comment-based help keywords. They are listed in the order in -which they typically appear in a help topic along with their intended use. -These keywords can appear in any order in the comment-based help, and they -are not case-sensitive. +The following are valid comment-based help keywords. They are listed in the +order in which they typically appear in a help topic along with their intended +use. These keywords can appear in any order in the comment-based help, and +they are not case-sensitive. ### .SYNOPSIS @@ -199,45 +207,44 @@ used only once in each topic. ### .PARAMETER -The description of a parameter. Add a ".PARAMETER" keyword for -each parameter in the function or script syntax. +The description of a parameter. Add a ".PARAMETER" keyword for each parameter +in the function or script syntax. -Type the parameter name on the same line as the ".PARAMETER" keyword. -Type the parameter description on the lines following the ".PARAMETER" -keyword. Windows PowerShell interprets all text between the ".PARAMETER" -line and the next keyword or the end of the comment block as part of -the parameter description. The description can include paragraph breaks. +Type the parameter name on the same line as the ".PARAMETER" keyword. Type the +parameter description on the lines following the ".PARAMETER" keyword. Windows +PowerShell interprets all text between the ".PARAMETER" line and the next +keyword or the end of the comment block as part of the parameter description. +The description can include paragraph breaks. ``` .PARAMETER ``` -The Parameter keywords can appear in any order in the comment block, but -the function or script syntax determines the order in which the parameters -(and their descriptions) appear in help topic. To change the order, -change the syntax. +The Parameter keywords can appear in any order in the comment block, but the +function or script syntax determines the order in which the parameters (and +their descriptions) appear in help topic. To change the order, change the +syntax. You can also specify a parameter description by placing a comment in the -function or script syntax immediately before the parameter variable name. -If you use both a syntax comment and a Parameter keyword, the description +function or script syntax immediately before the parameter variable name. If +you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored. ### .EXAMPLE -A sample command that uses the function or script, optionally followed -by sample output and a description. Repeat this keyword for each example. +A sample command that uses the function or script, optionally followed by +sample output and a description. Repeat this keyword for each example. ### .INPUTS The Microsoft .NET Framework types of objects that can be piped to the -function or script. You can also include a description of the input -objects. +function or script. You can also include a description of the input objects. ### .OUTPUTS -The .NET Framework type of the objects that the cmdlet returns. You can -also include a description of the returned objects. +The .NET Framework type of the objects that the cmdlet returns. You can also +include a description of the returned objects. ### .NOTES @@ -245,24 +252,24 @@ Additional information about the function or script. ### .LINK -The name of a related topic. The value appears on the line below -the ".LINK" keyword and must be preceded by a comment symbol `#` or -included in the comment block. +The name of a related topic. The value appears on the line below the ".LINK" +keyword and must be preceded by a comment symbol `#` or included in the +comment block. Repeat the ".LINK" keyword for each related topic. This content appears in the Related Links section of the help topic. The "Link" keyword content can also include a Uniform Resource Identifier -(URI) to an online version of the same help topic. The online version -opens when you use the **Online** parameter of `Get-Help`. The URI must begin -with "http" or "https". +(URI) to an online version of the same help topic. The online version opens +when you use the **Online** parameter of `Get-Help`. The URI must begin with +"http" or "https". ### .COMPONENT -The technology or feature that the function or script uses, or to which -it is related. This content appears when the `Get-Help` command includes -the **Component** parameter of `Get-Help`. +The technology or feature that the function or script uses, or to which it is +related. This content appears when the `Get-Help` command includes the +**Component** parameter of `Get-Help`. ### .ROLE @@ -276,9 +283,9 @@ command includes the **Functionality** parameter of `Get-Help`. ### .FORWARDHELPTARGETNAME -Redirects to the help topic for the specified command. You can redirect -users to any help topic, including help topics for a function, script, -cmdlet, or provider. +Redirects to the help topic for the specified command. You can redirect users +to any help topic, including help topics for a function, script, cmdlet, or +provider. ``` .FORWARDHELPTARGETNAME @@ -286,10 +293,10 @@ cmdlet, or provider. ### .FORWARDHELPCATEGORY -Specifies the help category of the item in "ForwardHelpTargetName". -Valid values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", -"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use this -keyword to avoid conflicts when there are commands with the same name. +Specifies the help category of the item in "ForwardHelpTargetName". Valid +values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", +"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use +this keyword to avoid conflicts when there are commands with the same name. ``` .FORWARDHELPCATEGORY @@ -298,7 +305,8 @@ keyword to avoid conflicts when there are commands with the same name. ### .REMOTEHELPRUNSPACE Specifies a session that contains the help topic. Enter a variable that -contains a "PSSession". This keyword is used by the [Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) +contains a "PSSession". This keyword is used by the +[Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) cmdlet to find the help topics for the exported commands. ``` @@ -313,34 +321,35 @@ Specifies an XML-based help file for the script or function. .EXTERNALHELP ``` -The "ExternalHelp" keyword is required when a function or script -is documented in XML files. Without this keyword, `Get-Help` cannot -find the XML-based help file for the function or script. +The "ExternalHelp" keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +file for the function or script. -The "ExternalHelp" keyword takes precedence over other comment-based -help keywords. If "ExternalHelp" is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches -the value of the "ExternalHelp" keyword. +The "ExternalHelp" keyword takes precedence over other comment-based help +keywords. If "ExternalHelp" is present, `Get-Help` does not display +comment-based help, even if it cannot find a help topic that matches the value +of the "ExternalHelp" keyword. -If the function is exported by a module, set the value of the -"ExternalHelp" keyword to a file name without a path. `Get-Help` looks for -the specified file name in a language-specific subdirectory of the module -directory. There are no requirements for the name of the XML-based help -file for a function, but a best practice is to use the following format: +If the function is exported by a module, set the value of the "ExternalHelp" +keyword to a file name without a path. `Get-Help` looks for the specified file +name in a language-specific subdirectory of the module directory. There are no +requirements for the name of the XML-based help file for a function, but a +best practice is to use the following format: ``` -help.xml ``` -If the function is not included in a module, include a path to the -XML-based help file. If the value includes a path and the path contains +If the function is not included in a module, include a path to the XML-based +help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in -accordance with the language fallback standards established for Windows, -just as it does in a module directory. +accordance with the language fallback standards established for Windows, just +as it does in a module directory. -For more information about the cmdlet help XML-based help file format, -see [How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in the MSDN library. +For more information about the cmdlet help XML-based help file format, see +[How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in +the MSDN library. ## AUTOGENERATED CONTENT @@ -349,41 +358,40 @@ parameters, and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The "Name" section of a function help topic is taken from the function -name in the function syntax. The "Name" of a script help topic is -taken from the script file name. To change the name or its -capitalization, change the function syntax or the script file name. +The "Name" section of a function help topic is taken from the function name in +the function syntax. The "Name" of a script help topic is taken from the +script file name. To change the name or its capitalization, change the +function syntax or the script file name. ### Syntax -The "Syntax" section of the help topic is generated from the function -or script syntax. To add detail to the help topic syntax, such as -the .NET Framework type of a parameter, add the detail to the syntax. -If you do not specify a parameter type, the "Object" type is -inserted as the default value. +The "Syntax" section of the help topic is generated from the function or +script syntax. To add detail to the help topic syntax, such as the .NET +Framework type of a parameter, add the detail to the syntax. If you do not +specify a parameter type, the "Object" type is inserted as the default value. ### Parameter List -The "Parameter list" in the help topic is generated from the function -or script syntax and from the descriptions that you add by using the -"Parameters" keyword. The function parameters appear in the "Parameters" -section of the help topic in the same order that they appear in -the function or script syntax. The spelling and capitalization of -parameter names is also taken from the syntax; it is not affected -by the parameter name specified by the "Parameter" keyword. +The "Parameter list" in the help topic is generated from the function or +script syntax and from the descriptions that you add by using the "Parameters" +keyword. The function parameters appear in the "Parameters" section of the +help topic in the same order that they appear in the function or script +syntax. The spelling and capitalization of parameter names is also taken from +the syntax; it is not affected by the parameter name specified by the +"Parameter" keyword. ### Common Parameters -The "Common parameters" are added to the syntax and parameter list -of the help topic, even if they have no effect. For more information -about the common parameters, see [about_CommonParameters](about_CommonParameters.md). +The "Common parameters" are added to the syntax and parameter list of the help +topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters](about_CommonParameters.md). ### Parameter Attribute Table -`Get-Help` generates the table of parameter attributes that appears -when you use the **Full** or **Parameter** parameter of `Get-help`. The value -of the "Required", "Position", and "Default" value attributes is taken -from the function or script syntax. +`Get-Help` generates the table of parameter attributes that appears when you +use the **Full** or **Parameter** parameter of `Get-help`. The value of the +"Required", "Position", and "Default" value attributes is taken from the +function or script syntax. Default values and a value for "Accept Wildcard characters" do not appear in the "Parameter attribute table" even when they are defined in the function or @@ -391,21 +399,19 @@ script. To help users, provide this information in the parameter description. ### Remarks -The "Remarks" section of the help topic is automatically generated -from the function or script name. You cannot change or affect its -content. +The "Remarks" section of the help topic is automatically generated from the +function or script name. You cannot change or affect its content. ## DISABLING COMMENT-BASED HELP -[This technique was suggested by Rich Prescott, a Windows engineer -from New York, NY.] +[This technique was suggested by Rich Prescott, a Windows engineer from New +York, NY.] -You can disable comment-based help. This makes the comment-based -help ineffective without deleting it. +You can disable comment-based help. This makes the comment-based help +ineffective without deleting it. -To disable comment-based help, enclose the comments in a here-string. To -hide the here-string, assign it to a variable or pipe it to the Out-Null -cmdlet. +To disable comment-based help, enclose the comments in a here-string. To hide +the here-string, assign it to a variable or pipe it to the Out-Null cmdlet. While it is disabled, the comment-based help has no effect. @@ -425,8 +431,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To disable the comment-based help, enclose it in a here-string, -as shown in the following example. +To disable the comment-based help, enclose it in a here-string, as shown in +the following example. ```powershell @" @@ -445,10 +451,9 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To hide the disabled comment-based help, assign the here-string to -a local variable that is not otherwise used in the function, as -shown in the following example. You can also pipe it to the [Out-Null](../Out-Null.md) -cmdlet. +To hide the disabled comment-based help, assign the here-string to a local +variable that is not otherwise used in the function, as shown in the following +example. You can also pipe it to the [Out-Null](../Out-Null.md) cmdlet. ```powershell $x = @" @@ -467,7 +472,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ## EXAMPLES @@ -504,7 +510,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension +or file name. .EXAMPLE @@ -549,11 +556,13 @@ Adds a file name extension to a supplied name. SYNTAX -Add-Extension [[-Name] ] [[-Extension] ] [] +Add-Extension [[-Name] ] [[-Extension] ] +[] DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. PARAMETERS @@ -586,7 +595,8 @@ None. You cannot pipe objects to Add-Extension. OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. Example 1 @@ -612,8 +622,8 @@ Set-Item - Parameter Descriptions in Function Syntax This example is the same as the previous one, except that the parameter -descriptions are inserted in the function syntax. This format is most -useful when the descriptions are brief. +descriptions are inserted in the function syntax. This format is most useful +when the descriptions are brief. ```powershell function Add-Extension @@ -640,7 +650,8 @@ Adds a file name extension to a supplied name. .DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. .INPUTS @@ -648,7 +659,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. .EXAMPLE @@ -678,12 +690,12 @@ Set-Item - Comment-based Help for a Script -The following sample script includes comment-based help. -Notice the blank lines between the closing "#>" and the "Param" statement. -In a script that does not have a Param statement, there must be at least -two blank lines between the final comment in the help topic and the first -function declaration. Without these blank lines, `Get-Help` associates the -help topic with the function, not the script. +The following sample script includes comment-based help. Notice the blank +lines between the closing "#>" and the "Param" statement. In a script that +does not have a Param statement, there must be at least two blank lines +between the final comment in the help topic and the first function +declaration. Without these blank lines, `Get-Help` associates the help topic +with the function, not the script. ```powershell <# @@ -722,7 +734,8 @@ C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv +C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +C:\Reports\2009\January.csv #> param ([string]$InputPath, [string]$OutPutPath) @@ -731,9 +744,9 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not -in a directory that is listed in the "Path" environment variable, the -`Get-Help` command that gets the script help must specify the script path. +The following command gets the script help. Because the script is not in a +directory that is listed in the "Path" environment variable, the `Get-Help` +command that gets the script help must specify the script path. ```powershell Get-Help -Path .\update-month.ps1 -Full @@ -813,12 +826,12 @@ C:\Reports\2009\January.csv - Redirecting to an XML File You can write XML-based help topics for functions and scripts. Although -comment-based help is easier to implement, XML-based help is required -for Updatable Help and to provide help topics in multiple languages. +comment-based help is easier to implement, XML-based help is required for +Updatable Help and to provide help topics in multiple languages. The following example shows the first few lines of the Update-Month.ps1 -script. The script uses the "ExternalHelp" keyword to specify the path to -an XML-based help topic for the script. +script. The script uses the "ExternalHelp" keyword to specify the path to an +XML-based help topic for the script. Note that the value of the "ExternalHelp" keyword appears on the same line as the keyword. Any other placement is ineffective. @@ -831,7 +844,8 @@ function Get-Data { } ... ``` -The following examples show three valid placements of the "ExternalHelp" keyword in a function. +The following examples show three valid placements of the "ExternalHelp" +keyword in a function. ```powershell function Add-Extension @@ -867,10 +881,10 @@ $name - Redirecting to a Different Help Topic -The following code is an excerpt from the beginning of the built-in -help function in Windows PowerShell, which displays one screen of help -text at a time. Because the help topic for the `Get-Help` cmdlet describes -the help function, the help function uses the "ForwardHelpTargetName" and +The following code is an excerpt from the beginning of the built-in help +function in Windows PowerShell, which displays one screen of help text at a +time. Because the help topic for the `Get-Help` cmdlet describes the help +function, the help function uses the "ForwardHelpTargetName" and "ForwardHelpCategory" keywords to redirect the user to the `Get-Help` cmdlet help topic. diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/6/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 4d6610ec5065..c7950b31389a 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -498,8 +498,8 @@ Are you sure you want to perform this action? Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is -"Y"): s +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default +is "Y"): s PS C:\ps-test> Get-Help New-Item -Parameter ItemType @@ -516,8 +516,10 @@ PS C:\ps-test> exit Confirm Are you sure you want to perform this action? -Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y +Performing operation "Create File" on Target "Destination: C:\ps-test\test +.txt". +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (defau +lt is "Y"): y Directory: C:\ps-test