diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index a3654213b88a..3888516c6096 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml # SHORT DESCRIPTION @@ -25,19 +24,19 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -Update-TypeData cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. -For example, Windows PowerShell adds a DateTime property to all -System.DateTime objects, such as the ones that the Get-Date cmdlet +For example, Windows PowerShell adds a `DateTime` property to all +`System.DateTime` objects, such as the ones that the `Get-Date` cmdlet returns. ```powershell @@ -45,25 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the DateTime property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the DateTime property to all Windows PowerShell sessions, Windows PowerShell -defines the DateTime property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). -Adding Extended Type Data to Windows PowerShell. +## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. -- The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. -- The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. -- Extended type data that is defined by using the Update-TypeData cmdlet -is added only to the current session. It is not saved in a file. +- The Types.ps1xml files in the Windows PowerShell installation directory + are loaded automatically into every Windows PowerShell session. + +- The Types.ps1xml files that modules export are loaded when the module + is imported into the current session. + +- Extended type data that is defined by using the `Update-TypeData` cmdlet + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -74,14 +75,12 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| ------------ | ----------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. | +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. -For more information about these cmdlets, see the help topic for each -cmdlet. +For more information about these cmdlets, see the help topic for each cmdlet. ## Built-in Types.ps1xml Files @@ -97,9 +96,9 @@ files to further extend the types. For example, by default, array objects (`System.Array`) have a `Length` property that lists the number of objects in the array. However, because -the name "length" does not clearly describe the property, Windows +the name "Length" does not clearly describe the property, Windows PowerShell adds an alias property named "Count" that displays the same -value. The following XML adds the `Count` property to the `System.Array` type. +value. The following XML adds the Count property to the `System.Array` type. ```xml @@ -115,38 +114,37 @@ value. The following XML adds the `Count` property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell -Get-Member -inputobject (1,2,3,4) +Get-Member -InputObject (1,2,3,4) ``` The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` - As a result, you can use either the Count property or the Length property of arrays in Windows PowerShell. For example: ```powershell -C:\PS> (1, 2, 3, 4).Count +C:\PS> (1, 2, 3, 4).count # 4 ``` ```powershell -C:\PS> (1, 2, 3, 4).Length +C:\PS> (1, 2, 3, 4).length # 4 ``` @@ -165,40 +163,40 @@ to Windows PowerShell, but it is useful to place the files in the Windows PowerShell installation directory (`$PSHOME`) or in a subdirectory of the installation directory. -When you have saved the new file, use the Update-TypeData cmdlet to add +When you have saved the new file, use the `Update-TypeData` cmdlet to add the new file to your Windows PowerShell session. If you want your types to take precedence over the types that are defined in the built-in file, -use the PrependData parameter of the Update-TypeData cmdlet. -Update-TypeData affects only the current session. To make the change to -all future sessions, export the console, or add the Update-TypeData +use the PrependData parameter of the `Update-TypeData` cmdlet. +`Update-TypeData` affects only the current session. To make the change to +all future sessions, export the console, or add the `Update-TypeData` command to your Windows PowerShell profile. -## Types.ps1xml and `Add-Member` +## Types.ps1xml and Add-Member The Types.ps1xml files add properties and methods to all the instances of the objects of the specified .NET Framework type in the affected Windows PowerShell session. However, if you need to add properties or -methods only to one instance of an object, use the Add-Member cmdlet. +methods only to one instance of an object, use the `Add-Member` cmdlet. -For more information, see `Add-Member`. +For more information, see [Add-Member](../../Microsoft.PowerShell.Utility/Add-Member.md). ## Example: Adding an `Age` Member to `FileInfo` Objects -This example shows how to add an Age property to file objects +This example shows how to add an `Age` property to file objects (`System.IO.FileInfo`). The age of a file is the difference between its creation time and the current time in days. It is easiest to use the original Types.ps1xml file as a template for the new file. The following command copies the original file to -a file called `MyTypes.ps1xml` in the `$PSHOME` directory. +a file called MyTypes.ps1xml in the `$PSHOME` directory. ```powershell Copy-Item Types.ps1xml MyTypes.ps1xml ``` Next, open the Types.ps1xml file in any XML or text editor, such -as Notepad. Because the Age property is calculated by using a script -block, find a `` tag to use as a model for the new Age +as Notepad. Because the `Age` property is calculated by using a script +block, find a `` tag to use as a model for the new `Age` property. Copy the XML between the `` and `` tags of the code to create @@ -225,7 +223,7 @@ property, which was copied from the original Types.ps1xml file. ``` Then, change the name of the .NET Framework type, the name of the -property, and the value of the script block to create an Age property +property, and the value of the script block to create an `Age` property for file objects. ```xml @@ -247,18 +245,19 @@ for file objects. After you save the file and close it, run an `Update-TypeData` command, such as the following command, to add the new Types.ps1xml file to the -current session. The command uses the PrependData parameter to place the +current session. The command uses the `PrependData` parameter to place the new file in a higher precedence order than the original file. (For more -information about Update-TypeData, see Update-TypeData.) +information about `Update-TypeData`, see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md).) ```powershell -Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml +Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml ``` To test the change, run a `Get-ChildItem` command to get the PowerShell.exe file in the `$PSHOME` directory, and then pipe the file to the `Format-List` cmdlet to list all of the properties of the file. As a -result of the change, the Age property appears in the list. +result of the change, the `Age` property appears in the list. ```powershell Get-ChildItem $PSHOME\PowerShell.exe | Format-List -Property * @@ -276,7 +275,7 @@ OriginalFilename: PowerShell.EXE # ... ``` -You can also display the Age property of the file by using the following +You can also display the `Age` property of the file by using the following command. ```powershell @@ -297,16 +296,16 @@ The type tags must contain the following tags: ``: A pair of `` tags that enclose the name of the affected .NET Framework type. -``: A pair of tags that enclose the tags for the +``: A pair of `` tags that enclose the tags for the new properties and methods that are defined for the .NET Framework type. -Any of the following member tags can be inside the tags. +Any of the following member tags can be inside the `` tags. ``: Defines a new name for an existing property. -The `` tag must have a pair of tags that specify -the name of the new property and a pair of tags +The `` tag must have a pair of `` tags that specify +the name of the new property and a pair of `` tags that specify the existing property. For example, the `Count` alias property is an alias for the `Length` @@ -330,7 +329,7 @@ The `` tag must have a pair of `` tags that specify the name of the new method and a pair of `` tags that specify the code in which the method is defined. -For example, the `Mode` property of directories (`System.IO.DirectoryInfo` +For example, the Mode property of directories (`System.IO.DirectoryInfo` objects) is a code property defined in the Windows PowerShell FileSystem provider. @@ -341,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -366,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -390,7 +393,9 @@ tags) is always "PsStandardMembers", and the names of the properties (the value of the `` tag) are one of the following: - `DefaultDisplayProperty`: A single property of an object. + - `DefaultDisplayPropertySet`: One or more properties of an object. + - `DefaultKeyPropertySet`: One or more key properties of an object. A key property identifies instances of property values, such as the ID number of items in a session history. @@ -432,7 +437,7 @@ The `` tag must have a pair of `` tags that specify the name of the new property and a pair of `` tags that specify the value of the property. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -467,7 +472,7 @@ properties for the default display of an object. You can identify the default displays by the value "PsStandardMembers" in the `` tag of a `` tag. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -505,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -542,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -553,12 +558,12 @@ For more information, see the [Windows PowerShell Software Development Kit (SDK) in the MSDN (Microsoft Developer Network) library](http://go.microsoft.com/fwlink/?LinkId=144538). -## Update-TypeData +## `Update-TypeData` To load your Types.ps1xml files into a Windows PowerShell session, run the `Update-TypeData` cmdlet. If you want the types in your file to take precedence over types in the built-in Types.ps1xml file, add the -`PrependData` parameter of `Update-TypeData`. `Update-TypeData` affects only +PrependData parameter of `Update-TypeData`. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the session, or add the `Update-TypeData` command to your Windows PowerShell profile. @@ -580,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see `about_Signing`. +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -598,4 +604,3 @@ a digital signature. For more information, see `about_Signing`. [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index b2ddd2ffb955..08ee68185fcb 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell®. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,125 +100,117 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: - -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 - Get-WmiObject Invoke-WmiMethod diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 4720a9de93dc..3888516c6096 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the DateTime property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the DateTime property to all Windows PowerShell sessions, Windows PowerShell -defines the DateTime property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. -- The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. +- The Types.ps1xml files in the Windows PowerShell installation directory + are loaded automatically into every Windows PowerShell session. -- The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. +- The Types.ps1xml files that modules export are loaded when the module + is imported into the current session. -- Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. +- Extended type data that is defined by using the `Update-TypeData` cmdlet + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,14 +75,12 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | --------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. | +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. -For more information about these cmdlets, see the help topic for each -cmdlet. +For more information about these cmdlets, see the help topic for each cmdlet. ## Built-in Types.ps1xml Files @@ -103,7 +98,7 @@ For example, by default, array objects (`System.Array`) have a `Length` property that lists the number of objects in the array. However, because the name "Length" does not clearly describe the property, Windows PowerShell adds an alias property named "Count" that displays the same -value. The following XML adds the `Count` property to the `System.Array` type. +value. The following XML adds the Count property to the `System.Array` type. ```xml @@ -119,8 +114,8 @@ value. The following XML adds the `Count` property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell Get-Member -InputObject (1,2,3,4) @@ -128,29 +123,28 @@ Get-Member -InputObject (1,2,3,4) The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` - -As a result, you can use either the `Count` property or the `Length` property +As a result, you can use either the Count property or the Length property of arrays in Windows PowerShell. For example: ```powershell -C:\PS> (1, 2, 3, 4).Count +C:\PS> (1, 2, 3, 4).count # 4 ``` ```powershell -C:\PS> (1, 2, 3, 4).Length +C:\PS> (1, 2, 3, 4).length # 4 ``` @@ -172,12 +166,12 @@ installation directory. When you have saved the new file, use the `Update-TypeData` cmdlet to add the new file to your Windows PowerShell session. If you want your types to take precedence over the types that are defined in the built-in file, -use the `PrependData` parameter of the `Update-TypeData` cmdlet. +use the PrependData parameter of the `Update-TypeData` cmdlet. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the console, or add the `Update-TypeData` command to your Windows PowerShell profile. -## Types.ps1xml and `Add-Member` +## Types.ps1xml and Add-Member The Types.ps1xml files add properties and methods to all the instances of the objects of the specified .NET Framework type in the affected @@ -188,7 +182,7 @@ For more information, see [Add-Member](../../Microsoft.PowerShell.Utility/Add-Me ## Example: Adding an `Age` Member to `FileInfo` Objects -This example shows how to add an Age property to file objects +This example shows how to add an `Age` property to file objects (`System.IO.FileInfo`). The age of a file is the difference between its creation time and the current time in days. @@ -201,7 +195,7 @@ Copy-Item Types.ps1xml MyTypes.ps1xml ``` Next, open the Types.ps1xml file in any XML or text editor, such -as Notepad. Because the Age property is calculated by using a script +as Notepad. Because the `Age` property is calculated by using a script block, find a `` tag to use as a model for the new `Age` property. @@ -257,7 +251,7 @@ information about `Update-TypeData`, see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md).) ```powershell -Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml +Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml ``` To test the change, run a `Get-ChildItem` command to get the @@ -285,11 +279,11 @@ You can also display the `Age` property of the file by using the following command. ```powershell -(Get-GhildItem $PSHOME\PowerShell.exe).Age +(Get-ChildItem $PSHOME\PowerShell.exe).Age # 16 ``` -The XML in Types.ps1xml Files +## The XML in Types.ps1xml Files The `` tag encloses all of the types that are defined in the file. There should be only one pair of `` tags. @@ -335,7 +329,7 @@ The `` tag must have a pair of `` tags that specify the name of the new method and a pair of `` tags that specify the code in which the method is defined. -For example, the Mode property of directories (System.IO.DirectoryInfo +For example, the Mode property of directories (`System.IO.DirectoryInfo` objects) is a code property defined in the Windows PowerShell FileSystem provider. @@ -346,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -371,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -439,7 +437,7 @@ The `` tag must have a pair of `` tags that specify the name of the new property and a pair of `` tags that specify the value of the property. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -474,7 +472,7 @@ properties for the default display of an object. You can identify the default displays by the value "PsStandardMembers" in the `` tag of a `` tag. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -496,7 +494,7 @@ property is always "Success". - + ``` ``: Defines a method whose value is the output of a script. @@ -512,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -549,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -565,7 +563,7 @@ library](http://go.microsoft.com/fwlink/?LinkId=144538). To load your Types.ps1xml files into a Windows PowerShell session, run the `Update-TypeData` cmdlet. If you want the types in your file to take precedence over types in the built-in Types.ps1xml file, add the -`PrependData` parameter of `Update-TypeData`. `Update-TypeData` affects only +PrependData parameter of `Update-TypeData`. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the session, or add the `Update-TypeData` command to your Windows PowerShell profile. @@ -576,8 +574,8 @@ suppress exceptions that would occur in many common types during formatting and outputting. If you are getting .NET Framework properties, you can work around the suppression of exceptions by using method syntax instead, as shown in the following example: - - ```powershell + +```powershell "hello".get_Length() ``` @@ -587,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -605,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index b2ddd2ffb955..08ee68185fcb 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell®. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,125 +100,117 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: - -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 - Get-WmiObject Invoke-WmiMethod diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md b/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md index b6abbe721641..4fbccbdc21cf 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ title: about_Using --- # About Using -## about_Using # SHORT DESCRIPTION @@ -15,47 +14,49 @@ Allows to indicate which namespaces are used in the session. # LONG DESCRIPTION - -The `using` statement allows to indicate which namespaces are used in the session. -Making easier to mention classes and members, as it requires less typing to mention them; -also, classes from modules can be referenced too. +The `using` statement allows to indicate which namespaces are used in the +session. Making easier to mention classes and members, as it requires less +typing to mention them; also, classes from modules can be referenced too. The `using` statement needs to be the first statement in the script. Syntax #1, to reference .Net Framework namespaces: + ``` using namespace <.Net-framework-namespace> ``` Syntax #2, to reference PowerShell modules: + ``` using module ``` -> **Note** The `using` statetement, for modules, is intended to surface the classes in the module. -> If the module isn't loaded, the `using` fails. +**Note**: The `using` statetement, for modules, is intended to surface the +classes in the module. If the module isn't loaded, the `using` fails. ## Example 1 The following script gets the cryptographic hash for the "Hello World" string. -Note how the `using namespace System.Text` and `using namespace System.IO` simplify -the references to `[UnicodeEncoding]` in *System.Text*; and, to `[Stream]` -and to `[MemoryStream]` in *System.IO*. - +Note how the `using namespace System.Text` and `using namespace System.IO` +simplify the references to `[UnicodeEncoding]` in *System.Text*; and, to +`[Stream]` and to `[MemoryStream]` in *System.IO*. ```powershell - using namespace System.Text - using namespace System.IO +using namespace System.Text +using namespace System.IO - [string]$string = "Hello World" - [string]$algorithm = "SHA256" ## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MACTripleDES", "MD5", "RIPEMD160" +[string]$string = "Hello World" +## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$algorithm = "SHA256" - [byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) +[byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) - [Stream]$memorystream = [MemoryStream]::new($stringbytes) - $hashfromstream = Get-FileHash -InputStream $memorystream -Algorithm $algorithm - $hashfromstream.Hash.ToString() +[Stream]$memorystream = [MemoryStream]::new($stringbytes) +$hashfromstream = Get-FileHash -InputStream $memorystream ` + -Algorithm $algorithm +$hashfromstream.Hash.ToString() ``` ## Example 2 @@ -77,4 +78,3 @@ $deck.Shuffle() [Card[]]$hand2 = $deck.Deal(5) [Card[]]$hand3 = $deck.Deal(5) ``` - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index ea2b5a898093..3888516c6096 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the `DateTime` property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the `DateTime` property to all Windows PowerShell sessions, Windows PowerShell -defines the `DateTime` property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. - The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. + are loaded automatically into every Windows PowerShell session. - The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. + is imported into the current session. - Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,18 +75,16 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | ----------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. | +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. -For more information about these cmdlets, see the help topic for each -cmdlet. +For more information about these cmdlets, see the help topic for each cmdlet. ## Built-in Types.ps1xml Files -The Types.ps1xml files in the $PSHOME directory are added automatically to +The Types.ps1xml files in the `$PSHOME` directory are added automatically to every session. The Types.ps1xml file in the Windows PowerShell installation directory @@ -103,7 +98,7 @@ For example, by default, array objects (`System.Array`) have a `Length` property that lists the number of objects in the array. However, because the name "Length" does not clearly describe the property, Windows PowerShell adds an alias property named "Count" that displays the same -value. The following XML adds the `Count` property to the `System.Array` type. +value. The following XML adds the Count property to the `System.Array` type. ```xml @@ -119,28 +114,28 @@ value. The following XML adds the `Count` property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell -Get-Member -inputobject (1,2,3,4) +Get-Member -InputObject (1,2,3,4) ``` The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` -As a result, you can use either the `Count` property or the `Length` property +As a result, you can use either the Count property or the Length property of arrays in Windows PowerShell. For example: ```powershell @@ -171,17 +166,17 @@ installation directory. When you have saved the new file, use the `Update-TypeData` cmdlet to add the new file to your Windows PowerShell session. If you want your types to take precedence over the types that are defined in the built-in file, -use the `PrependData` parameter of the `Update-TypeData` cmdlet. +use the PrependData parameter of the `Update-TypeData` cmdlet. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the console, or add the `Update-TypeData` command to your Windows PowerShell profile. -## Types.ps1xml and `Add-Member` +## Types.ps1xml and Add-Member The Types.ps1xml files add properties and methods to all the instances of the objects of the specified .NET Framework type in the affected Windows PowerShell session. However, if you need to add properties or -methods only to one instance of an object, use the Add-Member cmdlet. +methods only to one instance of an object, use the `Add-Member` cmdlet. For more information, see [Add-Member](../../Microsoft.PowerShell.Utility/Add-Member.md). @@ -193,7 +188,7 @@ its creation time and the current time in days. It is easiest to use the original Types.ps1xml file as a template for the new file. The following command copies the original file to -a file called MyTypes.ps1xml in the $PSHOME directory. +a file called MyTypes.ps1xml in the `$PSHOME` directory. ```powershell Copy-Item Types.ps1xml MyTypes.ps1xml @@ -256,13 +251,13 @@ information about `Update-TypeData`, see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md).) ```powershell -Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml +Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml ``` To test the change, run a `Get-ChildItem` command to get the PowerShell.exe file in the `$PSHOME` directory, and then pipe the file to the `Format-List` cmdlet to list all of the properties of the file. As a -result of the change, the Age property appears in the list. +result of the change, the `Age` property appears in the list. ```powershell Get-ChildItem $PSHOME\PowerShell.exe | Format-List -Property * @@ -334,7 +329,7 @@ The `` tag must have a pair of `` tags that specify the name of the new method and a pair of `` tags that specify the code in which the method is defined. -For example, the `Mode` property of directories (`System.IO.DirectoryInfo` +For example, the Mode property of directories (`System.IO.DirectoryInfo` objects) is a code property defined in the Windows PowerShell FileSystem provider. @@ -345,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -370,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -391,7 +390,7 @@ In Types.ps1xml files, the `` tag is used to define the default views of the .NET Framework objects in Windows PowerShell. In this case, the name of the member set (the value within the `` tags) is always "PsStandardMembers", and the names of the properties -(the value of the tag) are one of the following: +(the value of the `` tag) are one of the following: - `DefaultDisplayProperty`: A single property of an object. @@ -438,7 +437,7 @@ The `` tag must have a pair of `` tags that specify the name of the new property and a pair of `` tags that specify the value of the property. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -473,7 +472,7 @@ properties for the default display of an object. You can identify the default displays by the value "PsStandardMembers" in the `` tag of a `` tag. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -495,7 +494,7 @@ property is always "Success". - + ``` ``: Defines a method whose value is the output of a script. @@ -511,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -548,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -586,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -595,7 +595,7 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) -[Copy-ItemProperty](../../Microsoft.PowerShell.Management/Copy-Item.md) +[Copy-ItemProperty](../../Microsoft.PowerShell.Management/Copy-ItemProperty.md) [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) @@ -604,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index 85125adac7b3..08ee68185fcb 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell? +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,125 +100,117 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: - -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http://go.microsoft.com/fwlink/?LinkId=142219 - Get-WmiObject Invoke-WmiMethod diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md b/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md index b6abbe721641..4fbccbdc21cf 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ title: about_Using --- # About Using -## about_Using # SHORT DESCRIPTION @@ -15,47 +14,49 @@ Allows to indicate which namespaces are used in the session. # LONG DESCRIPTION - -The `using` statement allows to indicate which namespaces are used in the session. -Making easier to mention classes and members, as it requires less typing to mention them; -also, classes from modules can be referenced too. +The `using` statement allows to indicate which namespaces are used in the +session. Making easier to mention classes and members, as it requires less +typing to mention them; also, classes from modules can be referenced too. The `using` statement needs to be the first statement in the script. Syntax #1, to reference .Net Framework namespaces: + ``` using namespace <.Net-framework-namespace> ``` Syntax #2, to reference PowerShell modules: + ``` using module ``` -> **Note** The `using` statetement, for modules, is intended to surface the classes in the module. -> If the module isn't loaded, the `using` fails. +**Note**: The `using` statetement, for modules, is intended to surface the +classes in the module. If the module isn't loaded, the `using` fails. ## Example 1 The following script gets the cryptographic hash for the "Hello World" string. -Note how the `using namespace System.Text` and `using namespace System.IO` simplify -the references to `[UnicodeEncoding]` in *System.Text*; and, to `[Stream]` -and to `[MemoryStream]` in *System.IO*. - +Note how the `using namespace System.Text` and `using namespace System.IO` +simplify the references to `[UnicodeEncoding]` in *System.Text*; and, to +`[Stream]` and to `[MemoryStream]` in *System.IO*. ```powershell - using namespace System.Text - using namespace System.IO +using namespace System.Text +using namespace System.IO - [string]$string = "Hello World" - [string]$algorithm = "SHA256" ## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MACTripleDES", "MD5", "RIPEMD160" +[string]$string = "Hello World" +## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$algorithm = "SHA256" - [byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) +[byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) - [Stream]$memorystream = [MemoryStream]::new($stringbytes) - $hashfromstream = Get-FileHash -InputStream $memorystream -Algorithm $algorithm - $hashfromstream.Hash.ToString() +[Stream]$memorystream = [MemoryStream]::new($stringbytes) +$hashfromstream = Get-FileHash -InputStream $memorystream ` + -Algorithm $algorithm +$hashfromstream.Hash.ToString() ``` ## Example 2 @@ -77,4 +78,3 @@ $deck.Shuffle() [Card[]]$hand2 = $deck.Deal(5) [Card[]]$hand3 = $deck.Deal(5) ``` - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 96d2292ea00c..3888516c6096 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the `DateTime` property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the `DateTime` property to all Windows PowerShell sessions, Windows PowerShell -defines the `DateTime` property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. - The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. + are loaded automatically into every Windows PowerShell session. - The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. + is imported into the current session. - Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,11 +75,10 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | --------------------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. For more information about these cmdlets, see the help topic for each cmdlet. @@ -118,8 +114,8 @@ value. The following XML adds the Count property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell Get-Member -InputObject (1,2,3,4) @@ -127,15 +123,15 @@ Get-Member -InputObject (1,2,3,4) The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` @@ -344,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -369,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -510,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -547,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -585,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -603,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index 8f2a53213e37..08ee68185fcb 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,123 +100,116 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` - +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 Get-WmiObject diff --git a/reference/6/Microsoft.PowerShell.Core/About/About_Using.md b/reference/6/Microsoft.PowerShell.Core/About/About_Using.md index f834a0324955..4fbccbdc21cf 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/About_Using.md +++ b/reference/6/Microsoft.PowerShell.Core/About/About_Using.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ title: about_Using --- # About Using -## about_Using # SHORT DESCRIPTION @@ -15,47 +14,49 @@ Allows to indicate which namespaces are used in the session. # LONG DESCRIPTION - -The `using` statement allows to indicate which namespaces are used in the session. -Making easier to mention classes and members, as it requires less typing to mention them; -also, classes from modules can be referenced too. +The `using` statement allows to indicate which namespaces are used in the +session. Making easier to mention classes and members, as it requires less +typing to mention them; also, classes from modules can be referenced too. The `using` statement needs to be the first statement in the script. Syntax #1, to reference .Net Framework namespaces: + ``` using namespace <.Net-framework-namespace> ``` Syntax #2, to reference PowerShell modules: + ``` using module ``` -> **Note** The `using` statetement, for modules, is intended to surface the classes in the module. -> If the module isn't loaded, the `using` fails. +**Note**: The `using` statetement, for modules, is intended to surface the +classes in the module. If the module isn't loaded, the `using` fails. ## Example 1 The following script gets the cryptographic hash for the "Hello World" string. -Note how the `using namespace System.Text` and `using namespace System.IO` simplify -the references to `[UnicodeEncoding]` in *System.Text*; and, to `[Stream]` -and to `[MemoryStream]` in *System.IO*. - +Note how the `using namespace System.Text` and `using namespace System.IO` +simplify the references to `[UnicodeEncoding]` in *System.Text*; and, to +`[Stream]` and to `[MemoryStream]` in *System.IO*. ```powershell - using namespace System.Text - using namespace System.IO +using namespace System.Text +using namespace System.IO - [string]$string = "Hello World" - [string]$algorithm = "SHA256" ## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$string = "Hello World" +## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$algorithm = "SHA256" - [byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) +[byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) - [Stream]$memorystream = [MemoryStream]::new($stringbytes) - $hashfromstream = Get-FileHash -InputStream $memorystream -Algorithm $algorithm - $hashfromstream.Hash.ToString() +[Stream]$memorystream = [MemoryStream]::new($stringbytes) +$hashfromstream = Get-FileHash -InputStream $memorystream ` + -Algorithm $algorithm +$hashfromstream.Hash.ToString() ``` ## Example 2 @@ -77,4 +78,3 @@ $deck.Shuffle() [Card[]]$hand2 = $deck.Deal(5) [Card[]]$hand3 = $deck.Deal(5) ``` - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Split.md b/reference/6/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 96d2292ea00c..3888516c6096 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the `DateTime` property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the `DateTime` property to all Windows PowerShell sessions, Windows PowerShell -defines the `DateTime` property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. - The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. + are loaded automatically into every Windows PowerShell session. - The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. + is imported into the current session. - Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,11 +75,10 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | --------------------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. For more information about these cmdlets, see the help topic for each cmdlet. @@ -118,8 +114,8 @@ value. The following XML adds the Count property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell Get-Member -InputObject (1,2,3,4) @@ -127,15 +123,15 @@ Get-Member -InputObject (1,2,3,4) The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` @@ -344,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -369,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -510,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -547,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -585,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -603,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index 8f2a53213e37..08ee68185fcb 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,123 +100,116 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` - +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 Get-WmiObject diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Windows_RT.md b/reference/6/Microsoft.PowerShell.Core/About/about_Windows_RT.md deleted file mode 100644 index b58501e4a35e..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Windows_RT.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_Windows_RT ---- - -# About Windows RT -## about_Windows_RT - - -## SHORT DESCRIPTION -Explains limitations of Windows PowerShell 4.0 on Windows RT 8.1. - - -## LONG DESCRIPTION -The Windows RT 8.1 operating system is installed on computers and devices (such as Microsoft Surface 2, on which it is the operating system that ships with the computer) that use Advanced RISC Machine (ARM) processors. - -Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, and modules, and most scripts designed for Windows PowerShell 2.0 and later releases run on Windows RT 8.1 without changes. - -Because Windows RT 8.1 does not include all Windows features, some Windows PowerShell features work differently or do not work on Windows RT-based devices. The following list explains the differences. - --- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. Windows PowerShell ISE requires Windows Presentation Foundation, which is not included in Windows RT 8.1. - --- Windows PowerShell remoting and the WinRM service are disabled by default. To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the Set-Service cmdlet to set the startup type of the WinRM service to Automatic, or Automatic (Delayed Start). - -While remoting is disabled, you can use Windows PowerShell remoting to run commands on other computers, but other computers cannot run commands on the Windows RT device. Also, implicit remoting—that is, remoting that is built in to a cmdlet or script, and not explicitly requested with added parameters—does not work in Windows PowerShell running on Windows RT 8.1. - --- Domain-joined computing and Kerberos authentication are not supported on Windows RT 8.1. You cannot use Windows PowerShell to add or manage these features. - --- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 are also not supported by Windows PowerShell on Windows RT 8.1. - --- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such as Start-Transaction, and transaction parameters, such as UseTransaction, do not work properly. - --- All Windows PowerShell sessions on Windows RT 8.1 devices use the ConstrainedLanguage language mode. ConstrainedLanguage language mode is a companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets and Windows PowerShell language elements, but restricts types to ensure that users cannot use Windows PowerShell to circumvent or violate the UMCI protections. - -For more information about ConstrainedLanguage language mode, see about_Language_Modes. - -## SEE ALSO - -[about_Language_Modes](about_Language_Modes.md) - -[about_Remote](about_Remote.md) - -about_Workflows - -Windows PowerShell System Requirements: (http://technet.microsoft.com/library/hh857337.aspx) - -## KEYWORDS -about_ARM, about_PowerShell_on_ARM, about_PowerShell_on_Surface, about_Windows_RT_8.1 about_WindowsRT -