From 1e26c77c623e0cb166102d1a941e42467f6d7248 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 28 Nov 2017 18:20:06 -0800 Subject: [PATCH 1/5] reformatting About_* --- .../about_Functions_CmdletBindingAttribute.md | 20 +- .../About/about_Group_Policy_Settings.md | 126 ++-- .../About/about_Hash_Tables.md | 537 ++++++++--------- .../About/about_If.md | 6 +- .../About/about_Job_Details.md | 242 ++++---- .../about_Functions_CmdletBindingAttribute.md | 20 +- .../About/about_Group_Policy_Settings.md | 126 ++-- .../About/about_Hash_Tables.md | 537 ++++++++--------- .../About/about_If.md | 6 +- .../About/about_Job_Details.md | 242 ++++---- .../about_Functions_CmdletBindingAttribute.md | 20 +- .../About/about_Group_Policy_Settings.md | 126 ++-- .../About/about_Hash_Tables.md | 535 ++++++++--------- .../About/about_If.md | 6 +- .../About/about_Job_Details.md | 242 ++++---- .../about_Functions_CmdletBindingAttribute.md | 20 +- .../About/about_Group_Policy_Settings.md | 126 ++-- .../About/about_Hash_Tables.md | 534 ++++++++--------- .../About/about_If.md | 6 +- .../About/about_Job_Details.md | 242 ++++---- .../about_Functions_CmdletBindingAttribute.md | 20 +- .../About/about_Group_Policy_Settings.md | 126 ++-- .../About/about_Hash_Tables.md | 542 +++++++++--------- .../About/about_If.md | 6 +- .../About/about_Job_Details.md | 240 ++++---- 25 files changed, 2417 insertions(+), 2236 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md index 170a44e2c7e3..e2cf58d05dc1 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,13 +7,10 @@ title: about_Functions_CmdletBindingAttribute --- # About Functions CmdletBindingAttribute -## about_Functions_CmdletBindingAttribute - # SHORT DESCRIPTION -Describes the attribute that makes a function work like a -compiled cmdlet. +Describes the attribute that makes a function work like a compiled cmdlet. # LONG DESCRIPTION @@ -124,13 +121,15 @@ to an advanced function. function Get-Numbers { [CmdletBinding(SupportsPaging = $true)] param() - + $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100) - $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100) - + $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + + $FirstNumber - 1, 100) + if ($PSCmdlet.PagingParameters.IncludeTotalCount) { $TotalCountAccuracy = 1.0 - $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy) + $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, + $TotalCountAccuracy) Write-Output $TotalCount } $FirstNumber .. $LastNumber | Write-Output @@ -173,8 +172,7 @@ must be included when the parameter is used in a function. The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. You can use the Position argument to specify a position value for a parameter. For more information about the Position -argument, see about_Functions_Advanced_Parameters -(http://go.microsoft.com/fwlink/?LinkID=135173). +argument, see [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). # NOTES diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index 15463e8deb2d..ff4eed688151 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,8 +7,6 @@ title: about_Group_Policy_Settings --- # About Group Policy Settings -## about_Group_Policy_Settings - # SHORT DESCRIPTION @@ -16,28 +14,32 @@ Describes the Group Policy settings for Windows PowerShell # LONG DESCRIPTION - Windows PowerShell includes Group Policy settings to help you define consistent option values for servers in an enterprise environment. The Windows PowerShell Group Policy settings are in the following Group Policy paths: -Computer Configuration\Administrative Templates\Windows Components\Windows PowerShell -User Configuration\Administrative Templates\Windows Components\Windows PowerShell + Computer Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell + + User Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell Group policy settings in the User Configuration path take precedence over Group Policy settings in the Computer Configuration path. The policies are as follows: -Turn on Script Execution: Sets the Windows PowerShell execution -policy. -Turn on Module Logging: Sets the LogPipelineExecutionDetails -property of modules. -Set the default source path for Update-Help: -Sets the source for UpdatableHelp to -a directory, not the Internet. +- Turn on Script Execution: Sets the Windows PowerShell execution policy. +- Turn on Module Logging: Sets the LogPipelineExecutionDetails property of + modules. +- Set the default source path for Update-Help: Sets the source for + UpdatableHelp to a directory, not the Internet. To download spreadsheets that list all of the Group Policy settings for each version of Windows, see "Group Policy Settings Reference for Windows @@ -53,28 +55,27 @@ run. If you enable the policy setting, you can select from among the following policy settings. --- "Allow only signed scripts" allows scripts to execute only if they -are signed by a trusted publisher. This policy setting is equivalent -to the AllSigned execution policy. +- "Allow only signed scripts" allows scripts to execute only if they are + signed by a trusted publisher. This policy setting is equivalent to the + AllSigned execution policy. --- "Allow local scripts and remote signed scripts" allows all local -scripts to run. Scripts that originate from the Internet must be -signed by a trusted publisher. This policy setting is equivalent -to the RemoteSigned execution policy. +- "Allow local scripts and remote signed scripts" allows all local scripts to + run. Scripts that originate from the Internet must be signed by a trusted + publisher. This policy setting is equivalent to the RemoteSigned execution + policy. --- "Allow all scripts" allows all scripts to run. This policy -setting is equivalent to the Unrestricted execution policy. +- "Allow all scripts" allows all scripts to run. This policy setting is + equivalent to the Unrestricted execution policy. -If you disable this policy setting, no scripts are allowed to run. -This policy setting is equivalent to the Restricted execution policy. +If you disable this policy setting, no scripts are allowed to run. This policy +setting is equivalent to the Restricted execution policy. -If you disable or do not configure this policy setting, the execution -policy that is set for the computer or user by the Set-ExecutionPolicy -cmdlet determines whether scripts are permitted to run. The default -value is Restricted. +If you disable or do not configure this policy setting, the execution policy +that is set for the computer or user by the Set-ExecutionPolicy cmdlet +determines whether scripts are permitted to run. The default value is +Restricted. -For more information, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](about_Execution_Policies.md). # TURN ON MODULE LOGGING @@ -99,56 +100,54 @@ To turn on module logging for a module, use the following command format. The module must be imported into the session and the setting is effective only in the current session. +```powershell PS C:> Import-Module PS C:> (Get-Module ).LogPipelineExecutionDetails = $true +``` To turn on module logging for all sessions on a particular computer, add the previous commands to the all-users Windows PowerShell profile ($Profile.AllUsers.AllHosts). -For more information about module logging, see about_Modules -(http://go.microsoft.com/fwlink/?LinkID=144311). +For more information about module logging, see [about_Modules](about_Modules.md). # SET THE DEFAULT SOURCE PATH FOR UPDATE-HELP The "Set the Default Source Path for Update-Help" policy setting sets a -default value for the SourcePath parameter of the Update-Help cmdlet. -This setting prevents users from using the Update-Help cmdlet to download -help files from the Internet. +default value for the SourcePath parameter of the Update-Help cmdlet. This +setting prevents users from using the Update-Help cmdlet to download help +files from the Internet. -NOTE: The "Set the default source path for Update-Help" Group -Policy setting appears under Computer Configuration and -User Configuration. However, only the Group Policy setting -under Computer Configuration is effective. The Group Policy -setting under User Configuration is ignored. +NOTE: The "Set the default source path for Update-Help" Group Policy setting +appears under Computer Configuration and User Configuration. However, only the +Group Policy setting under Computer Configuration is effective. The Group +Policy setting under User Configuration is ignored. The Update-Help cmdlet downloads and installs the newest help files for Windows PowerShell modules and installs them on the computer. By default, -Update-Help downloads new help files from an Internet location specified -by the module. +Update-Help downloads new help files from an Internet location specified by +the module. -However, you can use the Save-Help cmdlet to download the newest help -files to a file system location, such as a network share, and then use -the Update-Help cmdlet to get the help files from the file system -location and install them on the computer. The SourcePath parameter of -the Update-Help cmdlet specifies the file system location. +However, you can use the Save-Help cmdlet to download the newest help files to +a file system location, such as a network share, and then use the Update-Help +cmdlet to get the help files from the file system location and install them on +the computer. The SourcePath parameter of the Update-Help cmdlet specifies the +file system location. -By providing a default value for the SourcePath parameter, this Group -Policy setting implicitly adds the SourcePath parameter to all Update-Help -commands. Users can override the particular file system location specified -as the default value by entering a different file system location. But they -cannot remove the SourcePath parameter from the Update-Help command. +By providing a default value for the SourcePath parameter, this Group Policy +setting implicitly adds the SourcePath parameter to all Update-Help commands. +Users can override the particular file system location specified as the +default value by entering a different file system location. But they cannot +remove the SourcePath parameter from the Update-Help command. If you enable this policy setting, you can specify a default value for the SourcePath parameter. Enter a file system location. -If this policy setting is disabled or not configured, there is no -default value for the SourcePath parameter of the Update-Help cmdlet. -Users can download help from the Internet or from any file system -location. +If this policy setting is disabled or not configured, there is no default +value for the SourcePath parameter of the `Update-Help` cmdlet. Users can +download help from the Internet or from any file system location. -For more information, see about_Updatable_Help -(http://go.microsoft.com/fwlink/?LinkID=235801). +For more information, see [about_Updatable_Help](about_Updatable_Help.md). # KEYWORDS @@ -163,13 +162,12 @@ about_GroupPolicy [about_Updatable_Help](about_Updatable_Help.md) -Get-ExecutionPolicy - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Get-Module +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -Update-Help +[Get-Module](../Get-Module.md) -Save-Help +[Update-Help](../Update-Help.md) +[Save-Help](../../Save-Help.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 34916bc2ec99..174cf4dd2d6a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,471 +7,484 @@ title: about_Hash_Tables --- # About Hash Tables -## about_Hash_Tables - ## SHORT DESCRIPTION -Describes how to create, use, and sort hash tables in Windows PowerShell. +Describes how to create, use, and sort hash tables in PowerShell. ## LONG DESCRIPTION -A hash table, also known as a dictionary or associative array, is a compact data structure that stores one or more key\/value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In Windows PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) object. You can use the properties and methods of Hashtable objects in Windows PowerShell. +A hash table, also known as a dictionary or associative array, is a compact +data structure that stores one or more key/value pairs. For example, a hash +table might contain a series of IP addresses and computer names, where the IP +addresses are the keys and the computer names are the values, or vice versa. -Beginning in Windows PowerShell 3.0, you can use the [ordered] attribute to create an ordered dictionary (System.Collections.Specialized.OrderedDictionary) in Windows PowerShell. +In PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) +object. You can use the properties and methods of Hashtable objects in +PowerShell. -Ordered dictionaries differ from hash tables in that the keys always appear in the order in which you list them. The order of keys in a hash table is not determined. +Beginning in PowerShell 3.0, you can use the [ordered] attribute to create an +ordered dictionary (System.Collections.Specialized.OrderedDictionary) in +PowerShell. -The keys and value in hash tables are also .NET objects. They are most often strings or integers, but they can have any object type. You can also create nested hash tables, in which the value of a key is another hash table. +Ordered dictionaries differ from hash tables in that the keys always appear in +the order in which you list them. The order of keys in a hash table is not +determined. -Hash tables are frequently used because they are very efficient for finding and retrieving data. You can use hash tables to store lists and to create calculated properties in Windows PowerShell. And, Windows PowerShell has a cmdlet, ConvertFrom-StringData, that converts strings to a hash table. +The keys and value in hash tables are also .NET objects. They are most often +strings or integers, but they can have any object type. You can also create +nested hash tables, in which the value of a key is another hash table. +Hash tables are frequently used because they are very efficient for finding +and retrieving data. You can use hash tables to store lists and to create +calculated properties in PowerShell. And, PowerShell has a cmdlet, +ConvertFrom-StringData, that converts strings to a hash table. ### Syntax -The syntax of a hash table is as follows: +The syntax of a hash table is as follows: -``` +```powershell @{ = ; [ = ] ...} ``` - The syntax of an ordered dictionary is as follows: - -``` +```powershell [ordered]@{ = ; [ = ] ...} ``` - -The [ordered] attribute was introduced in Windows PowerShell 3.0. - +The [ordered] attribute was introduced in PowerShell 3.0. ### Creating Hash Tables + To create a hash table, follow these guidelines: - Begin the hash table with an at sign (@). - - Enclose the hash table in braces ({}). - -- Enter one or more key\/value pairs for the content of the hash table. - -- Use an equal sign (\=) to separate each key from its value. - -- Use a semicolon (;) or a line break to separate the key\/value pairs. - -- Key that contains spaces must be enclosed in quotation marks. Values must be valid Windows PowerShell expressions. Strings must appear in quotation marks, even if they do not include spaces. - +- Enter one or more key/value pairs for the content of the hash table. +- Use an equal sign (=) to separate each key from its value. +- Use a semicolon (;) or a line break to separate the key/value pairs. +- Key that contains spaces must be enclosed in quotation marks. Values must be + valid PowerShell expressions. Strings must appear in quotation marks, even if + they do not include spaces. - To manage the hash table, save it in a variable. - -- When assigning an ordered hash table to a variable, place the [ordered] attribute before the "@" symbol. If you place it before the variable name, the command fails. +- When assigning an ordered hash table to a variable, place the [ordered] + attribute before the "@" symbol. If you place it before the variable name, the + command fails. To create an empty hash table in the value of $hash, type: - -``` +```powershell $hash = @{} ``` +You can also add keys and values to a hash table when you create it. For +example, the following statement creates a hash table with three keys. -You can also add keys and values to a hash table when you create it. For example, the following statement creates a hash table with three keys. - - -``` +```powershell $hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} ``` - - ### Creating Ordered Dictionaries -You can create an ordered dictionary by adding an object of the OrderedDictionary type, but the easiest way to create an ordered dictionary is use the [Ordered] attribute. -The [ordered] attribute is introduced in Windows PowerShell 3.0. +You can create an ordered dictionary by adding an object of the +OrderedDictionary type, but the easiest way to create an ordered dictionary is +use the [Ordered] attribute. -Place the attribute immediately before the "@" symbol. +The [ordered] attribute is introduced in PowerShell 3.0. +Place the attribute immediately before the "@" symbol. -``` +```powershell $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` +You can use ordered dictionaries in the same way that you use hash tables. +Either type can be used as the value of parameters that take a hash table or +dictionary (iDictionary). -You can use ordered dictionaries in the same way that you use hash tables. Either type can be used as the value of parameters that take a hash table or dictionary (iDictionary). +You cannot use the [ordered] attribute to convert or cast a hash table. If you +place the ordered attribute before the variable name, the command fails with +the following error message. -You cannot use the [ordered] attribute to convert or cast a hash table. If you place the ordered attribute before the variable name, the command fails with the following error message. - - -``` -PS C:\> [ordered]$hash = @{} -At line:1 char:1 -+ [ordered]$hash = @{} -+ [!INCLUDE[]()] -The ordered attribute can be specified only on a hash literal node. -+ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException +```powershell +PS C:\> [ordered]$hash = @{} +At line:1 char:1 ++ [ordered]$hash = @{} ++ [!INCLUDE[]()] +The ordered attribute can be specified only on a hash literal node. ++ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordExc +eption + FullyQualifiedErrorId : OrderedAttributeOnlyOnHashLiteralNode ``` - To correct the expression, move the [ordered] attribute. - -``` +```powershell PS C:\> $hash = [ordered]@{} ``` - -You can cast an ordered dictionary to a hash table, but you cannot recover the ordered attribute, even if you clear the variable and enter new values. To re-establish the order, you must remove and recreate the variable. - +You can cast an ordered dictionary to a hash table, but you cannot recover the +ordered attribute, even if you clear the variable and enter new values. To +re-establish the order, you must remove and recreate the variable. ``` -PS C:\> [hashtable]$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} -PS C:\ps-test> $hash - -Name Value ----- ----- -Color Blue -Shape Square +PS C:\> [hashtable]$hash = [ordered]@{ +>> Number = 1; Shape = "Square"; Color = "Blue"} +PS C:\> $hash + +Name Value +---- ----- +Color Blue +Shape Square Number 1 ``` - - ### Displaying Hash Tables -To display a hash table that is saved in a variable, type the variable name. By default, a hash tables is displayed as a table with one column for keys and one for values. +To display a hash table that is saved in a variable, type the variable name. +By default, a hash tables is displayed as a table with one column for keys and +one for values. -``` -C:\PS> $hash - -Name Value ----- ----- -Shape Square -Color Blue +```powershell +C:\PS> $hash + +Name Value +---- ----- +Shape Square +Color Blue Number 1 ``` +Hash tables have Keys and Values properties. Use dot notation to display all +of the keys or all of the values. -Hash tables have Keys and Values properties. Use dot notation to display all of the keys or all of the values. +```powershell +C:\PS> $hash.keys +Number +Shape +Color - -``` -C:\PS> $hash.keys -Number -Shape -Color - -C:\PS> $hash.values -1 -Square +C:\PS> $hash.values +1 +Square Blue ``` +Each key name is also a property of the hash table, and its value is the value +of the key-name property. Use the following format to display the property +values. -Each key name is also a property of the hash table, and its value is the value of the key-name property. Use the following format to display the property values. - - -``` -$hashtable. +```powershell +$hashtable. ``` - For example: +```powershell +C:\PS> $hash.Number +1 -``` -C:\PS> $hash.Number -1 - -C:\PS> $hash.Color +C:\PS> $hash.Color Blue ``` +If the key name collides with one of the property names of the HashTable type, +you can use `PSBase` to access those properties. For example, if the key name +is `keys` and you want to return the collection of Keys, use this syntax: -Hash tables have a Count property that indicates the number of key-value pairs in the hash table. +```powershell +$hashtable.PSBase.Keys +``` +Hash tables have a Count property that indicates the number of key-value pairs +in the hash table. -``` -C:\PS> $hash.count +```powershell +C:\PS> $hash.count 3 ``` - -Hash table tables are not arrays, so you cannot use an integer as an index into the hash table, but you can use a key name to index into the hash table. If the key is a string value, enclose the key name in quotation marks. +Hash table tables are not arrays, so you cannot use an integer as an index +into the hash table, but you can use a key name to index into the hash table. +If the key is a string value, enclose the key name in quotation marks. For example: - -``` -C:\PS> $hash["Number"] +```powershell +C:\PS> $hash["Number"] 1 ``` - - ### Adding and Removing Keys and Values -To add keys and values to a hash table, use the following command format. +To add keys and values to a hash table, use the following command format. -``` +```powershell $hash[""] = "" ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash["Time"] = "Now" ``` +You can also add keys and values to a hash table by using the Add method of +the System.Collections.Hashtable object. The Add method has the following +syntax: -You can also add keys and values to a hash table by using the Add method of the System.Collections.Hashtable object. The Add method has the following syntax: - - -``` +```powershell Add(Key, Value) ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash = $hash.Add("Time", "Now") ``` +And, you can add keys and values to a hash table by using the addition +operator (+) to add a hash table to an existing hash table. For example, the +following statement adds a "Time" key with a value of "Now" to the hash table +in the $hash variable. -And, you can add keys and values to a hash table by using the addition operator (\+) to add a hash table to an existing hash table. For example, the following statement adds a "Time" key with a value of "Now" to the hash table in the $hash variable. - - -``` +```powershell $hash = $hash + @{Time="Now"} ``` - You can also add values that are stored in variables. +```powershell +$t = "Today" +$now = (Get-Date) -``` -$t = "Today" -$now = (Get-Date) - $hash.Add($t, $now) ``` - -You cannot use a subtraction operator to remove a key\/value pair from a hash table, but you can use the Remove method of the Hashtable object. The Remove method takes the key as its value. +You cannot use a subtraction operator to remove a key/value pair from a hash +table, but you can use the Remove method of the Hashtable object. The Remove +method takes the key as its value. The Remove method has the following syntax: - ``` Remove(Key) ``` +For example, to remove the Time=Now key/value pair from the hash table in the +value of the $hash variable, type: -For example, to remove the Time\=Now key\/value pair from the hash table in the value of the $hash variable, type: - - -``` -$hash.$Remove("Time") +```powershell +$hash.Remove("Time") ``` - -You can use all of the properties and methods of Hashtable objects in Windows PowerShell, including Contains, Clear, Clone, and CopyTo. For more information about Hashtable objects, see ["System.Collections.Hashtable"](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN. - +You can use all of the properties and methods of Hashtable objects in +PowerShell, including Contains, Clear, Clone, and CopyTo. For more information +about Hashtable objects, see "System.Collections.Hashtable" on MSDN. ### Object Types in HashTables -The keys and values in a hash table can have any .NET object type, and a single hash table can have keys and values of multiple types. -The following statement creates a hash table of process name strings and process object values and saves it in the $p variable. +The keys and values in a hash table can have any .NET object type, and a +single hash table can have keys and values of multiple types. +The following statement creates a hash table of process name strings and +process object values and saves it in the \$p variable. -``` -$p = @{"PowerShell" = (get-process PowerShell); +```powershell +$p = @{"PowerShell" = (get-process PowerShell); "Notepad" = (get-process notepad)} ``` +You can display the hash table in \$p and use the key-name properties to +display the values. -You can display the hash table in $p and use the key-name properties to display the values. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) - -C:\PS> $p.PowerShell - -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName -------- ------ ----- ----- ----- ------ -- ----------- - 441 24 54196 54012 571 5.10 1788 PowerShell - -C:\PS> $p.keys | foreach {$p.$_.handles} -441 -251 -``` +C:\PS> $p.PowerShell +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 441 24 54196 54012 571 5.10 1788 PowerShell -The keys in a hash table can also be any .NET type. The following statement adds a key\/value pair to the hash table in the $p variable. The key is a Service object that represents the WinRM service, and the value is the current status of the service. +C:\PS> $p.keys | foreach {$p.$_.handles} +441 +251 +``` +The keys in a hash table can also be any .NET type. The following statement +adds a key/value pair to the hash table in the \$p variable. The key is a +Service object that represents the WinRM service, and the value is the current +status of the service. -``` +```powershell C:\PS> $p = $p + @{(Get-Service WinRM) = ((Get-Service WinRM).Status)} ``` +You can display and access the new key/value pair by using the same methods +that you use for other pairs in the hash table. -You can display and access the new key\/value pair by using the same methods that you use for other pairs in the hash table. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running - -C:\PS> $p.keys -PowerShell -Notepad - -Status Name DisplayName ------- ---- ----------- -Running winrm Windows Remote Management (WS-Manag... - -C:\PS> $p.keys | foreach {$_.name} -winrm -``` +C:\PS> $p.keys +PowerShell +Notepad +Status Name DisplayName +------ ---- ----------- +Running winrm Windows Remote Management (WS-Manag... -The keys and values in a hash table can also be Hashtable objects. The following statement adds key\/value pair to the hash table in the $p variable in which the key is a string, Hash2, and the value is a hash table with three key\/value pairs. +C:\PS> $p.keys | foreach {$_.name} +winrm +``` +The keys and values in a hash table can also be Hashtable objects. The +following statement adds key/value pair to the hash table in the \$p variable +in which the key is a string, Hash2, and the value is a hash table with three +key/value pairs. -``` +```powershell C:\PS> $p = $p + @{"Hash2"= @{a=1; b=2; c=3}} ``` - You can display and access the new values by using the same methods. +```powershell +C:\PS> $p -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running -Hash2 {a, b, c} - -C:\PS> $p.Hash2 - -Name Value ----- ----- -a 1 -b 2 -c 3 - -C:\PS> $p.Hash2.b -2 -``` +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running +Hash2 {a, b, c} +C:\PS> $p.Hash2 +Name Value +---- ----- +a 1 +b 2 +c 3 + +C:\PS> $p.Hash2.b +2 +``` ### Sorting Keys and Values -The items in a hash table are intrinsically unordered. The key\/value pairs might appear in a different order each time that you display them. -Although you cannot sort a hash table, you can use the GetEnumerator method of hash tables to enumerate the keys and values, and then use the Sort-Object cmdlet to sort the enumerated values for display. +The items in a hash table are intrinsically unordered. The key/value pairs +might appear in a different order each time that you display them. -For example, the following commands enumerate the keys and values in the hash table in the $p variable and then sort the keys in alphabetical order. +Although you cannot sort a hash table, you can use the GetEnumerator method of +hash tables to enumerate the keys and values, and then use the Sort-Object +cmdlet to sort the enumerated values for display. +For example, the following commands enumerate the keys and values in the hash +table in the \$p variable and then sort the keys in alphabetical order. -``` -C:\PS> $p.GetEnumerator() | Sort-Object -Property key - -Name Value ----- ----- -Notepad System.Diagnostics.Process (notepad) -PowerShell System.Diagnostics.Process (PowerShell) +```powershell +C:\PS> $p.GetEnumerator() | Sort-Object -Property key + +Name Value +---- ----- +Notepad System.Diagnostics.Process (notepad) +PowerShell System.Diagnostics.Process (PowerShell) System.ServiceProcess.Servi... Running ``` +The following command uses the same procedure to sort the hash values in +descending order. -The following command uses the same procedure to sort the hash values in descending order. +```powershell +C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -``` -C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) System.ServiceProcess.Servi... Running ``` - - ### Creating Objects from Hash Tables -Beginning in Windows PowerShell 3.0, you can create an object from a hash table of properties and property values. -The syntax is as follows: +Beginning in PowerShell 3.0, you can create an object from a hash table of +properties and property values. +The syntax is as follows: -``` -[]@{=;=} +```powershell +[]@{ + = + = +} ``` +This method works only for classes that have a null constructor, that is, a +constructor that has no parameters. The object properties must be public and +settable. -This method works only for classes that have a null constructor, that is, a constructor that has no parameters. The object properties must be public and settable. - -For more information, see [about_Object_Creation](about_Object_Creation.md). - +For more information, see [about_Object_Creation(about_Object_Creation.md)]. ### ConvertFrom-StringData -The ConvertFrom-StringData cmdlet converts a string or a here-string of key\/value pairs into a hash table. You can use the ConvertFrom-StringData cmdlet safely in the Data section of a script, and you can use it with the Import-LocalizedData cmdlet to display user messages in the user-interface (UI) culture of the current user. -Here-strings are especially useful when the values in the hash table include quotation marks. (For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md).) +The `ConvertFrom-StringData` cmdlet converts a string or a here-string of +key/value pairs into a hash table. You can use the `ConvertFrom-StringData` +cmdlet safely in the Data section of a script, and you can use it with the +`Import-LocalizedData` cmdlet to display user messages in the user-interface +(UI) culture of the current user. -The following example shows how to create a here-string of the user messages in the previous example and how to use ConvertFrom-StringData to convert them from a string into a hash table. +Here-strings are especially useful when the values in the hash table include +quotation marks. For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). -The following command creates a here-string of the key\/value pairs and then saves it in the $string variable. +The following example shows how to create a here-string of the user messages +in the previous example and how to use `ConvertFrom-StringData` to convert them +from a string into a hash table. +The following command creates a here-string of the key/value pairs and then +saves it in the \$string variable. -``` -C:\PS> $string = @" -Msg1 = Type "Windows". -Msg2 = She said, "Hello, World." -Msg3 = Enter an alias (or "nickname"). +```powershell +C:\PS> $string = @" +Msg1 = Type "Windows". +Msg2 = She said, "Hello, World." +Msg3 = Enter an alias (or "nickname"). "@ ``` +This command uses the ConvertFrom-StringData cmdlet to convert the here-string +into a hash table. -This command uses the ConvertFrom-StringData cmdlet to convert the here-string into a hash table. - +```powershell +C:\PS> ConvertFrom-StringData $string -``` -C:\PS> ConvertFrom-StringData $string - -Name Value ----- ----- -Msg3 Enter an alias (or "nickname"). -Msg2 She said, "Hello, World." +Name Value +---- ----- +Msg3 Enter an alias (or "nickname"). +Msg2 She said, "Hello, World." Msg1 Type "Windows". ``` - For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). - ## SEE ALSO [about_Arrays](about_Arrays.md) @@ -486,5 +499,5 @@ For more information about here-strings, see [about_Quoting_Rules](about_Quoting [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) -["System.Collections.Hashtable"](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN +[System.Collections.Hashtable](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md index bacd41016bfc..43c54fe84cb6 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md @@ -73,7 +73,8 @@ if ($a -gt 2) { Write-Host "The value $a is greater than 2." } else { - Write-Host "The value $a is less than or equal to 2, is not created or is not initialized." + Write-Host ("The value $a is less than or equal to 2," + + " is not created or is not initialized.") } ``` @@ -89,7 +90,8 @@ elseif ($a -eq 2) { Write-Host "The value $a is equal to 2." } else { - Write-Host "The value $a is less than 2 or was not created or initialized." + Write-Host ("The value $a is less than 2 or" + + " was not created or initialized.") } ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 31c9c354fcb4..61ddaa58384e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Job_Details --- # About Job Details -## about_Job_Details - - # SHORT DESCRIPTION @@ -20,7 +17,8 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in Windows PowerShell. -This topic is a supplement to the about_Jobs and about_Remote_Jobs topics. +This topic is a supplement to the [about_Jobs](about_Jobs.md) and +[about_Remote_Jobs](about_Remote_Jobs.md) topics. # ABOUT BACKGROUND JOBS @@ -94,65 +92,71 @@ To get the parent and child jobs of a job, use the IncludeChildJobs parameter of the Get-Job cmdlet. The IncludeChildJob parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -IncludeChildJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the parent job and only the child jobs with a particular State value, use the ChildJobState parameter of the Get-Job cmdlet. The ChildJobState parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -ChildJobState Failed -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the child jobs of a job on all versions of Windows PowerShell, use the ChildJob property of the parent job. +```powershell C:\PS> (Get-Job Job1).ChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` You can also use a Get-Job command on the child job, as shown in the following command: +```powershell C:\PS> Get-Job Job3 -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 Failed False localhost Get-Process +``` The configuration of the child job depends on the command that you use to start the job. --- When you use Start-Job to start a job on a local computer, the job -consists of an executive parent job and a child job that runs the -command. +- When you use Start-Job to start a job on a local computer, the job consists + of an executive parent job and a child job that runs the command. --- When you use the AsJob parameter of Invoke-Command to start a job on -one or more computers, the job consists of an executive parent job -and a child job for each job run on each computer. +- When you use the AsJob parameter of Invoke-Command to start a job on one or + more computers, the job consists of an executive parent job and a child job + for each job run on each computer. --- When you use Invoke-Command to run a Start-Job command on one or more -remote computers, the result is the same as a local command run on -each remote computer. The command returns a job object for each -computer. The job object consists of an executive parent job and -one child job that runs the command. +- When you use Invoke-Command to run a Start-Job command on one or more remote + computers, the result is the same as a local command run on each remote + computer. The command returns a job object for each computer. The job object + consists of an executive parent job and one child job that runs the command. -The parent job represents all of the child jobs. When you manage a parent -job, you also manage the associated child jobs. For example, if you stop a -parent job, all child jobs are stopped. If you get the results of a parent -job, you get the results of all child jobs. +The parent job represents all of the child jobs. When you manage a parent job, +you also manage the associated child jobs. For example, if you stop a parent +job, all child jobs are stopped. If you get the results of a parent job, you +get the results of all child jobs. However, you can also manage child jobs individually. This is most useful when you want to investigate a problem with a job or get the results of @@ -161,49 +165,60 @@ Invoke-Command. (The backtick character [`] is the continuation character.) The following command uses the AsJob parameter of Invoke-Command to start background jobs on the local computer and two remote computers. The command -saves the job in the $j variable. +saves the job in the \$j variable. +```powershell PS C:> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` -Command {Get-Date} -AsJob +``` -When you display the Name and ChildJob properties of the job in $j, it +When you display the Name and ChildJob properties of the job in \$j, it shows that the command returned a job object with three child jobs, one for each computer. +```powershell PS C:> $j | Format-List Name, ChildJobs Name : Job3 ChildJobs : {Job4, Job5, Job6} +``` When you display the parent job, it shows that the job failed. +```powershell C:\PS> $j -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- -3 Job3 RemotingJob Failed False localhost,Server... +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- +3 Job3 RemotingJob Failed False localhost,Server... +``` But when you run a Get-Job command that gets the child jobs, the output shows that only one child job failed. +```powershell PS C:> Get-Job -IncludeChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 RemotingJob Failed False localhost,Server... -4 Job4 Completed True localhost Get-Date -5 Job5 Failed False Server01 Get-Date -6 Job6 Completed True Server02 Get-Date +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 RemotingJob Failed False localhost,Server... +4 Job4 Completed True localhost Get-Date +5 Job5 Failed False Server01 Get-Date +6 Job6 Completed True Server02 Get-Date +``` To get the results of all child jobs, use the Receive-Job cmdlet to get the results of the parent job. But you can also get the results of a particular child job, as shown in the following command. -C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, DateTime -Auto +```powershell +C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, +>> DateTime -Auto ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM +``` The child jobs feature of Windows PowerShell background jobs gives you more control over the jobs that you run. @@ -239,86 +254,100 @@ Get-Job returns indicates the job type. The following table lists the job types that come with Windows PowerShell. -Job Type Description --------- ----------- -BackgroundJob Started by using the Start-Job cmdlet. -RemoteJob Started by using the AsJob parameter of the -Invoke-Command cmdlet. -PSWorkflowJob Started by using the AsJob parameter of a -workflow. -PSScheduledJob An instance of a scheduled job started by -a job trigger. -CIMJob Started by using the AsJob parameter of -a cmdlet from a CDXML module. -WMIJob Started by using the AsJob parameter of -a cmdlet from a WMI module. -PSEventJob Created by running Register-ObjectEvent -and specifying an action with the Action -parameter. - -NOTE: Before using the Get-Job cmdlet to get jobs of a particular -type, verify that the module that adds the job type is imported -into the current session. Otherwise, Get-Job does not get jobs of -that type. +|Job Type |Description | +|--------------|----------------------------------------------------------| +|BackgroundJob |Started by using the Start-Job cmdlet. | +|RemoteJob |Started by using the AsJob parameter of the Invoke-Command| +| |cmdlet. | +|PSWorkflowJob |Started by using the AsJob parameter of a workflow. | +|PSScheduledJob|An instance of a scheduled job started by a job trigger. | +|CIMJob |Started by using the AsJob parameter of a cmdlet from a | +| |CDXML module. | +|WMIJob |Started by using the AsJob parameter of a cmdlet from a | +| |WMI module. | +|PSEventJob |Created by running Register-ObjectEvent and specifying an | +| |action with the Action parameter. | + +NOTE: Before using the Get-Job cmdlet to get jobs of a particular type, verify +that the module that adds the job type is imported into the current session. +Otherwise, Get-Job does not get jobs of that type. # EXAMPLE -The following commands create a local background job, a -remote background job, a workflow job, and a scheduled job. -Then, it uses the Get-Job cmdlet to get the jobs. Get-Job -does not get the scheduled job, but it gets any started +The following commands create a local background job, a remote background job, +a workflow job, and a scheduled job. Then, it uses the Get-Job cmdlet to get +the jobs. `Get-Job` does not get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. + +```powershell PS C:> Start-Job -Name LocalData {Get-Process} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Running True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Running True localhost Get-Process +``` Start a background job that runs on a remote computer. -PS C:> Invoke-Command -ComputerName Server01 {Get-Process} -AsJob -JobName RemoteData -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 RemoteData RemoteJob Running True Server01 Get-Process +```powershell +PS C:> Invoke-Command -ComputerName Server01 {Get-Process} ` +-AsJob -JobName RemoteData + +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 RemoteData RemoteJob Running True Server01 Get-Process +``` Create a scheduled job -PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock {Get-Process} ` --Trigger (New-JobTrigger -Once -At "3 PM") +```powershell +PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` + {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` Create a workflow. +```powershell PS C:> workflow Test-Workflow {Get-Process} +``` Run the workflow as a job. +```powershell + PS C:> Test-Workflow -AsJob -JobName TestWFJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +``` -Get the jobs. The Get-Job command does not get scheduled jobs, but it gets +Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets instances of the scheduled job that are started. +```powershell PS C:> Get-Job -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Completed True localhost Get-Process +4 RemoteData RemoteJob Completed True Server01 Get-Process +6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob +8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +``` To get scheduled jobs, use the Get-ScheduledJob cmdlet. + +```powershell PS C:> Get-ScheduledJob Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` # SEE ALSO @@ -328,31 +357,30 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../PSScheduledJob/About/about_Scheduled_Jobs.md) - -Invoke-Command +[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -Suspend-Job +[Remove-Job](../Remove-Job.md) -Resume-Job +[Suspend-Job](../Remove-Job.md) -New-PSSession +[Resume-Job](../Resume-Job) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Register-ScheduledJob +[Exit-PSSession](../Exit-PSSession.md) -Get-ScheduleJob +[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) +[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md index 170a44e2c7e3..e2cf58d05dc1 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,13 +7,10 @@ title: about_Functions_CmdletBindingAttribute --- # About Functions CmdletBindingAttribute -## about_Functions_CmdletBindingAttribute - # SHORT DESCRIPTION -Describes the attribute that makes a function work like a -compiled cmdlet. +Describes the attribute that makes a function work like a compiled cmdlet. # LONG DESCRIPTION @@ -124,13 +121,15 @@ to an advanced function. function Get-Numbers { [CmdletBinding(SupportsPaging = $true)] param() - + $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100) - $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100) - + $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + + $FirstNumber - 1, 100) + if ($PSCmdlet.PagingParameters.IncludeTotalCount) { $TotalCountAccuracy = 1.0 - $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy) + $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, + $TotalCountAccuracy) Write-Output $TotalCount } $FirstNumber .. $LastNumber | Write-Output @@ -173,8 +172,7 @@ must be included when the parameter is used in a function. The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. You can use the Position argument to specify a position value for a parameter. For more information about the Position -argument, see about_Functions_Advanced_Parameters -(http://go.microsoft.com/fwlink/?LinkID=135173). +argument, see [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). # NOTES diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index 15463e8deb2d..ff4eed688151 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,8 +7,6 @@ title: about_Group_Policy_Settings --- # About Group Policy Settings -## about_Group_Policy_Settings - # SHORT DESCRIPTION @@ -16,28 +14,32 @@ Describes the Group Policy settings for Windows PowerShell # LONG DESCRIPTION - Windows PowerShell includes Group Policy settings to help you define consistent option values for servers in an enterprise environment. The Windows PowerShell Group Policy settings are in the following Group Policy paths: -Computer Configuration\Administrative Templates\Windows Components\Windows PowerShell -User Configuration\Administrative Templates\Windows Components\Windows PowerShell + Computer Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell + + User Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell Group policy settings in the User Configuration path take precedence over Group Policy settings in the Computer Configuration path. The policies are as follows: -Turn on Script Execution: Sets the Windows PowerShell execution -policy. -Turn on Module Logging: Sets the LogPipelineExecutionDetails -property of modules. -Set the default source path for Update-Help: -Sets the source for UpdatableHelp to -a directory, not the Internet. +- Turn on Script Execution: Sets the Windows PowerShell execution policy. +- Turn on Module Logging: Sets the LogPipelineExecutionDetails property of + modules. +- Set the default source path for Update-Help: Sets the source for + UpdatableHelp to a directory, not the Internet. To download spreadsheets that list all of the Group Policy settings for each version of Windows, see "Group Policy Settings Reference for Windows @@ -53,28 +55,27 @@ run. If you enable the policy setting, you can select from among the following policy settings. --- "Allow only signed scripts" allows scripts to execute only if they -are signed by a trusted publisher. This policy setting is equivalent -to the AllSigned execution policy. +- "Allow only signed scripts" allows scripts to execute only if they are + signed by a trusted publisher. This policy setting is equivalent to the + AllSigned execution policy. --- "Allow local scripts and remote signed scripts" allows all local -scripts to run. Scripts that originate from the Internet must be -signed by a trusted publisher. This policy setting is equivalent -to the RemoteSigned execution policy. +- "Allow local scripts and remote signed scripts" allows all local scripts to + run. Scripts that originate from the Internet must be signed by a trusted + publisher. This policy setting is equivalent to the RemoteSigned execution + policy. --- "Allow all scripts" allows all scripts to run. This policy -setting is equivalent to the Unrestricted execution policy. +- "Allow all scripts" allows all scripts to run. This policy setting is + equivalent to the Unrestricted execution policy. -If you disable this policy setting, no scripts are allowed to run. -This policy setting is equivalent to the Restricted execution policy. +If you disable this policy setting, no scripts are allowed to run. This policy +setting is equivalent to the Restricted execution policy. -If you disable or do not configure this policy setting, the execution -policy that is set for the computer or user by the Set-ExecutionPolicy -cmdlet determines whether scripts are permitted to run. The default -value is Restricted. +If you disable or do not configure this policy setting, the execution policy +that is set for the computer or user by the Set-ExecutionPolicy cmdlet +determines whether scripts are permitted to run. The default value is +Restricted. -For more information, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](about_Execution_Policies.md). # TURN ON MODULE LOGGING @@ -99,56 +100,54 @@ To turn on module logging for a module, use the following command format. The module must be imported into the session and the setting is effective only in the current session. +```powershell PS C:> Import-Module PS C:> (Get-Module ).LogPipelineExecutionDetails = $true +``` To turn on module logging for all sessions on a particular computer, add the previous commands to the all-users Windows PowerShell profile ($Profile.AllUsers.AllHosts). -For more information about module logging, see about_Modules -(http://go.microsoft.com/fwlink/?LinkID=144311). +For more information about module logging, see [about_Modules](about_Modules.md). # SET THE DEFAULT SOURCE PATH FOR UPDATE-HELP The "Set the Default Source Path for Update-Help" policy setting sets a -default value for the SourcePath parameter of the Update-Help cmdlet. -This setting prevents users from using the Update-Help cmdlet to download -help files from the Internet. +default value for the SourcePath parameter of the Update-Help cmdlet. This +setting prevents users from using the Update-Help cmdlet to download help +files from the Internet. -NOTE: The "Set the default source path for Update-Help" Group -Policy setting appears under Computer Configuration and -User Configuration. However, only the Group Policy setting -under Computer Configuration is effective. The Group Policy -setting under User Configuration is ignored. +NOTE: The "Set the default source path for Update-Help" Group Policy setting +appears under Computer Configuration and User Configuration. However, only the +Group Policy setting under Computer Configuration is effective. The Group +Policy setting under User Configuration is ignored. The Update-Help cmdlet downloads and installs the newest help files for Windows PowerShell modules and installs them on the computer. By default, -Update-Help downloads new help files from an Internet location specified -by the module. +Update-Help downloads new help files from an Internet location specified by +the module. -However, you can use the Save-Help cmdlet to download the newest help -files to a file system location, such as a network share, and then use -the Update-Help cmdlet to get the help files from the file system -location and install them on the computer. The SourcePath parameter of -the Update-Help cmdlet specifies the file system location. +However, you can use the Save-Help cmdlet to download the newest help files to +a file system location, such as a network share, and then use the Update-Help +cmdlet to get the help files from the file system location and install them on +the computer. The SourcePath parameter of the Update-Help cmdlet specifies the +file system location. -By providing a default value for the SourcePath parameter, this Group -Policy setting implicitly adds the SourcePath parameter to all Update-Help -commands. Users can override the particular file system location specified -as the default value by entering a different file system location. But they -cannot remove the SourcePath parameter from the Update-Help command. +By providing a default value for the SourcePath parameter, this Group Policy +setting implicitly adds the SourcePath parameter to all Update-Help commands. +Users can override the particular file system location specified as the +default value by entering a different file system location. But they cannot +remove the SourcePath parameter from the Update-Help command. If you enable this policy setting, you can specify a default value for the SourcePath parameter. Enter a file system location. -If this policy setting is disabled or not configured, there is no -default value for the SourcePath parameter of the Update-Help cmdlet. -Users can download help from the Internet or from any file system -location. +If this policy setting is disabled or not configured, there is no default +value for the SourcePath parameter of the `Update-Help` cmdlet. Users can +download help from the Internet or from any file system location. -For more information, see about_Updatable_Help -(http://go.microsoft.com/fwlink/?LinkID=235801). +For more information, see [about_Updatable_Help](about_Updatable_Help.md). # KEYWORDS @@ -163,13 +162,12 @@ about_GroupPolicy [about_Updatable_Help](about_Updatable_Help.md) -Get-ExecutionPolicy - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Get-Module +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -Update-Help +[Get-Module](../Get-Module.md) -Save-Help +[Update-Help](../Update-Help.md) +[Save-Help](../../Save-Help.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 34916bc2ec99..174cf4dd2d6a 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,471 +7,484 @@ title: about_Hash_Tables --- # About Hash Tables -## about_Hash_Tables - ## SHORT DESCRIPTION -Describes how to create, use, and sort hash tables in Windows PowerShell. +Describes how to create, use, and sort hash tables in PowerShell. ## LONG DESCRIPTION -A hash table, also known as a dictionary or associative array, is a compact data structure that stores one or more key\/value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In Windows PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) object. You can use the properties and methods of Hashtable objects in Windows PowerShell. +A hash table, also known as a dictionary or associative array, is a compact +data structure that stores one or more key/value pairs. For example, a hash +table might contain a series of IP addresses and computer names, where the IP +addresses are the keys and the computer names are the values, or vice versa. -Beginning in Windows PowerShell 3.0, you can use the [ordered] attribute to create an ordered dictionary (System.Collections.Specialized.OrderedDictionary) in Windows PowerShell. +In PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) +object. You can use the properties and methods of Hashtable objects in +PowerShell. -Ordered dictionaries differ from hash tables in that the keys always appear in the order in which you list them. The order of keys in a hash table is not determined. +Beginning in PowerShell 3.0, you can use the [ordered] attribute to create an +ordered dictionary (System.Collections.Specialized.OrderedDictionary) in +PowerShell. -The keys and value in hash tables are also .NET objects. They are most often strings or integers, but they can have any object type. You can also create nested hash tables, in which the value of a key is another hash table. +Ordered dictionaries differ from hash tables in that the keys always appear in +the order in which you list them. The order of keys in a hash table is not +determined. -Hash tables are frequently used because they are very efficient for finding and retrieving data. You can use hash tables to store lists and to create calculated properties in Windows PowerShell. And, Windows PowerShell has a cmdlet, ConvertFrom-StringData, that converts strings to a hash table. +The keys and value in hash tables are also .NET objects. They are most often +strings or integers, but they can have any object type. You can also create +nested hash tables, in which the value of a key is another hash table. +Hash tables are frequently used because they are very efficient for finding +and retrieving data. You can use hash tables to store lists and to create +calculated properties in PowerShell. And, PowerShell has a cmdlet, +ConvertFrom-StringData, that converts strings to a hash table. ### Syntax -The syntax of a hash table is as follows: +The syntax of a hash table is as follows: -``` +```powershell @{ = ; [ = ] ...} ``` - The syntax of an ordered dictionary is as follows: - -``` +```powershell [ordered]@{ = ; [ = ] ...} ``` - -The [ordered] attribute was introduced in Windows PowerShell 3.0. - +The [ordered] attribute was introduced in PowerShell 3.0. ### Creating Hash Tables + To create a hash table, follow these guidelines: - Begin the hash table with an at sign (@). - - Enclose the hash table in braces ({}). - -- Enter one or more key\/value pairs for the content of the hash table. - -- Use an equal sign (\=) to separate each key from its value. - -- Use a semicolon (;) or a line break to separate the key\/value pairs. - -- Key that contains spaces must be enclosed in quotation marks. Values must be valid Windows PowerShell expressions. Strings must appear in quotation marks, even if they do not include spaces. - +- Enter one or more key/value pairs for the content of the hash table. +- Use an equal sign (=) to separate each key from its value. +- Use a semicolon (;) or a line break to separate the key/value pairs. +- Key that contains spaces must be enclosed in quotation marks. Values must be + valid PowerShell expressions. Strings must appear in quotation marks, even if + they do not include spaces. - To manage the hash table, save it in a variable. - -- When assigning an ordered hash table to a variable, place the [ordered] attribute before the "@" symbol. If you place it before the variable name, the command fails. +- When assigning an ordered hash table to a variable, place the [ordered] + attribute before the "@" symbol. If you place it before the variable name, the + command fails. To create an empty hash table in the value of $hash, type: - -``` +```powershell $hash = @{} ``` +You can also add keys and values to a hash table when you create it. For +example, the following statement creates a hash table with three keys. -You can also add keys and values to a hash table when you create it. For example, the following statement creates a hash table with three keys. - - -``` +```powershell $hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} ``` - - ### Creating Ordered Dictionaries -You can create an ordered dictionary by adding an object of the OrderedDictionary type, but the easiest way to create an ordered dictionary is use the [Ordered] attribute. -The [ordered] attribute is introduced in Windows PowerShell 3.0. +You can create an ordered dictionary by adding an object of the +OrderedDictionary type, but the easiest way to create an ordered dictionary is +use the [Ordered] attribute. -Place the attribute immediately before the "@" symbol. +The [ordered] attribute is introduced in PowerShell 3.0. +Place the attribute immediately before the "@" symbol. -``` +```powershell $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` +You can use ordered dictionaries in the same way that you use hash tables. +Either type can be used as the value of parameters that take a hash table or +dictionary (iDictionary). -You can use ordered dictionaries in the same way that you use hash tables. Either type can be used as the value of parameters that take a hash table or dictionary (iDictionary). +You cannot use the [ordered] attribute to convert or cast a hash table. If you +place the ordered attribute before the variable name, the command fails with +the following error message. -You cannot use the [ordered] attribute to convert or cast a hash table. If you place the ordered attribute before the variable name, the command fails with the following error message. - - -``` -PS C:\> [ordered]$hash = @{} -At line:1 char:1 -+ [ordered]$hash = @{} -+ [!INCLUDE[]()] -The ordered attribute can be specified only on a hash literal node. -+ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException +```powershell +PS C:\> [ordered]$hash = @{} +At line:1 char:1 ++ [ordered]$hash = @{} ++ [!INCLUDE[]()] +The ordered attribute can be specified only on a hash literal node. ++ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordExc +eption + FullyQualifiedErrorId : OrderedAttributeOnlyOnHashLiteralNode ``` - To correct the expression, move the [ordered] attribute. - -``` +```powershell PS C:\> $hash = [ordered]@{} ``` - -You can cast an ordered dictionary to a hash table, but you cannot recover the ordered attribute, even if you clear the variable and enter new values. To re-establish the order, you must remove and recreate the variable. - +You can cast an ordered dictionary to a hash table, but you cannot recover the +ordered attribute, even if you clear the variable and enter new values. To +re-establish the order, you must remove and recreate the variable. ``` -PS C:\> [hashtable]$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} -PS C:\ps-test> $hash - -Name Value ----- ----- -Color Blue -Shape Square +PS C:\> [hashtable]$hash = [ordered]@{ +>> Number = 1; Shape = "Square"; Color = "Blue"} +PS C:\> $hash + +Name Value +---- ----- +Color Blue +Shape Square Number 1 ``` - - ### Displaying Hash Tables -To display a hash table that is saved in a variable, type the variable name. By default, a hash tables is displayed as a table with one column for keys and one for values. +To display a hash table that is saved in a variable, type the variable name. +By default, a hash tables is displayed as a table with one column for keys and +one for values. -``` -C:\PS> $hash - -Name Value ----- ----- -Shape Square -Color Blue +```powershell +C:\PS> $hash + +Name Value +---- ----- +Shape Square +Color Blue Number 1 ``` +Hash tables have Keys and Values properties. Use dot notation to display all +of the keys or all of the values. -Hash tables have Keys and Values properties. Use dot notation to display all of the keys or all of the values. +```powershell +C:\PS> $hash.keys +Number +Shape +Color - -``` -C:\PS> $hash.keys -Number -Shape -Color - -C:\PS> $hash.values -1 -Square +C:\PS> $hash.values +1 +Square Blue ``` +Each key name is also a property of the hash table, and its value is the value +of the key-name property. Use the following format to display the property +values. -Each key name is also a property of the hash table, and its value is the value of the key-name property. Use the following format to display the property values. - - -``` -$hashtable. +```powershell +$hashtable. ``` - For example: +```powershell +C:\PS> $hash.Number +1 -``` -C:\PS> $hash.Number -1 - -C:\PS> $hash.Color +C:\PS> $hash.Color Blue ``` +If the key name collides with one of the property names of the HashTable type, +you can use `PSBase` to access those properties. For example, if the key name +is `keys` and you want to return the collection of Keys, use this syntax: -Hash tables have a Count property that indicates the number of key-value pairs in the hash table. +```powershell +$hashtable.PSBase.Keys +``` +Hash tables have a Count property that indicates the number of key-value pairs +in the hash table. -``` -C:\PS> $hash.count +```powershell +C:\PS> $hash.count 3 ``` - -Hash table tables are not arrays, so you cannot use an integer as an index into the hash table, but you can use a key name to index into the hash table. If the key is a string value, enclose the key name in quotation marks. +Hash table tables are not arrays, so you cannot use an integer as an index +into the hash table, but you can use a key name to index into the hash table. +If the key is a string value, enclose the key name in quotation marks. For example: - -``` -C:\PS> $hash["Number"] +```powershell +C:\PS> $hash["Number"] 1 ``` - - ### Adding and Removing Keys and Values -To add keys and values to a hash table, use the following command format. +To add keys and values to a hash table, use the following command format. -``` +```powershell $hash[""] = "" ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash["Time"] = "Now" ``` +You can also add keys and values to a hash table by using the Add method of +the System.Collections.Hashtable object. The Add method has the following +syntax: -You can also add keys and values to a hash table by using the Add method of the System.Collections.Hashtable object. The Add method has the following syntax: - - -``` +```powershell Add(Key, Value) ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash = $hash.Add("Time", "Now") ``` +And, you can add keys and values to a hash table by using the addition +operator (+) to add a hash table to an existing hash table. For example, the +following statement adds a "Time" key with a value of "Now" to the hash table +in the $hash variable. -And, you can add keys and values to a hash table by using the addition operator (\+) to add a hash table to an existing hash table. For example, the following statement adds a "Time" key with a value of "Now" to the hash table in the $hash variable. - - -``` +```powershell $hash = $hash + @{Time="Now"} ``` - You can also add values that are stored in variables. +```powershell +$t = "Today" +$now = (Get-Date) -``` -$t = "Today" -$now = (Get-Date) - $hash.Add($t, $now) ``` - -You cannot use a subtraction operator to remove a key\/value pair from a hash table, but you can use the Remove method of the Hashtable object. The Remove method takes the key as its value. +You cannot use a subtraction operator to remove a key/value pair from a hash +table, but you can use the Remove method of the Hashtable object. The Remove +method takes the key as its value. The Remove method has the following syntax: - ``` Remove(Key) ``` +For example, to remove the Time=Now key/value pair from the hash table in the +value of the $hash variable, type: -For example, to remove the Time\=Now key\/value pair from the hash table in the value of the $hash variable, type: - - -``` -$hash.$Remove("Time") +```powershell +$hash.Remove("Time") ``` - -You can use all of the properties and methods of Hashtable objects in Windows PowerShell, including Contains, Clear, Clone, and CopyTo. For more information about Hashtable objects, see ["System.Collections.Hashtable"](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN. - +You can use all of the properties and methods of Hashtable objects in +PowerShell, including Contains, Clear, Clone, and CopyTo. For more information +about Hashtable objects, see "System.Collections.Hashtable" on MSDN. ### Object Types in HashTables -The keys and values in a hash table can have any .NET object type, and a single hash table can have keys and values of multiple types. -The following statement creates a hash table of process name strings and process object values and saves it in the $p variable. +The keys and values in a hash table can have any .NET object type, and a +single hash table can have keys and values of multiple types. +The following statement creates a hash table of process name strings and +process object values and saves it in the \$p variable. -``` -$p = @{"PowerShell" = (get-process PowerShell); +```powershell +$p = @{"PowerShell" = (get-process PowerShell); "Notepad" = (get-process notepad)} ``` +You can display the hash table in \$p and use the key-name properties to +display the values. -You can display the hash table in $p and use the key-name properties to display the values. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) - -C:\PS> $p.PowerShell - -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName -------- ------ ----- ----- ----- ------ -- ----------- - 441 24 54196 54012 571 5.10 1788 PowerShell - -C:\PS> $p.keys | foreach {$p.$_.handles} -441 -251 -``` +C:\PS> $p.PowerShell +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 441 24 54196 54012 571 5.10 1788 PowerShell -The keys in a hash table can also be any .NET type. The following statement adds a key\/value pair to the hash table in the $p variable. The key is a Service object that represents the WinRM service, and the value is the current status of the service. +C:\PS> $p.keys | foreach {$p.$_.handles} +441 +251 +``` +The keys in a hash table can also be any .NET type. The following statement +adds a key/value pair to the hash table in the \$p variable. The key is a +Service object that represents the WinRM service, and the value is the current +status of the service. -``` +```powershell C:\PS> $p = $p + @{(Get-Service WinRM) = ((Get-Service WinRM).Status)} ``` +You can display and access the new key/value pair by using the same methods +that you use for other pairs in the hash table. -You can display and access the new key\/value pair by using the same methods that you use for other pairs in the hash table. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running - -C:\PS> $p.keys -PowerShell -Notepad - -Status Name DisplayName ------- ---- ----------- -Running winrm Windows Remote Management (WS-Manag... - -C:\PS> $p.keys | foreach {$_.name} -winrm -``` +C:\PS> $p.keys +PowerShell +Notepad +Status Name DisplayName +------ ---- ----------- +Running winrm Windows Remote Management (WS-Manag... -The keys and values in a hash table can also be Hashtable objects. The following statement adds key\/value pair to the hash table in the $p variable in which the key is a string, Hash2, and the value is a hash table with three key\/value pairs. +C:\PS> $p.keys | foreach {$_.name} +winrm +``` +The keys and values in a hash table can also be Hashtable objects. The +following statement adds key/value pair to the hash table in the \$p variable +in which the key is a string, Hash2, and the value is a hash table with three +key/value pairs. -``` +```powershell C:\PS> $p = $p + @{"Hash2"= @{a=1; b=2; c=3}} ``` - You can display and access the new values by using the same methods. +```powershell +C:\PS> $p -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running -Hash2 {a, b, c} - -C:\PS> $p.Hash2 - -Name Value ----- ----- -a 1 -b 2 -c 3 - -C:\PS> $p.Hash2.b -2 -``` +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running +Hash2 {a, b, c} +C:\PS> $p.Hash2 +Name Value +---- ----- +a 1 +b 2 +c 3 + +C:\PS> $p.Hash2.b +2 +``` ### Sorting Keys and Values -The items in a hash table are intrinsically unordered. The key\/value pairs might appear in a different order each time that you display them. -Although you cannot sort a hash table, you can use the GetEnumerator method of hash tables to enumerate the keys and values, and then use the Sort-Object cmdlet to sort the enumerated values for display. +The items in a hash table are intrinsically unordered. The key/value pairs +might appear in a different order each time that you display them. -For example, the following commands enumerate the keys and values in the hash table in the $p variable and then sort the keys in alphabetical order. +Although you cannot sort a hash table, you can use the GetEnumerator method of +hash tables to enumerate the keys and values, and then use the Sort-Object +cmdlet to sort the enumerated values for display. +For example, the following commands enumerate the keys and values in the hash +table in the \$p variable and then sort the keys in alphabetical order. -``` -C:\PS> $p.GetEnumerator() | Sort-Object -Property key - -Name Value ----- ----- -Notepad System.Diagnostics.Process (notepad) -PowerShell System.Diagnostics.Process (PowerShell) +```powershell +C:\PS> $p.GetEnumerator() | Sort-Object -Property key + +Name Value +---- ----- +Notepad System.Diagnostics.Process (notepad) +PowerShell System.Diagnostics.Process (PowerShell) System.ServiceProcess.Servi... Running ``` +The following command uses the same procedure to sort the hash values in +descending order. -The following command uses the same procedure to sort the hash values in descending order. +```powershell +C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -``` -C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) System.ServiceProcess.Servi... Running ``` - - ### Creating Objects from Hash Tables -Beginning in Windows PowerShell 3.0, you can create an object from a hash table of properties and property values. -The syntax is as follows: +Beginning in PowerShell 3.0, you can create an object from a hash table of +properties and property values. +The syntax is as follows: -``` -[]@{=;=} +```powershell +[]@{ + = + = +} ``` +This method works only for classes that have a null constructor, that is, a +constructor that has no parameters. The object properties must be public and +settable. -This method works only for classes that have a null constructor, that is, a constructor that has no parameters. The object properties must be public and settable. - -For more information, see [about_Object_Creation](about_Object_Creation.md). - +For more information, see [about_Object_Creation(about_Object_Creation.md)]. ### ConvertFrom-StringData -The ConvertFrom-StringData cmdlet converts a string or a here-string of key\/value pairs into a hash table. You can use the ConvertFrom-StringData cmdlet safely in the Data section of a script, and you can use it with the Import-LocalizedData cmdlet to display user messages in the user-interface (UI) culture of the current user. -Here-strings are especially useful when the values in the hash table include quotation marks. (For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md).) +The `ConvertFrom-StringData` cmdlet converts a string or a here-string of +key/value pairs into a hash table. You can use the `ConvertFrom-StringData` +cmdlet safely in the Data section of a script, and you can use it with the +`Import-LocalizedData` cmdlet to display user messages in the user-interface +(UI) culture of the current user. -The following example shows how to create a here-string of the user messages in the previous example and how to use ConvertFrom-StringData to convert them from a string into a hash table. +Here-strings are especially useful when the values in the hash table include +quotation marks. For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). -The following command creates a here-string of the key\/value pairs and then saves it in the $string variable. +The following example shows how to create a here-string of the user messages +in the previous example and how to use `ConvertFrom-StringData` to convert them +from a string into a hash table. +The following command creates a here-string of the key/value pairs and then +saves it in the \$string variable. -``` -C:\PS> $string = @" -Msg1 = Type "Windows". -Msg2 = She said, "Hello, World." -Msg3 = Enter an alias (or "nickname"). +```powershell +C:\PS> $string = @" +Msg1 = Type "Windows". +Msg2 = She said, "Hello, World." +Msg3 = Enter an alias (or "nickname"). "@ ``` +This command uses the ConvertFrom-StringData cmdlet to convert the here-string +into a hash table. -This command uses the ConvertFrom-StringData cmdlet to convert the here-string into a hash table. - +```powershell +C:\PS> ConvertFrom-StringData $string -``` -C:\PS> ConvertFrom-StringData $string - -Name Value ----- ----- -Msg3 Enter an alias (or "nickname"). -Msg2 She said, "Hello, World." +Name Value +---- ----- +Msg3 Enter an alias (or "nickname"). +Msg2 She said, "Hello, World." Msg1 Type "Windows". ``` - For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). - ## SEE ALSO [about_Arrays](about_Arrays.md) @@ -486,5 +499,5 @@ For more information about here-strings, see [about_Quoting_Rules](about_Quoting [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) -["System.Collections.Hashtable"](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN +[System.Collections.Hashtable](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_If.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_If.md index bacd41016bfc..43c54fe84cb6 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_If.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_If.md @@ -73,7 +73,8 @@ if ($a -gt 2) { Write-Host "The value $a is greater than 2." } else { - Write-Host "The value $a is less than or equal to 2, is not created or is not initialized." + Write-Host ("The value $a is less than or equal to 2," + + " is not created or is not initialized.") } ``` @@ -89,7 +90,8 @@ elseif ($a -eq 2) { Write-Host "The value $a is equal to 2." } else { - Write-Host "The value $a is less than 2 or was not created or initialized." + Write-Host ("The value $a is less than 2 or" + + " was not created or initialized.") } ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 31c9c354fcb4..61ddaa58384e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Job_Details --- # About Job Details -## about_Job_Details - - # SHORT DESCRIPTION @@ -20,7 +17,8 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in Windows PowerShell. -This topic is a supplement to the about_Jobs and about_Remote_Jobs topics. +This topic is a supplement to the [about_Jobs](about_Jobs.md) and +[about_Remote_Jobs](about_Remote_Jobs.md) topics. # ABOUT BACKGROUND JOBS @@ -94,65 +92,71 @@ To get the parent and child jobs of a job, use the IncludeChildJobs parameter of the Get-Job cmdlet. The IncludeChildJob parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -IncludeChildJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the parent job and only the child jobs with a particular State value, use the ChildJobState parameter of the Get-Job cmdlet. The ChildJobState parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -ChildJobState Failed -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the child jobs of a job on all versions of Windows PowerShell, use the ChildJob property of the parent job. +```powershell C:\PS> (Get-Job Job1).ChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` You can also use a Get-Job command on the child job, as shown in the following command: +```powershell C:\PS> Get-Job Job3 -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 Failed False localhost Get-Process +``` The configuration of the child job depends on the command that you use to start the job. --- When you use Start-Job to start a job on a local computer, the job -consists of an executive parent job and a child job that runs the -command. +- When you use Start-Job to start a job on a local computer, the job consists + of an executive parent job and a child job that runs the command. --- When you use the AsJob parameter of Invoke-Command to start a job on -one or more computers, the job consists of an executive parent job -and a child job for each job run on each computer. +- When you use the AsJob parameter of Invoke-Command to start a job on one or + more computers, the job consists of an executive parent job and a child job + for each job run on each computer. --- When you use Invoke-Command to run a Start-Job command on one or more -remote computers, the result is the same as a local command run on -each remote computer. The command returns a job object for each -computer. The job object consists of an executive parent job and -one child job that runs the command. +- When you use Invoke-Command to run a Start-Job command on one or more remote + computers, the result is the same as a local command run on each remote + computer. The command returns a job object for each computer. The job object + consists of an executive parent job and one child job that runs the command. -The parent job represents all of the child jobs. When you manage a parent -job, you also manage the associated child jobs. For example, if you stop a -parent job, all child jobs are stopped. If you get the results of a parent -job, you get the results of all child jobs. +The parent job represents all of the child jobs. When you manage a parent job, +you also manage the associated child jobs. For example, if you stop a parent +job, all child jobs are stopped. If you get the results of a parent job, you +get the results of all child jobs. However, you can also manage child jobs individually. This is most useful when you want to investigate a problem with a job or get the results of @@ -161,49 +165,60 @@ Invoke-Command. (The backtick character [`] is the continuation character.) The following command uses the AsJob parameter of Invoke-Command to start background jobs on the local computer and two remote computers. The command -saves the job in the $j variable. +saves the job in the \$j variable. +```powershell PS C:> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` -Command {Get-Date} -AsJob +``` -When you display the Name and ChildJob properties of the job in $j, it +When you display the Name and ChildJob properties of the job in \$j, it shows that the command returned a job object with three child jobs, one for each computer. +```powershell PS C:> $j | Format-List Name, ChildJobs Name : Job3 ChildJobs : {Job4, Job5, Job6} +``` When you display the parent job, it shows that the job failed. +```powershell C:\PS> $j -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- -3 Job3 RemotingJob Failed False localhost,Server... +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- +3 Job3 RemotingJob Failed False localhost,Server... +``` But when you run a Get-Job command that gets the child jobs, the output shows that only one child job failed. +```powershell PS C:> Get-Job -IncludeChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 RemotingJob Failed False localhost,Server... -4 Job4 Completed True localhost Get-Date -5 Job5 Failed False Server01 Get-Date -6 Job6 Completed True Server02 Get-Date +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 RemotingJob Failed False localhost,Server... +4 Job4 Completed True localhost Get-Date +5 Job5 Failed False Server01 Get-Date +6 Job6 Completed True Server02 Get-Date +``` To get the results of all child jobs, use the Receive-Job cmdlet to get the results of the parent job. But you can also get the results of a particular child job, as shown in the following command. -C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, DateTime -Auto +```powershell +C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, +>> DateTime -Auto ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM +``` The child jobs feature of Windows PowerShell background jobs gives you more control over the jobs that you run. @@ -239,86 +254,100 @@ Get-Job returns indicates the job type. The following table lists the job types that come with Windows PowerShell. -Job Type Description --------- ----------- -BackgroundJob Started by using the Start-Job cmdlet. -RemoteJob Started by using the AsJob parameter of the -Invoke-Command cmdlet. -PSWorkflowJob Started by using the AsJob parameter of a -workflow. -PSScheduledJob An instance of a scheduled job started by -a job trigger. -CIMJob Started by using the AsJob parameter of -a cmdlet from a CDXML module. -WMIJob Started by using the AsJob parameter of -a cmdlet from a WMI module. -PSEventJob Created by running Register-ObjectEvent -and specifying an action with the Action -parameter. - -NOTE: Before using the Get-Job cmdlet to get jobs of a particular -type, verify that the module that adds the job type is imported -into the current session. Otherwise, Get-Job does not get jobs of -that type. +|Job Type |Description | +|--------------|----------------------------------------------------------| +|BackgroundJob |Started by using the Start-Job cmdlet. | +|RemoteJob |Started by using the AsJob parameter of the Invoke-Command| +| |cmdlet. | +|PSWorkflowJob |Started by using the AsJob parameter of a workflow. | +|PSScheduledJob|An instance of a scheduled job started by a job trigger. | +|CIMJob |Started by using the AsJob parameter of a cmdlet from a | +| |CDXML module. | +|WMIJob |Started by using the AsJob parameter of a cmdlet from a | +| |WMI module. | +|PSEventJob |Created by running Register-ObjectEvent and specifying an | +| |action with the Action parameter. | + +NOTE: Before using the Get-Job cmdlet to get jobs of a particular type, verify +that the module that adds the job type is imported into the current session. +Otherwise, Get-Job does not get jobs of that type. # EXAMPLE -The following commands create a local background job, a -remote background job, a workflow job, and a scheduled job. -Then, it uses the Get-Job cmdlet to get the jobs. Get-Job -does not get the scheduled job, but it gets any started +The following commands create a local background job, a remote background job, +a workflow job, and a scheduled job. Then, it uses the Get-Job cmdlet to get +the jobs. `Get-Job` does not get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. + +```powershell PS C:> Start-Job -Name LocalData {Get-Process} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Running True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Running True localhost Get-Process +``` Start a background job that runs on a remote computer. -PS C:> Invoke-Command -ComputerName Server01 {Get-Process} -AsJob -JobName RemoteData -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 RemoteData RemoteJob Running True Server01 Get-Process +```powershell +PS C:> Invoke-Command -ComputerName Server01 {Get-Process} ` +-AsJob -JobName RemoteData + +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 RemoteData RemoteJob Running True Server01 Get-Process +``` Create a scheduled job -PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock {Get-Process} ` --Trigger (New-JobTrigger -Once -At "3 PM") +```powershell +PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` + {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` Create a workflow. +```powershell PS C:> workflow Test-Workflow {Get-Process} +``` Run the workflow as a job. +```powershell + PS C:> Test-Workflow -AsJob -JobName TestWFJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +``` -Get the jobs. The Get-Job command does not get scheduled jobs, but it gets +Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets instances of the scheduled job that are started. +```powershell PS C:> Get-Job -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Completed True localhost Get-Process +4 RemoteData RemoteJob Completed True Server01 Get-Process +6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob +8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +``` To get scheduled jobs, use the Get-ScheduledJob cmdlet. + +```powershell PS C:> Get-ScheduledJob Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` # SEE ALSO @@ -328,31 +357,30 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../PSScheduledJob/About/about_Scheduled_Jobs.md) - -Invoke-Command +[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -Suspend-Job +[Remove-Job](../Remove-Job.md) -Resume-Job +[Suspend-Job](../Remove-Job.md) -New-PSSession +[Resume-Job](../Resume-Job) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Register-ScheduledJob +[Exit-PSSession](../Exit-PSSession.md) -Get-ScheduleJob +[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) +[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md index 170a44e2c7e3..e2cf58d05dc1 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,13 +7,10 @@ title: about_Functions_CmdletBindingAttribute --- # About Functions CmdletBindingAttribute -## about_Functions_CmdletBindingAttribute - # SHORT DESCRIPTION -Describes the attribute that makes a function work like a -compiled cmdlet. +Describes the attribute that makes a function work like a compiled cmdlet. # LONG DESCRIPTION @@ -124,13 +121,15 @@ to an advanced function. function Get-Numbers { [CmdletBinding(SupportsPaging = $true)] param() - + $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100) - $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100) - + $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + + $FirstNumber - 1, 100) + if ($PSCmdlet.PagingParameters.IncludeTotalCount) { $TotalCountAccuracy = 1.0 - $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy) + $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, + $TotalCountAccuracy) Write-Output $TotalCount } $FirstNumber .. $LastNumber | Write-Output @@ -173,8 +172,7 @@ must be included when the parameter is used in a function. The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. You can use the Position argument to specify a position value for a parameter. For more information about the Position -argument, see about_Functions_Advanced_Parameters -(http://go.microsoft.com/fwlink/?LinkID=135173). +argument, see [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). # NOTES diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index 15463e8deb2d..ff4eed688151 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,8 +7,6 @@ title: about_Group_Policy_Settings --- # About Group Policy Settings -## about_Group_Policy_Settings - # SHORT DESCRIPTION @@ -16,28 +14,32 @@ Describes the Group Policy settings for Windows PowerShell # LONG DESCRIPTION - Windows PowerShell includes Group Policy settings to help you define consistent option values for servers in an enterprise environment. The Windows PowerShell Group Policy settings are in the following Group Policy paths: -Computer Configuration\Administrative Templates\Windows Components\Windows PowerShell -User Configuration\Administrative Templates\Windows Components\Windows PowerShell + Computer Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell + + User Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell Group policy settings in the User Configuration path take precedence over Group Policy settings in the Computer Configuration path. The policies are as follows: -Turn on Script Execution: Sets the Windows PowerShell execution -policy. -Turn on Module Logging: Sets the LogPipelineExecutionDetails -property of modules. -Set the default source path for Update-Help: -Sets the source for UpdatableHelp to -a directory, not the Internet. +- Turn on Script Execution: Sets the Windows PowerShell execution policy. +- Turn on Module Logging: Sets the LogPipelineExecutionDetails property of + modules. +- Set the default source path for Update-Help: Sets the source for + UpdatableHelp to a directory, not the Internet. To download spreadsheets that list all of the Group Policy settings for each version of Windows, see "Group Policy Settings Reference for Windows @@ -53,28 +55,27 @@ run. If you enable the policy setting, you can select from among the following policy settings. --- "Allow only signed scripts" allows scripts to execute only if they -are signed by a trusted publisher. This policy setting is equivalent -to the AllSigned execution policy. +- "Allow only signed scripts" allows scripts to execute only if they are + signed by a trusted publisher. This policy setting is equivalent to the + AllSigned execution policy. --- "Allow local scripts and remote signed scripts" allows all local -scripts to run. Scripts that originate from the Internet must be -signed by a trusted publisher. This policy setting is equivalent -to the RemoteSigned execution policy. +- "Allow local scripts and remote signed scripts" allows all local scripts to + run. Scripts that originate from the Internet must be signed by a trusted + publisher. This policy setting is equivalent to the RemoteSigned execution + policy. --- "Allow all scripts" allows all scripts to run. This policy -setting is equivalent to the Unrestricted execution policy. +- "Allow all scripts" allows all scripts to run. This policy setting is + equivalent to the Unrestricted execution policy. -If you disable this policy setting, no scripts are allowed to run. -This policy setting is equivalent to the Restricted execution policy. +If you disable this policy setting, no scripts are allowed to run. This policy +setting is equivalent to the Restricted execution policy. -If you disable or do not configure this policy setting, the execution -policy that is set for the computer or user by the Set-ExecutionPolicy -cmdlet determines whether scripts are permitted to run. The default -value is Restricted. +If you disable or do not configure this policy setting, the execution policy +that is set for the computer or user by the Set-ExecutionPolicy cmdlet +determines whether scripts are permitted to run. The default value is +Restricted. -For more information, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](about_Execution_Policies.md). # TURN ON MODULE LOGGING @@ -99,56 +100,54 @@ To turn on module logging for a module, use the following command format. The module must be imported into the session and the setting is effective only in the current session. +```powershell PS C:> Import-Module PS C:> (Get-Module ).LogPipelineExecutionDetails = $true +``` To turn on module logging for all sessions on a particular computer, add the previous commands to the all-users Windows PowerShell profile ($Profile.AllUsers.AllHosts). -For more information about module logging, see about_Modules -(http://go.microsoft.com/fwlink/?LinkID=144311). +For more information about module logging, see [about_Modules](about_Modules.md). # SET THE DEFAULT SOURCE PATH FOR UPDATE-HELP The "Set the Default Source Path for Update-Help" policy setting sets a -default value for the SourcePath parameter of the Update-Help cmdlet. -This setting prevents users from using the Update-Help cmdlet to download -help files from the Internet. +default value for the SourcePath parameter of the Update-Help cmdlet. This +setting prevents users from using the Update-Help cmdlet to download help +files from the Internet. -NOTE: The "Set the default source path for Update-Help" Group -Policy setting appears under Computer Configuration and -User Configuration. However, only the Group Policy setting -under Computer Configuration is effective. The Group Policy -setting under User Configuration is ignored. +NOTE: The "Set the default source path for Update-Help" Group Policy setting +appears under Computer Configuration and User Configuration. However, only the +Group Policy setting under Computer Configuration is effective. The Group +Policy setting under User Configuration is ignored. The Update-Help cmdlet downloads and installs the newest help files for Windows PowerShell modules and installs them on the computer. By default, -Update-Help downloads new help files from an Internet location specified -by the module. +Update-Help downloads new help files from an Internet location specified by +the module. -However, you can use the Save-Help cmdlet to download the newest help -files to a file system location, such as a network share, and then use -the Update-Help cmdlet to get the help files from the file system -location and install them on the computer. The SourcePath parameter of -the Update-Help cmdlet specifies the file system location. +However, you can use the Save-Help cmdlet to download the newest help files to +a file system location, such as a network share, and then use the Update-Help +cmdlet to get the help files from the file system location and install them on +the computer. The SourcePath parameter of the Update-Help cmdlet specifies the +file system location. -By providing a default value for the SourcePath parameter, this Group -Policy setting implicitly adds the SourcePath parameter to all Update-Help -commands. Users can override the particular file system location specified -as the default value by entering a different file system location. But they -cannot remove the SourcePath parameter from the Update-Help command. +By providing a default value for the SourcePath parameter, this Group Policy +setting implicitly adds the SourcePath parameter to all Update-Help commands. +Users can override the particular file system location specified as the +default value by entering a different file system location. But they cannot +remove the SourcePath parameter from the Update-Help command. If you enable this policy setting, you can specify a default value for the SourcePath parameter. Enter a file system location. -If this policy setting is disabled or not configured, there is no -default value for the SourcePath parameter of the Update-Help cmdlet. -Users can download help from the Internet or from any file system -location. +If this policy setting is disabled or not configured, there is no default +value for the SourcePath parameter of the `Update-Help` cmdlet. Users can +download help from the Internet or from any file system location. -For more information, see about_Updatable_Help -(http://go.microsoft.com/fwlink/?LinkID=235801). +For more information, see [about_Updatable_Help](about_Updatable_Help.md). # KEYWORDS @@ -163,13 +162,12 @@ about_GroupPolicy [about_Updatable_Help](about_Updatable_Help.md) -Get-ExecutionPolicy - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Get-Module +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -Update-Help +[Get-Module](../Get-Module.md) -Save-Help +[Update-Help](../Update-Help.md) +[Save-Help](../../Save-Help.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 3b7802845367..174cf4dd2d6a 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,471 +7,484 @@ title: about_Hash_Tables --- # About Hash Tables -## about_Hash_Tables - ## SHORT DESCRIPTION -Describes how to create, use, and sort hash tables in Windows PowerShell. +Describes how to create, use, and sort hash tables in PowerShell. ## LONG DESCRIPTION -A hash table, also known as a dictionary or associative array, is a compact data structure that stores one or more key\/value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In Windows PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) object. You can use the properties and methods of Hashtable objects in Windows PowerShell. +A hash table, also known as a dictionary or associative array, is a compact +data structure that stores one or more key/value pairs. For example, a hash +table might contain a series of IP addresses and computer names, where the IP +addresses are the keys and the computer names are the values, or vice versa. -Beginning in Windows PowerShell 3.0, you can use the [ordered] attribute to create an ordered dictionary (System.Collections.Specialized.OrderedDictionary) in Windows PowerShell. +In PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) +object. You can use the properties and methods of Hashtable objects in +PowerShell. -Ordered dictionaries differ from hash tables in that the keys always appear in the order in which you list them. The order of keys in a hash table is not determined. +Beginning in PowerShell 3.0, you can use the [ordered] attribute to create an +ordered dictionary (System.Collections.Specialized.OrderedDictionary) in +PowerShell. -The keys and value in hash tables are also .NET objects. They are most often strings or integers, but they can have any object type. You can also create nested hash tables, in which the value of a key is another hash table. +Ordered dictionaries differ from hash tables in that the keys always appear in +the order in which you list them. The order of keys in a hash table is not +determined. -Hash tables are frequently used because they are very efficient for finding and retrieving data. You can use hash tables to store lists and to create calculated properties in Windows PowerShell. And, Windows PowerShell has a cmdlet, ConvertFrom-StringData, that converts strings to a hash table. +The keys and value in hash tables are also .NET objects. They are most often +strings or integers, but they can have any object type. You can also create +nested hash tables, in which the value of a key is another hash table. +Hash tables are frequently used because they are very efficient for finding +and retrieving data. You can use hash tables to store lists and to create +calculated properties in PowerShell. And, PowerShell has a cmdlet, +ConvertFrom-StringData, that converts strings to a hash table. ### Syntax -The syntax of a hash table is as follows: +The syntax of a hash table is as follows: -``` +```powershell @{ = ; [ = ] ...} ``` - The syntax of an ordered dictionary is as follows: - -``` +```powershell [ordered]@{ = ; [ = ] ...} ``` - -The [ordered] attribute was introduced in Windows PowerShell 3.0. - +The [ordered] attribute was introduced in PowerShell 3.0. ### Creating Hash Tables + To create a hash table, follow these guidelines: - Begin the hash table with an at sign (@). - - Enclose the hash table in braces ({}). - -- Enter one or more key\/value pairs for the content of the hash table. - -- Use an equal sign (\=) to separate each key from its value. - -- Use a semicolon (;) or a line break to separate the key\/value pairs. - -- Key that contains spaces must be enclosed in quotation marks. Values must be valid Windows PowerShell expressions. Strings must appear in quotation marks, even if they do not include spaces. - +- Enter one or more key/value pairs for the content of the hash table. +- Use an equal sign (=) to separate each key from its value. +- Use a semicolon (;) or a line break to separate the key/value pairs. +- Key that contains spaces must be enclosed in quotation marks. Values must be + valid PowerShell expressions. Strings must appear in quotation marks, even if + they do not include spaces. - To manage the hash table, save it in a variable. - -- When assigning an ordered hash table to a variable, place the [ordered] attribute before the "@" symbol. If you place it before the variable name, the command fails. +- When assigning an ordered hash table to a variable, place the [ordered] + attribute before the "@" symbol. If you place it before the variable name, the + command fails. To create an empty hash table in the value of $hash, type: - -``` +```powershell $hash = @{} ``` +You can also add keys and values to a hash table when you create it. For +example, the following statement creates a hash table with three keys. -You can also add keys and values to a hash table when you create it. For example, the following statement creates a hash table with three keys. - - -``` +```powershell $hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} ``` - - ### Creating Ordered Dictionaries -You can create an ordered dictionary by adding an object of the OrderedDictionary type, but the easiest way to create an ordered dictionary is use the [Ordered] attribute. -The [ordered] attribute is introduced in Windows PowerShell 3.0. +You can create an ordered dictionary by adding an object of the +OrderedDictionary type, but the easiest way to create an ordered dictionary is +use the [Ordered] attribute. -Place the attribute immediately before the "@" symbol. +The [ordered] attribute is introduced in PowerShell 3.0. +Place the attribute immediately before the "@" symbol. -``` +```powershell $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` +You can use ordered dictionaries in the same way that you use hash tables. +Either type can be used as the value of parameters that take a hash table or +dictionary (iDictionary). -You can use ordered dictionaries in the same way that you use hash tables. Either type can be used as the value of parameters that take a hash table or dictionary (iDictionary). +You cannot use the [ordered] attribute to convert or cast a hash table. If you +place the ordered attribute before the variable name, the command fails with +the following error message. -You cannot use the [ordered] attribute to convert or cast a hash table. If you place the ordered attribute before the variable name, the command fails with the following error message. - - -``` -PS C:\> [ordered]$hash = @{} -At line:1 char:1 -+ [ordered]$hash = @{} -+ [!INCLUDE[]()] -The ordered attribute can be specified only on a hash literal node. -+ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException +```powershell +PS C:\> [ordered]$hash = @{} +At line:1 char:1 ++ [ordered]$hash = @{} ++ [!INCLUDE[]()] +The ordered attribute can be specified only on a hash literal node. ++ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordExc +eption + FullyQualifiedErrorId : OrderedAttributeOnlyOnHashLiteralNode ``` - To correct the expression, move the [ordered] attribute. - -``` +```powershell PS C:\> $hash = [ordered]@{} ``` - -You can cast an ordered dictionary to a hash table, but you cannot recover the ordered attribute, even if you clear the variable and enter new values. To re-establish the order, you must remove and recreate the variable. - +You can cast an ordered dictionary to a hash table, but you cannot recover the +ordered attribute, even if you clear the variable and enter new values. To +re-establish the order, you must remove and recreate the variable. ``` -PS C:\> [hashtable]$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} -PS C:\ps-test> $hash - -Name Value ----- ----- -Color Blue -Shape Square +PS C:\> [hashtable]$hash = [ordered]@{ +>> Number = 1; Shape = "Square"; Color = "Blue"} +PS C:\> $hash + +Name Value +---- ----- +Color Blue +Shape Square Number 1 ``` - - ### Displaying Hash Tables -To display a hash table that is saved in a variable, type the variable name. By default, a hash tables is displayed as a table with one column for keys and one for values. +To display a hash table that is saved in a variable, type the variable name. +By default, a hash tables is displayed as a table with one column for keys and +one for values. -``` -C:\PS> $hash - -Name Value ----- ----- -Shape Square -Color Blue +```powershell +C:\PS> $hash + +Name Value +---- ----- +Shape Square +Color Blue Number 1 ``` +Hash tables have Keys and Values properties. Use dot notation to display all +of the keys or all of the values. -Hash tables have Keys and Values properties. Use dot notation to display all of the keys or all of the values. +```powershell +C:\PS> $hash.keys +Number +Shape +Color - -``` -C:\PS> $hash.keys -Number -Shape -Color - -C:\PS> $hash.values -1 -Square +C:\PS> $hash.values +1 +Square Blue ``` +Each key name is also a property of the hash table, and its value is the value +of the key-name property. Use the following format to display the property +values. -Each key name is also a property of the hash table, and its value is the value of the key-name property. Use the following format to display the property values. - - -``` -$hashtable. +```powershell +$hashtable. ``` - For example: +```powershell +C:\PS> $hash.Number +1 -``` -C:\PS> $hash.Number -1 - -C:\PS> $hash.Color +C:\PS> $hash.Color Blue ``` +If the key name collides with one of the property names of the HashTable type, +you can use `PSBase` to access those properties. For example, if the key name +is `keys` and you want to return the collection of Keys, use this syntax: -Hash tables have a Count property that indicates the number of key-value pairs in the hash table. +```powershell +$hashtable.PSBase.Keys +``` +Hash tables have a Count property that indicates the number of key-value pairs +in the hash table. -``` -C:\PS> $hash.count +```powershell +C:\PS> $hash.count 3 ``` - -Hash table tables are not arrays, so you cannot use an integer as an index into the hash table, but you can use a key name to index into the hash table. If the key is a string value, enclose the key name in quotation marks. +Hash table tables are not arrays, so you cannot use an integer as an index +into the hash table, but you can use a key name to index into the hash table. +If the key is a string value, enclose the key name in quotation marks. For example: - -``` -C:\PS> $hash["Number"] +```powershell +C:\PS> $hash["Number"] 1 ``` - - ### Adding and Removing Keys and Values -To add keys and values to a hash table, use the following command format. +To add keys and values to a hash table, use the following command format. -``` +```powershell $hash[""] = "" ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash["Time"] = "Now" ``` +You can also add keys and values to a hash table by using the Add method of +the System.Collections.Hashtable object. The Add method has the following +syntax: -You can also add keys and values to a hash table by using the Add method of the System.Collections.Hashtable object. The Add method has the following syntax: - - -``` +```powershell Add(Key, Value) ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash = $hash.Add("Time", "Now") ``` +And, you can add keys and values to a hash table by using the addition +operator (+) to add a hash table to an existing hash table. For example, the +following statement adds a "Time" key with a value of "Now" to the hash table +in the $hash variable. -And, you can add keys and values to a hash table by using the addition operator (\+) to add a hash table to an existing hash table. For example, the following statement adds a "Time" key with a value of "Now" to the hash table in the $hash variable. - - -``` +```powershell $hash = $hash + @{Time="Now"} ``` - You can also add values that are stored in variables. +```powershell +$t = "Today" +$now = (Get-Date) -``` -$t = "Today" -$now = (Get-Date) - $hash.Add($t, $now) ``` - -You cannot use a subtraction operator to remove a key\/value pair from a hash table, but you can use the Remove method of the Hashtable object. The Remove method takes the key as its value. +You cannot use a subtraction operator to remove a key/value pair from a hash +table, but you can use the Remove method of the Hashtable object. The Remove +method takes the key as its value. The Remove method has the following syntax: - ``` Remove(Key) ``` +For example, to remove the Time=Now key/value pair from the hash table in the +value of the $hash variable, type: -For example, to remove the Time\=Now key\/value pair from the hash table in the value of the $hash variable, type: - - -``` -$hash.$Remove("Time") +```powershell +$hash.Remove("Time") ``` - -You can use all of the properties and methods of Hashtable objects in Windows PowerShell, including Contains, Clear, Clone, and CopyTo. For more information about Hashtable objects, see [System.Collections.Hashtable](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN. - +You can use all of the properties and methods of Hashtable objects in +PowerShell, including Contains, Clear, Clone, and CopyTo. For more information +about Hashtable objects, see "System.Collections.Hashtable" on MSDN. ### Object Types in HashTables -The keys and values in a hash table can have any .NET object type, and a single hash table can have keys and values of multiple types. -The following statement creates a hash table of process name strings and process object values and saves it in the $p variable. +The keys and values in a hash table can have any .NET object type, and a +single hash table can have keys and values of multiple types. +The following statement creates a hash table of process name strings and +process object values and saves it in the \$p variable. -``` -$p = @{"PowerShell" = (get-process PowerShell); +```powershell +$p = @{"PowerShell" = (get-process PowerShell); "Notepad" = (get-process notepad)} ``` +You can display the hash table in \$p and use the key-name properties to +display the values. -You can display the hash table in $p and use the key-name properties to display the values. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) - -C:\PS> $p.PowerShell - -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName -------- ------ ----- ----- ----- ------ -- ----------- - 441 24 54196 54012 571 5.10 1788 PowerShell - -C:\PS> $p.keys | foreach {$p.$_.handles} -441 -251 -``` +C:\PS> $p.PowerShell +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 441 24 54196 54012 571 5.10 1788 PowerShell -The keys in a hash table can also be any .NET type. The following statement adds a key\/value pair to the hash table in the $p variable. The key is a Service object that represents the WinRM service, and the value is the current status of the service. +C:\PS> $p.keys | foreach {$p.$_.handles} +441 +251 +``` +The keys in a hash table can also be any .NET type. The following statement +adds a key/value pair to the hash table in the \$p variable. The key is a +Service object that represents the WinRM service, and the value is the current +status of the service. -``` +```powershell C:\PS> $p = $p + @{(Get-Service WinRM) = ((Get-Service WinRM).Status)} ``` +You can display and access the new key/value pair by using the same methods +that you use for other pairs in the hash table. -You can display and access the new key\/value pair by using the same methods that you use for other pairs in the hash table. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running - -C:\PS> $p.keys -PowerShell -Notepad - -Status Name DisplayName ------- ---- ----------- -Running winrm Windows Remote Management (WS-Manag... - -C:\PS> $p.keys | foreach {$_.name} -winrm -``` +C:\PS> $p.keys +PowerShell +Notepad +Status Name DisplayName +------ ---- ----------- +Running winrm Windows Remote Management (WS-Manag... -The keys and values in a hash table can also be Hashtable objects. The following statement adds key\/value pair to the hash table in the $p variable in which the key is a string, Hash2, and the value is a hash table with three key\/value pairs. +C:\PS> $p.keys | foreach {$_.name} +winrm +``` +The keys and values in a hash table can also be Hashtable objects. The +following statement adds key/value pair to the hash table in the \$p variable +in which the key is a string, Hash2, and the value is a hash table with three +key/value pairs. -``` +```powershell C:\PS> $p = $p + @{"Hash2"= @{a=1; b=2; c=3}} ``` - You can display and access the new values by using the same methods. +```powershell +C:\PS> $p -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running -Hash2 {a, b, c} - -C:\PS> $p.Hash2 - -Name Value ----- ----- -a 1 -b 2 -c 3 - -C:\PS> $p.Hash2.b -2 -``` +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running +Hash2 {a, b, c} +C:\PS> $p.Hash2 +Name Value +---- ----- +a 1 +b 2 +c 3 + +C:\PS> $p.Hash2.b +2 +``` ### Sorting Keys and Values -The items in a hash table are intrinsically unordered. The key\/value pairs might appear in a different order each time that you display them. -Although you cannot sort a hash table, you can use the GetEnumerator method of hash tables to enumerate the keys and values, and then use the Sort-Object cmdlet to sort the enumerated values for display. +The items in a hash table are intrinsically unordered. The key/value pairs +might appear in a different order each time that you display them. -For example, the following commands enumerate the keys and values in the hash table in the $p variable and then sort the keys in alphabetical order. +Although you cannot sort a hash table, you can use the GetEnumerator method of +hash tables to enumerate the keys and values, and then use the Sort-Object +cmdlet to sort the enumerated values for display. +For example, the following commands enumerate the keys and values in the hash +table in the \$p variable and then sort the keys in alphabetical order. -``` -C:\PS> $p.GetEnumerator() | Sort-Object -Property key - -Name Value ----- ----- -Notepad System.Diagnostics.Process (notepad) -PowerShell System.Diagnostics.Process (PowerShell) +```powershell +C:\PS> $p.GetEnumerator() | Sort-Object -Property key + +Name Value +---- ----- +Notepad System.Diagnostics.Process (notepad) +PowerShell System.Diagnostics.Process (PowerShell) System.ServiceProcess.Servi... Running ``` +The following command uses the same procedure to sort the hash values in +descending order. -The following command uses the same procedure to sort the hash values in descending order. +```powershell +C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -``` -C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) System.ServiceProcess.Servi... Running ``` - - ### Creating Objects from Hash Tables -Beginning in Windows PowerShell 3.0, you can create an object from a hash table of properties and property values. -The syntax is as follows: +Beginning in PowerShell 3.0, you can create an object from a hash table of +properties and property values. +The syntax is as follows: -``` -[]@{=;=} +```powershell +[]@{ + = + = +} ``` +This method works only for classes that have a null constructor, that is, a +constructor that has no parameters. The object properties must be public and +settable. -This method works only for classes that have a null constructor, that is, a constructor that has no parameters. The object properties must be public and settable. - -For more information, see [about_Object_Creation](about_Object_Creation.md). - +For more information, see [about_Object_Creation(about_Object_Creation.md)]. ### ConvertFrom-StringData -The ConvertFrom-StringData cmdlet converts a string or a here-string of key\/value pairs into a hash table. You can use the ConvertFrom-StringData cmdlet safely in the Data section of a script, and you can use it with the Import-LocalizedData cmdlet to display user messages in the user-interface (UI) culture of the current user. -Here-strings are especially useful when the values in the hash table include quotation marks. (For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md).) +The `ConvertFrom-StringData` cmdlet converts a string or a here-string of +key/value pairs into a hash table. You can use the `ConvertFrom-StringData` +cmdlet safely in the Data section of a script, and you can use it with the +`Import-LocalizedData` cmdlet to display user messages in the user-interface +(UI) culture of the current user. -The following example shows how to create a here-string of the user messages in the previous example and how to use ConvertFrom-StringData to convert them from a string into a hash table. +Here-strings are especially useful when the values in the hash table include +quotation marks. For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). -The following command creates a here-string of the key\/value pairs and then saves it in the $string variable. +The following example shows how to create a here-string of the user messages +in the previous example and how to use `ConvertFrom-StringData` to convert them +from a string into a hash table. +The following command creates a here-string of the key/value pairs and then +saves it in the \$string variable. -``` -C:\PS> $string = @" -Msg1 = Type "Windows". -Msg2 = She said, "Hello, World." -Msg3 = Enter an alias (or "nickname"). +```powershell +C:\PS> $string = @" +Msg1 = Type "Windows". +Msg2 = She said, "Hello, World." +Msg3 = Enter an alias (or "nickname"). "@ ``` +This command uses the ConvertFrom-StringData cmdlet to convert the here-string +into a hash table. -This command uses the ConvertFrom-StringData cmdlet to convert the here-string into a hash table. - +```powershell +C:\PS> ConvertFrom-StringData $string -``` -C:\PS> ConvertFrom-StringData $string - -Name Value ----- ----- -Msg3 Enter an alias (or "nickname"). -Msg2 She said, "Hello, World." +Name Value +---- ----- +Msg3 Enter an alias (or "nickname"). +Msg2 She said, "Hello, World." Msg1 Type "Windows". ``` - For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). - ## SEE ALSO [about_Arrays](about_Arrays.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_If.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_If.md index bacd41016bfc..43c54fe84cb6 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_If.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_If.md @@ -73,7 +73,8 @@ if ($a -gt 2) { Write-Host "The value $a is greater than 2." } else { - Write-Host "The value $a is less than or equal to 2, is not created or is not initialized." + Write-Host ("The value $a is less than or equal to 2," + + " is not created or is not initialized.") } ``` @@ -89,7 +90,8 @@ elseif ($a -eq 2) { Write-Host "The value $a is equal to 2." } else { - Write-Host "The value $a is less than 2 or was not created or initialized." + Write-Host ("The value $a is less than 2 or" + + " was not created or initialized.") } ``` diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 31c9c354fcb4..61ddaa58384e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Job_Details --- # About Job Details -## about_Job_Details - - # SHORT DESCRIPTION @@ -20,7 +17,8 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in Windows PowerShell. -This topic is a supplement to the about_Jobs and about_Remote_Jobs topics. +This topic is a supplement to the [about_Jobs](about_Jobs.md) and +[about_Remote_Jobs](about_Remote_Jobs.md) topics. # ABOUT BACKGROUND JOBS @@ -94,65 +92,71 @@ To get the parent and child jobs of a job, use the IncludeChildJobs parameter of the Get-Job cmdlet. The IncludeChildJob parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -IncludeChildJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the parent job and only the child jobs with a particular State value, use the ChildJobState parameter of the Get-Job cmdlet. The ChildJobState parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -ChildJobState Failed -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the child jobs of a job on all versions of Windows PowerShell, use the ChildJob property of the parent job. +```powershell C:\PS> (Get-Job Job1).ChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` You can also use a Get-Job command on the child job, as shown in the following command: +```powershell C:\PS> Get-Job Job3 -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 Failed False localhost Get-Process +``` The configuration of the child job depends on the command that you use to start the job. --- When you use Start-Job to start a job on a local computer, the job -consists of an executive parent job and a child job that runs the -command. +- When you use Start-Job to start a job on a local computer, the job consists + of an executive parent job and a child job that runs the command. --- When you use the AsJob parameter of Invoke-Command to start a job on -one or more computers, the job consists of an executive parent job -and a child job for each job run on each computer. +- When you use the AsJob parameter of Invoke-Command to start a job on one or + more computers, the job consists of an executive parent job and a child job + for each job run on each computer. --- When you use Invoke-Command to run a Start-Job command on one or more -remote computers, the result is the same as a local command run on -each remote computer. The command returns a job object for each -computer. The job object consists of an executive parent job and -one child job that runs the command. +- When you use Invoke-Command to run a Start-Job command on one or more remote + computers, the result is the same as a local command run on each remote + computer. The command returns a job object for each computer. The job object + consists of an executive parent job and one child job that runs the command. -The parent job represents all of the child jobs. When you manage a parent -job, you also manage the associated child jobs. For example, if you stop a -parent job, all child jobs are stopped. If you get the results of a parent -job, you get the results of all child jobs. +The parent job represents all of the child jobs. When you manage a parent job, +you also manage the associated child jobs. For example, if you stop a parent +job, all child jobs are stopped. If you get the results of a parent job, you +get the results of all child jobs. However, you can also manage child jobs individually. This is most useful when you want to investigate a problem with a job or get the results of @@ -161,49 +165,60 @@ Invoke-Command. (The backtick character [`] is the continuation character.) The following command uses the AsJob parameter of Invoke-Command to start background jobs on the local computer and two remote computers. The command -saves the job in the $j variable. +saves the job in the \$j variable. +```powershell PS C:> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` -Command {Get-Date} -AsJob +``` -When you display the Name and ChildJob properties of the job in $j, it +When you display the Name and ChildJob properties of the job in \$j, it shows that the command returned a job object with three child jobs, one for each computer. +```powershell PS C:> $j | Format-List Name, ChildJobs Name : Job3 ChildJobs : {Job4, Job5, Job6} +``` When you display the parent job, it shows that the job failed. +```powershell C:\PS> $j -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- -3 Job3 RemotingJob Failed False localhost,Server... +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- +3 Job3 RemotingJob Failed False localhost,Server... +``` But when you run a Get-Job command that gets the child jobs, the output shows that only one child job failed. +```powershell PS C:> Get-Job -IncludeChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 RemotingJob Failed False localhost,Server... -4 Job4 Completed True localhost Get-Date -5 Job5 Failed False Server01 Get-Date -6 Job6 Completed True Server02 Get-Date +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 RemotingJob Failed False localhost,Server... +4 Job4 Completed True localhost Get-Date +5 Job5 Failed False Server01 Get-Date +6 Job6 Completed True Server02 Get-Date +``` To get the results of all child jobs, use the Receive-Job cmdlet to get the results of the parent job. But you can also get the results of a particular child job, as shown in the following command. -C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, DateTime -Auto +```powershell +C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, +>> DateTime -Auto ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM +``` The child jobs feature of Windows PowerShell background jobs gives you more control over the jobs that you run. @@ -239,86 +254,100 @@ Get-Job returns indicates the job type. The following table lists the job types that come with Windows PowerShell. -Job Type Description --------- ----------- -BackgroundJob Started by using the Start-Job cmdlet. -RemoteJob Started by using the AsJob parameter of the -Invoke-Command cmdlet. -PSWorkflowJob Started by using the AsJob parameter of a -workflow. -PSScheduledJob An instance of a scheduled job started by -a job trigger. -CIMJob Started by using the AsJob parameter of -a cmdlet from a CDXML module. -WMIJob Started by using the AsJob parameter of -a cmdlet from a WMI module. -PSEventJob Created by running Register-ObjectEvent -and specifying an action with the Action -parameter. - -NOTE: Before using the Get-Job cmdlet to get jobs of a particular -type, verify that the module that adds the job type is imported -into the current session. Otherwise, Get-Job does not get jobs of -that type. +|Job Type |Description | +|--------------|----------------------------------------------------------| +|BackgroundJob |Started by using the Start-Job cmdlet. | +|RemoteJob |Started by using the AsJob parameter of the Invoke-Command| +| |cmdlet. | +|PSWorkflowJob |Started by using the AsJob parameter of a workflow. | +|PSScheduledJob|An instance of a scheduled job started by a job trigger. | +|CIMJob |Started by using the AsJob parameter of a cmdlet from a | +| |CDXML module. | +|WMIJob |Started by using the AsJob parameter of a cmdlet from a | +| |WMI module. | +|PSEventJob |Created by running Register-ObjectEvent and specifying an | +| |action with the Action parameter. | + +NOTE: Before using the Get-Job cmdlet to get jobs of a particular type, verify +that the module that adds the job type is imported into the current session. +Otherwise, Get-Job does not get jobs of that type. # EXAMPLE -The following commands create a local background job, a -remote background job, a workflow job, and a scheduled job. -Then, it uses the Get-Job cmdlet to get the jobs. Get-Job -does not get the scheduled job, but it gets any started +The following commands create a local background job, a remote background job, +a workflow job, and a scheduled job. Then, it uses the Get-Job cmdlet to get +the jobs. `Get-Job` does not get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. + +```powershell PS C:> Start-Job -Name LocalData {Get-Process} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Running True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Running True localhost Get-Process +``` Start a background job that runs on a remote computer. -PS C:> Invoke-Command -ComputerName Server01 {Get-Process} -AsJob -JobName RemoteData -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 RemoteData RemoteJob Running True Server01 Get-Process +```powershell +PS C:> Invoke-Command -ComputerName Server01 {Get-Process} ` +-AsJob -JobName RemoteData + +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 RemoteData RemoteJob Running True Server01 Get-Process +``` Create a scheduled job -PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock {Get-Process} ` --Trigger (New-JobTrigger -Once -At "3 PM") +```powershell +PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` + {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` Create a workflow. +```powershell PS C:> workflow Test-Workflow {Get-Process} +``` Run the workflow as a job. +```powershell + PS C:> Test-Workflow -AsJob -JobName TestWFJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +``` -Get the jobs. The Get-Job command does not get scheduled jobs, but it gets +Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets instances of the scheduled job that are started. +```powershell PS C:> Get-Job -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Completed True localhost Get-Process +4 RemoteData RemoteJob Completed True Server01 Get-Process +6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob +8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +``` To get scheduled jobs, use the Get-ScheduledJob cmdlet. + +```powershell PS C:> Get-ScheduledJob Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` # SEE ALSO @@ -328,31 +357,30 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../PSScheduledJob/About/about_Scheduled_Jobs.md) - -Invoke-Command +[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -Suspend-Job +[Remove-Job](../Remove-Job.md) -Resume-Job +[Suspend-Job](../Remove-Job.md) -New-PSSession +[Resume-Job](../Resume-Job) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Register-ScheduledJob +[Exit-PSSession](../Exit-PSSession.md) -Get-ScheduleJob +[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) +[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md index 170a44e2c7e3..e2cf58d05dc1 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,13 +7,10 @@ title: about_Functions_CmdletBindingAttribute --- # About Functions CmdletBindingAttribute -## about_Functions_CmdletBindingAttribute - # SHORT DESCRIPTION -Describes the attribute that makes a function work like a -compiled cmdlet. +Describes the attribute that makes a function work like a compiled cmdlet. # LONG DESCRIPTION @@ -124,13 +121,15 @@ to an advanced function. function Get-Numbers { [CmdletBinding(SupportsPaging = $true)] param() - + $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100) - $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100) - + $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + + $FirstNumber - 1, 100) + if ($PSCmdlet.PagingParameters.IncludeTotalCount) { $TotalCountAccuracy = 1.0 - $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy) + $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, + $TotalCountAccuracy) Write-Output $TotalCount } $FirstNumber .. $LastNumber | Write-Output @@ -173,8 +172,7 @@ must be included when the parameter is used in a function. The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. You can use the Position argument to specify a position value for a parameter. For more information about the Position -argument, see about_Functions_Advanced_Parameters -(http://go.microsoft.com/fwlink/?LinkID=135173). +argument, see [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). # NOTES diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index 15463e8deb2d..ff4eed688151 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,8 +7,6 @@ title: about_Group_Policy_Settings --- # About Group Policy Settings -## about_Group_Policy_Settings - # SHORT DESCRIPTION @@ -16,28 +14,32 @@ Describes the Group Policy settings for Windows PowerShell # LONG DESCRIPTION - Windows PowerShell includes Group Policy settings to help you define consistent option values for servers in an enterprise environment. The Windows PowerShell Group Policy settings are in the following Group Policy paths: -Computer Configuration\Administrative Templates\Windows Components\Windows PowerShell -User Configuration\Administrative Templates\Windows Components\Windows PowerShell + Computer Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell + + User Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell Group policy settings in the User Configuration path take precedence over Group Policy settings in the Computer Configuration path. The policies are as follows: -Turn on Script Execution: Sets the Windows PowerShell execution -policy. -Turn on Module Logging: Sets the LogPipelineExecutionDetails -property of modules. -Set the default source path for Update-Help: -Sets the source for UpdatableHelp to -a directory, not the Internet. +- Turn on Script Execution: Sets the Windows PowerShell execution policy. +- Turn on Module Logging: Sets the LogPipelineExecutionDetails property of + modules. +- Set the default source path for Update-Help: Sets the source for + UpdatableHelp to a directory, not the Internet. To download spreadsheets that list all of the Group Policy settings for each version of Windows, see "Group Policy Settings Reference for Windows @@ -53,28 +55,27 @@ run. If you enable the policy setting, you can select from among the following policy settings. --- "Allow only signed scripts" allows scripts to execute only if they -are signed by a trusted publisher. This policy setting is equivalent -to the AllSigned execution policy. +- "Allow only signed scripts" allows scripts to execute only if they are + signed by a trusted publisher. This policy setting is equivalent to the + AllSigned execution policy. --- "Allow local scripts and remote signed scripts" allows all local -scripts to run. Scripts that originate from the Internet must be -signed by a trusted publisher. This policy setting is equivalent -to the RemoteSigned execution policy. +- "Allow local scripts and remote signed scripts" allows all local scripts to + run. Scripts that originate from the Internet must be signed by a trusted + publisher. This policy setting is equivalent to the RemoteSigned execution + policy. --- "Allow all scripts" allows all scripts to run. This policy -setting is equivalent to the Unrestricted execution policy. +- "Allow all scripts" allows all scripts to run. This policy setting is + equivalent to the Unrestricted execution policy. -If you disable this policy setting, no scripts are allowed to run. -This policy setting is equivalent to the Restricted execution policy. +If you disable this policy setting, no scripts are allowed to run. This policy +setting is equivalent to the Restricted execution policy. -If you disable or do not configure this policy setting, the execution -policy that is set for the computer or user by the Set-ExecutionPolicy -cmdlet determines whether scripts are permitted to run. The default -value is Restricted. +If you disable or do not configure this policy setting, the execution policy +that is set for the computer or user by the Set-ExecutionPolicy cmdlet +determines whether scripts are permitted to run. The default value is +Restricted. -For more information, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](about_Execution_Policies.md). # TURN ON MODULE LOGGING @@ -99,56 +100,54 @@ To turn on module logging for a module, use the following command format. The module must be imported into the session and the setting is effective only in the current session. +```powershell PS C:> Import-Module PS C:> (Get-Module ).LogPipelineExecutionDetails = $true +``` To turn on module logging for all sessions on a particular computer, add the previous commands to the all-users Windows PowerShell profile ($Profile.AllUsers.AllHosts). -For more information about module logging, see about_Modules -(http://go.microsoft.com/fwlink/?LinkID=144311). +For more information about module logging, see [about_Modules](about_Modules.md). # SET THE DEFAULT SOURCE PATH FOR UPDATE-HELP The "Set the Default Source Path for Update-Help" policy setting sets a -default value for the SourcePath parameter of the Update-Help cmdlet. -This setting prevents users from using the Update-Help cmdlet to download -help files from the Internet. +default value for the SourcePath parameter of the Update-Help cmdlet. This +setting prevents users from using the Update-Help cmdlet to download help +files from the Internet. -NOTE: The "Set the default source path for Update-Help" Group -Policy setting appears under Computer Configuration and -User Configuration. However, only the Group Policy setting -under Computer Configuration is effective. The Group Policy -setting under User Configuration is ignored. +NOTE: The "Set the default source path for Update-Help" Group Policy setting +appears under Computer Configuration and User Configuration. However, only the +Group Policy setting under Computer Configuration is effective. The Group +Policy setting under User Configuration is ignored. The Update-Help cmdlet downloads and installs the newest help files for Windows PowerShell modules and installs them on the computer. By default, -Update-Help downloads new help files from an Internet location specified -by the module. +Update-Help downloads new help files from an Internet location specified by +the module. -However, you can use the Save-Help cmdlet to download the newest help -files to a file system location, such as a network share, and then use -the Update-Help cmdlet to get the help files from the file system -location and install them on the computer. The SourcePath parameter of -the Update-Help cmdlet specifies the file system location. +However, you can use the Save-Help cmdlet to download the newest help files to +a file system location, such as a network share, and then use the Update-Help +cmdlet to get the help files from the file system location and install them on +the computer. The SourcePath parameter of the Update-Help cmdlet specifies the +file system location. -By providing a default value for the SourcePath parameter, this Group -Policy setting implicitly adds the SourcePath parameter to all Update-Help -commands. Users can override the particular file system location specified -as the default value by entering a different file system location. But they -cannot remove the SourcePath parameter from the Update-Help command. +By providing a default value for the SourcePath parameter, this Group Policy +setting implicitly adds the SourcePath parameter to all Update-Help commands. +Users can override the particular file system location specified as the +default value by entering a different file system location. But they cannot +remove the SourcePath parameter from the Update-Help command. If you enable this policy setting, you can specify a default value for the SourcePath parameter. Enter a file system location. -If this policy setting is disabled or not configured, there is no -default value for the SourcePath parameter of the Update-Help cmdlet. -Users can download help from the Internet or from any file system -location. +If this policy setting is disabled or not configured, there is no default +value for the SourcePath parameter of the `Update-Help` cmdlet. Users can +download help from the Internet or from any file system location. -For more information, see about_Updatable_Help -(http://go.microsoft.com/fwlink/?LinkID=235801). +For more information, see [about_Updatable_Help](about_Updatable_Help.md). # KEYWORDS @@ -163,13 +162,12 @@ about_GroupPolicy [about_Updatable_Help](about_Updatable_Help.md) -Get-ExecutionPolicy - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Get-Module +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -Update-Help +[Get-Module](../Get-Module.md) -Save-Help +[Update-Help](../Update-Help.md) +[Save-Help](../../Save-Help.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 990afdf7e6a0..174cf4dd2d6a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,478 +7,484 @@ title: about_Hash_Tables --- # About Hash Tables -## about_Hash_Tables - ## SHORT DESCRIPTION -Describes how to create, use, and sort hash tables in Windows PowerShell. +Describes how to create, use, and sort hash tables in PowerShell. ## LONG DESCRIPTION -A hash table, also known as a dictionary or associative array, is a compact data structure that stores one or more key\/value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In Windows PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) object. You can use the properties and methods of Hashtable objects in Windows PowerShell. +A hash table, also known as a dictionary or associative array, is a compact +data structure that stores one or more key/value pairs. For example, a hash +table might contain a series of IP addresses and computer names, where the IP +addresses are the keys and the computer names are the values, or vice versa. -Beginning in Windows PowerShell 3.0, you can use the [ordered] attribute to create an ordered dictionary (System.Collections.Specialized.OrderedDictionary) in Windows PowerShell. +In PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) +object. You can use the properties and methods of Hashtable objects in +PowerShell. -Ordered dictionaries differ from hash tables in that the keys always appear in the order in which you list them. The order of keys in a hash table is not determined. +Beginning in PowerShell 3.0, you can use the [ordered] attribute to create an +ordered dictionary (System.Collections.Specialized.OrderedDictionary) in +PowerShell. -The keys and value in hash tables are also .NET objects. They are most often strings or integers, but they can have any object type. You can also create nested hash tables, in which the value of a key is another hash table. +Ordered dictionaries differ from hash tables in that the keys always appear in +the order in which you list them. The order of keys in a hash table is not +determined. -Hash tables are frequently used because they are very efficient for finding and retrieving data. You can use hash tables to store lists and to create calculated properties in Windows PowerShell. And, Windows PowerShell has a cmdlet, ConvertFrom-StringData, that converts strings to a hash table. +The keys and value in hash tables are also .NET objects. They are most often +strings or integers, but they can have any object type. You can also create +nested hash tables, in which the value of a key is another hash table. +Hash tables are frequently used because they are very efficient for finding +and retrieving data. You can use hash tables to store lists and to create +calculated properties in PowerShell. And, PowerShell has a cmdlet, +ConvertFrom-StringData, that converts strings to a hash table. ### Syntax -The syntax of a hash table is as follows: +The syntax of a hash table is as follows: -``` +```powershell @{ = ; [ = ] ...} ``` - The syntax of an ordered dictionary is as follows: - -``` +```powershell [ordered]@{ = ; [ = ] ...} ``` - -The [ordered] attribute was introduced in Windows PowerShell 3.0. - +The [ordered] attribute was introduced in PowerShell 3.0. ### Creating Hash Tables + To create a hash table, follow these guidelines: - Begin the hash table with an at sign (@). - - Enclose the hash table in braces ({}). - -- Enter one or more key\/value pairs for the content of the hash table. - -- Use an equal sign (\=) to separate each key from its value. - -- Use a semicolon (;) or a line break to separate the key\/value pairs. - -- Key that contains spaces must be enclosed in quotation marks. Values must be valid Windows PowerShell expressions. Strings must appear in quotation marks, even if they do not include spaces. - +- Enter one or more key/value pairs for the content of the hash table. +- Use an equal sign (=) to separate each key from its value. +- Use a semicolon (;) or a line break to separate the key/value pairs. +- Key that contains spaces must be enclosed in quotation marks. Values must be + valid PowerShell expressions. Strings must appear in quotation marks, even if + they do not include spaces. - To manage the hash table, save it in a variable. - -- When assigning an ordered hash table to a variable, place the [ordered] attribute before the "@" symbol. If you place it before the variable name, the command fails. +- When assigning an ordered hash table to a variable, place the [ordered] + attribute before the "@" symbol. If you place it before the variable name, the + command fails. To create an empty hash table in the value of $hash, type: - -``` +```powershell $hash = @{} ``` +You can also add keys and values to a hash table when you create it. For +example, the following statement creates a hash table with three keys. -You can also add keys and values to a hash table when you create it. For example, the following statement creates a hash table with three keys. - - -``` +```powershell $hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} ``` - - ### Creating Ordered Dictionaries -You can create an ordered dictionary by adding an object of the OrderedDictionary type, but the easiest way to create an ordered dictionary is use the [Ordered] attribute. -The [ordered] attribute is introduced in Windows PowerShell 3.0. +You can create an ordered dictionary by adding an object of the +OrderedDictionary type, but the easiest way to create an ordered dictionary is +use the [Ordered] attribute. -Place the attribute immediately before the "@" symbol. +The [ordered] attribute is introduced in PowerShell 3.0. +Place the attribute immediately before the "@" symbol. -``` +```powershell $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` +You can use ordered dictionaries in the same way that you use hash tables. +Either type can be used as the value of parameters that take a hash table or +dictionary (iDictionary). -You can use ordered dictionaries in the same way that you use hash tables. Either type can be used as the value of parameters that take a hash table or dictionary (iDictionary). - -You cannot use the [ordered] attribute to convert or cast a hash table. If you place the ordered attribute before the variable name, the command fails with the following error message. - +You cannot use the [ordered] attribute to convert or cast a hash table. If you +place the ordered attribute before the variable name, the command fails with +the following error message. -``` -PS C:\> [ordered]$hash = @{} -At line:1 char:1 -+ [ordered]$hash = @{} -+ [!INCLUDE[]()] -The ordered attribute can be specified only on a hash literal node. -+ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException +```powershell +PS C:\> [ordered]$hash = @{} +At line:1 char:1 ++ [ordered]$hash = @{} ++ [!INCLUDE[]()] +The ordered attribute can be specified only on a hash literal node. ++ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordExc +eption + FullyQualifiedErrorId : OrderedAttributeOnlyOnHashLiteralNode ``` - To correct the expression, move the [ordered] attribute. - -``` +```powershell PS C:\> $hash = [ordered]@{} ``` - -You can cast an ordered dictionary to a hash table, but you cannot recover the ordered attribute, even if you clear the variable and enter new values. To re-establish the order, you must remove and recreate the variable. - +You can cast an ordered dictionary to a hash table, but you cannot recover the +ordered attribute, even if you clear the variable and enter new values. To +re-establish the order, you must remove and recreate the variable. ``` -PS C:\> [hashtable]$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} -PS C:\ps-test> $hash - -Name Value ----- ----- -Color Blue -Shape Square +PS C:\> [hashtable]$hash = [ordered]@{ +>> Number = 1; Shape = "Square"; Color = "Blue"} +PS C:\> $hash + +Name Value +---- ----- +Color Blue +Shape Square Number 1 ``` - - ### Displaying Hash Tables -To display a hash table that is saved in a variable, type the variable name. By default, a hash tables is displayed as a table with one column for keys and one for values. +To display a hash table that is saved in a variable, type the variable name. +By default, a hash tables is displayed as a table with one column for keys and +one for values. -``` -C:\PS> $hash - -Name Value ----- ----- -Shape Square -Color Blue +```powershell +C:\PS> $hash + +Name Value +---- ----- +Shape Square +Color Blue Number 1 ``` +Hash tables have Keys and Values properties. Use dot notation to display all +of the keys or all of the values. -Hash tables have Keys and Values properties. Use dot notation to display all of the keys or all of the values. - +```powershell +C:\PS> $hash.keys +Number +Shape +Color -``` -C:\PS> $hash.keys -Number -Shape -Color - -C:\PS> $hash.values -1 -Square +C:\PS> $hash.values +1 +Square Blue ``` +Each key name is also a property of the hash table, and its value is the value +of the key-name property. Use the following format to display the property +values. -Each key name is also a property of the hash table, and its value is the value of the key-name property. Use the following format to display the property values. - - -``` -$hashtable. +```powershell +$hashtable. ``` For example: +```powershell +C:\PS> $hash.Number +1 -``` -C:\PS> $hash.Number -1 - -C:\PS> $hash.Color +C:\PS> $hash.Color Blue ``` - -If the key name collides with one of the property names of the HashTable type, you can use `PSBase` to access those properties. -For example, if the key name is `keys` and you want to return the collection of Keys, use this syntax: +If the key name collides with one of the property names of the HashTable type, +you can use `PSBase` to access those properties. For example, if the key name +is `keys` and you want to return the collection of Keys, use this syntax: ```powershell $hashtable.PSBase.Keys ``` +Hash tables have a Count property that indicates the number of key-value pairs +in the hash table. -Hash tables have a Count property that indicates the number of key-value pairs in the hash table. - - -``` -C:\PS> $hash.count +```powershell +C:\PS> $hash.count 3 ``` - -Hash table tables are not arrays, so you cannot use an integer as an index into the hash table, but you can use a key name to index into the hash table. If the key is a string value, enclose the key name in quotation marks. +Hash table tables are not arrays, so you cannot use an integer as an index +into the hash table, but you can use a key name to index into the hash table. +If the key is a string value, enclose the key name in quotation marks. For example: - -``` -C:\PS> $hash["Number"] +```powershell +C:\PS> $hash["Number"] 1 ``` - - ### Adding and Removing Keys and Values -To add keys and values to a hash table, use the following command format. +To add keys and values to a hash table, use the following command format. -``` +```powershell $hash[""] = "" ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash["Time"] = "Now" ``` +You can also add keys and values to a hash table by using the Add method of +the System.Collections.Hashtable object. The Add method has the following +syntax: -You can also add keys and values to a hash table by using the Add method of the System.Collections.Hashtable object. The Add method has the following syntax: - - -``` +```powershell Add(Key, Value) ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash = $hash.Add("Time", "Now") ``` +And, you can add keys and values to a hash table by using the addition +operator (+) to add a hash table to an existing hash table. For example, the +following statement adds a "Time" key with a value of "Now" to the hash table +in the $hash variable. -And, you can add keys and values to a hash table by using the addition operator (\+) to add a hash table to an existing hash table. For example, the following statement adds a "Time" key with a value of "Now" to the hash table in the $hash variable. - - -``` +```powershell $hash = $hash + @{Time="Now"} ``` - You can also add values that are stored in variables. +```powershell +$t = "Today" +$now = (Get-Date) -``` -$t = "Today" -$now = (Get-Date) - $hash.Add($t, $now) ``` - -You cannot use a subtraction operator to remove a key\/value pair from a hash table, but you can use the Remove method of the Hashtable object. The Remove method takes the key as its value. +You cannot use a subtraction operator to remove a key/value pair from a hash +table, but you can use the Remove method of the Hashtable object. The Remove +method takes the key as its value. The Remove method has the following syntax: - ``` Remove(Key) ``` +For example, to remove the Time=Now key/value pair from the hash table in the +value of the $hash variable, type: -For example, to remove the Time\=Now key\/value pair from the hash table in the value of the $hash variable, type: - - -``` +```powershell $hash.Remove("Time") ``` - -You can use all of the properties and methods of Hashtable objects in Windows PowerShell, including Contains, Clear, Clone, and CopyTo. For more information about Hashtable objects, see [System.Collections.Hashtable](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN. - +You can use all of the properties and methods of Hashtable objects in +PowerShell, including Contains, Clear, Clone, and CopyTo. For more information +about Hashtable objects, see "System.Collections.Hashtable" on MSDN. ### Object Types in HashTables -The keys and values in a hash table can have any .NET object type, and a single hash table can have keys and values of multiple types. -The following statement creates a hash table of process name strings and process object values and saves it in the $p variable. +The keys and values in a hash table can have any .NET object type, and a +single hash table can have keys and values of multiple types. +The following statement creates a hash table of process name strings and +process object values and saves it in the \$p variable. -``` -$p = @{"PowerShell" = (get-process PowerShell); +```powershell +$p = @{"PowerShell" = (get-process PowerShell); "Notepad" = (get-process notepad)} ``` +You can display the hash table in \$p and use the key-name properties to +display the values. -You can display the hash table in $p and use the key-name properties to display the values. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) - -C:\PS> $p.PowerShell - -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName -------- ------ ----- ----- ----- ------ -- ----------- - 441 24 54196 54012 571 5.10 1788 PowerShell - -C:\PS> $p.keys | foreach {$p.$_.handles} -441 -251 -``` +C:\PS> $p.PowerShell +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 441 24 54196 54012 571 5.10 1788 PowerShell -The keys in a hash table can also be any .NET type. The following statement adds a key\/value pair to the hash table in the $p variable. The key is a Service object that represents the WinRM service, and the value is the current status of the service. +C:\PS> $p.keys | foreach {$p.$_.handles} +441 +251 +``` +The keys in a hash table can also be any .NET type. The following statement +adds a key/value pair to the hash table in the \$p variable. The key is a +Service object that represents the WinRM service, and the value is the current +status of the service. -``` +```powershell C:\PS> $p = $p + @{(Get-Service WinRM) = ((Get-Service WinRM).Status)} ``` +You can display and access the new key/value pair by using the same methods +that you use for other pairs in the hash table. -You can display and access the new key\/value pair by using the same methods that you use for other pairs in the hash table. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running - -C:\PS> $p.keys -PowerShell -Notepad - -Status Name DisplayName ------- ---- ----------- -Running winrm Windows Remote Management (WS-Manag... - -C:\PS> $p.keys | foreach {$_.name} -winrm -``` +C:\PS> $p.keys +PowerShell +Notepad +Status Name DisplayName +------ ---- ----------- +Running winrm Windows Remote Management (WS-Manag... -The keys and values in a hash table can also be Hashtable objects. The following statement adds key\/value pair to the hash table in the $p variable in which the key is a string, Hash2, and the value is a hash table with three key\/value pairs. +C:\PS> $p.keys | foreach {$_.name} +winrm +``` +The keys and values in a hash table can also be Hashtable objects. The +following statement adds key/value pair to the hash table in the \$p variable +in which the key is a string, Hash2, and the value is a hash table with three +key/value pairs. -``` +```powershell C:\PS> $p = $p + @{"Hash2"= @{a=1; b=2; c=3}} ``` - You can display and access the new values by using the same methods. +```powershell +C:\PS> $p -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running -Hash2 {a, b, c} - -C:\PS> $p.Hash2 - -Name Value ----- ----- -a 1 -b 2 -c 3 - -C:\PS> $p.Hash2.b -2 -``` +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running +Hash2 {a, b, c} +C:\PS> $p.Hash2 +Name Value +---- ----- +a 1 +b 2 +c 3 + +C:\PS> $p.Hash2.b +2 +``` ### Sorting Keys and Values -The items in a hash table are intrinsically unordered. The key\/value pairs might appear in a different order each time that you display them. -Although you cannot sort a hash table, you can use the GetEnumerator method of hash tables to enumerate the keys and values, and then use the Sort-Object cmdlet to sort the enumerated values for display. +The items in a hash table are intrinsically unordered. The key/value pairs +might appear in a different order each time that you display them. -For example, the following commands enumerate the keys and values in the hash table in the $p variable and then sort the keys in alphabetical order. +Although you cannot sort a hash table, you can use the GetEnumerator method of +hash tables to enumerate the keys and values, and then use the Sort-Object +cmdlet to sort the enumerated values for display. +For example, the following commands enumerate the keys and values in the hash +table in the \$p variable and then sort the keys in alphabetical order. -``` -C:\PS> $p.GetEnumerator() | Sort-Object -Property key - -Name Value ----- ----- -Notepad System.Diagnostics.Process (notepad) -PowerShell System.Diagnostics.Process (PowerShell) +```powershell +C:\PS> $p.GetEnumerator() | Sort-Object -Property key + +Name Value +---- ----- +Notepad System.Diagnostics.Process (notepad) +PowerShell System.Diagnostics.Process (PowerShell) System.ServiceProcess.Servi... Running ``` +The following command uses the same procedure to sort the hash values in +descending order. -The following command uses the same procedure to sort the hash values in descending order. - +```powershell +C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending -``` -C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) System.ServiceProcess.Servi... Running ``` - - ### Creating Objects from Hash Tables -Beginning in Windows PowerShell 3.0, you can create an object from a hash table of properties and property values. -The syntax is as follows: +Beginning in PowerShell 3.0, you can create an object from a hash table of +properties and property values. +The syntax is as follows: -``` -[]@{=;=} +```powershell +[]@{ + = + = +} ``` +This method works only for classes that have a null constructor, that is, a +constructor that has no parameters. The object properties must be public and +settable. -This method works only for classes that have a null constructor, that is, a constructor that has no parameters. The object properties must be public and settable. - -For more information, see [about_Object_Creation](about_Object_Creation.md). - +For more information, see [about_Object_Creation(about_Object_Creation.md)]. ### ConvertFrom-StringData -The ConvertFrom-StringData cmdlet converts a string or a here-string of key\/value pairs into a hash table. You can use the ConvertFrom-StringData cmdlet safely in the Data section of a script, and you can use it with the Import-LocalizedData cmdlet to display user messages in the user-interface (UI) culture of the current user. -Here-strings are especially useful when the values in the hash table include quotation marks. (For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md).) +The `ConvertFrom-StringData` cmdlet converts a string or a here-string of +key/value pairs into a hash table. You can use the `ConvertFrom-StringData` +cmdlet safely in the Data section of a script, and you can use it with the +`Import-LocalizedData` cmdlet to display user messages in the user-interface +(UI) culture of the current user. -The following example shows how to create a here-string of the user messages in the previous example and how to use ConvertFrom-StringData to convert them from a string into a hash table. +Here-strings are especially useful when the values in the hash table include +quotation marks. For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). -The following command creates a here-string of the key\/value pairs and then saves it in the $string variable. +The following example shows how to create a here-string of the user messages +in the previous example and how to use `ConvertFrom-StringData` to convert them +from a string into a hash table. +The following command creates a here-string of the key/value pairs and then +saves it in the \$string variable. -``` -C:\PS> $string = @" -Msg1 = Type "Windows". -Msg2 = She said, "Hello, World." -Msg3 = Enter an alias (or "nickname"). +```powershell +C:\PS> $string = @" +Msg1 = Type "Windows". +Msg2 = She said, "Hello, World." +Msg3 = Enter an alias (or "nickname"). "@ ``` +This command uses the ConvertFrom-StringData cmdlet to convert the here-string +into a hash table. -This command uses the ConvertFrom-StringData cmdlet to convert the here-string into a hash table. - +```powershell +C:\PS> ConvertFrom-StringData $string -``` -C:\PS> ConvertFrom-StringData $string - -Name Value ----- ----- -Msg3 Enter an alias (or "nickname"). -Msg2 She said, "Hello, World." +Name Value +---- ----- +Msg3 Enter an alias (or "nickname"). +Msg2 She said, "Hello, World." Msg1 Type "Windows". ``` - For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). - ## SEE ALSO [about_Arrays](about_Arrays.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_If.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_If.md index bacd41016bfc..43c54fe84cb6 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_If.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_If.md @@ -73,7 +73,8 @@ if ($a -gt 2) { Write-Host "The value $a is greater than 2." } else { - Write-Host "The value $a is less than or equal to 2, is not created or is not initialized." + Write-Host ("The value $a is less than or equal to 2," + + " is not created or is not initialized.") } ``` @@ -89,7 +90,8 @@ elseif ($a -eq 2) { Write-Host "The value $a is equal to 2." } else { - Write-Host "The value $a is less than 2 or was not created or initialized." + Write-Host ("The value $a is less than 2 or" + + " was not created or initialized.") } ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md index 31c9c354fcb4..61ddaa58384e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Job_Details --- # About Job Details -## about_Job_Details - - # SHORT DESCRIPTION @@ -20,7 +17,8 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in Windows PowerShell. -This topic is a supplement to the about_Jobs and about_Remote_Jobs topics. +This topic is a supplement to the [about_Jobs](about_Jobs.md) and +[about_Remote_Jobs](about_Remote_Jobs.md) topics. # ABOUT BACKGROUND JOBS @@ -94,65 +92,71 @@ To get the parent and child jobs of a job, use the IncludeChildJobs parameter of the Get-Job cmdlet. The IncludeChildJob parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -IncludeChildJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the parent job and only the child jobs with a particular State value, use the ChildJobState parameter of the Get-Job cmdlet. The ChildJobState parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -ChildJobState Failed -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the child jobs of a job on all versions of Windows PowerShell, use the ChildJob property of the parent job. +```powershell C:\PS> (Get-Job Job1).ChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` You can also use a Get-Job command on the child job, as shown in the following command: +```powershell C:\PS> Get-Job Job3 -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 Failed False localhost Get-Process +``` The configuration of the child job depends on the command that you use to start the job. --- When you use Start-Job to start a job on a local computer, the job -consists of an executive parent job and a child job that runs the -command. +- When you use Start-Job to start a job on a local computer, the job consists + of an executive parent job and a child job that runs the command. --- When you use the AsJob parameter of Invoke-Command to start a job on -one or more computers, the job consists of an executive parent job -and a child job for each job run on each computer. +- When you use the AsJob parameter of Invoke-Command to start a job on one or + more computers, the job consists of an executive parent job and a child job + for each job run on each computer. --- When you use Invoke-Command to run a Start-Job command on one or more -remote computers, the result is the same as a local command run on -each remote computer. The command returns a job object for each -computer. The job object consists of an executive parent job and -one child job that runs the command. +- When you use Invoke-Command to run a Start-Job command on one or more remote + computers, the result is the same as a local command run on each remote + computer. The command returns a job object for each computer. The job object + consists of an executive parent job and one child job that runs the command. -The parent job represents all of the child jobs. When you manage a parent -job, you also manage the associated child jobs. For example, if you stop a -parent job, all child jobs are stopped. If you get the results of a parent -job, you get the results of all child jobs. +The parent job represents all of the child jobs. When you manage a parent job, +you also manage the associated child jobs. For example, if you stop a parent +job, all child jobs are stopped. If you get the results of a parent job, you +get the results of all child jobs. However, you can also manage child jobs individually. This is most useful when you want to investigate a problem with a job or get the results of @@ -161,49 +165,60 @@ Invoke-Command. (The backtick character [`] is the continuation character.) The following command uses the AsJob parameter of Invoke-Command to start background jobs on the local computer and two remote computers. The command -saves the job in the $j variable. +saves the job in the \$j variable. +```powershell PS C:> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` -Command {Get-Date} -AsJob +``` -When you display the Name and ChildJob properties of the job in $j, it +When you display the Name and ChildJob properties of the job in \$j, it shows that the command returned a job object with three child jobs, one for each computer. +```powershell PS C:> $j | Format-List Name, ChildJobs Name : Job3 ChildJobs : {Job4, Job5, Job6} +``` When you display the parent job, it shows that the job failed. +```powershell C:\PS> $j -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- -3 Job3 RemotingJob Failed False localhost,Server... +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- +3 Job3 RemotingJob Failed False localhost,Server... +``` But when you run a Get-Job command that gets the child jobs, the output shows that only one child job failed. +```powershell PS C:> Get-Job -IncludeChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 RemotingJob Failed False localhost,Server... -4 Job4 Completed True localhost Get-Date -5 Job5 Failed False Server01 Get-Date -6 Job6 Completed True Server02 Get-Date +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 RemotingJob Failed False localhost,Server... +4 Job4 Completed True localhost Get-Date +5 Job5 Failed False Server01 Get-Date +6 Job6 Completed True Server02 Get-Date +``` To get the results of all child jobs, use the Receive-Job cmdlet to get the results of the parent job. But you can also get the results of a particular child job, as shown in the following command. -C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, DateTime -Auto +```powershell +C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, +>> DateTime -Auto ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM +``` The child jobs feature of Windows PowerShell background jobs gives you more control over the jobs that you run. @@ -239,86 +254,100 @@ Get-Job returns indicates the job type. The following table lists the job types that come with Windows PowerShell. -Job Type Description --------- ----------- -BackgroundJob Started by using the Start-Job cmdlet. -RemoteJob Started by using the AsJob parameter of the -Invoke-Command cmdlet. -PSWorkflowJob Started by using the AsJob parameter of a -workflow. -PSScheduledJob An instance of a scheduled job started by -a job trigger. -CIMJob Started by using the AsJob parameter of -a cmdlet from a CDXML module. -WMIJob Started by using the AsJob parameter of -a cmdlet from a WMI module. -PSEventJob Created by running Register-ObjectEvent -and specifying an action with the Action -parameter. - -NOTE: Before using the Get-Job cmdlet to get jobs of a particular -type, verify that the module that adds the job type is imported -into the current session. Otherwise, Get-Job does not get jobs of -that type. +|Job Type |Description | +|--------------|----------------------------------------------------------| +|BackgroundJob |Started by using the Start-Job cmdlet. | +|RemoteJob |Started by using the AsJob parameter of the Invoke-Command| +| |cmdlet. | +|PSWorkflowJob |Started by using the AsJob parameter of a workflow. | +|PSScheduledJob|An instance of a scheduled job started by a job trigger. | +|CIMJob |Started by using the AsJob parameter of a cmdlet from a | +| |CDXML module. | +|WMIJob |Started by using the AsJob parameter of a cmdlet from a | +| |WMI module. | +|PSEventJob |Created by running Register-ObjectEvent and specifying an | +| |action with the Action parameter. | + +NOTE: Before using the Get-Job cmdlet to get jobs of a particular type, verify +that the module that adds the job type is imported into the current session. +Otherwise, Get-Job does not get jobs of that type. # EXAMPLE -The following commands create a local background job, a -remote background job, a workflow job, and a scheduled job. -Then, it uses the Get-Job cmdlet to get the jobs. Get-Job -does not get the scheduled job, but it gets any started +The following commands create a local background job, a remote background job, +a workflow job, and a scheduled job. Then, it uses the Get-Job cmdlet to get +the jobs. `Get-Job` does not get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. + +```powershell PS C:> Start-Job -Name LocalData {Get-Process} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Running True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Running True localhost Get-Process +``` Start a background job that runs on a remote computer. -PS C:> Invoke-Command -ComputerName Server01 {Get-Process} -AsJob -JobName RemoteData -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 RemoteData RemoteJob Running True Server01 Get-Process +```powershell +PS C:> Invoke-Command -ComputerName Server01 {Get-Process} ` +-AsJob -JobName RemoteData + +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 RemoteData RemoteJob Running True Server01 Get-Process +``` Create a scheduled job -PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock {Get-Process} ` --Trigger (New-JobTrigger -Once -At "3 PM") +```powershell +PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` + {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` Create a workflow. +```powershell PS C:> workflow Test-Workflow {Get-Process} +``` Run the workflow as a job. +```powershell + PS C:> Test-Workflow -AsJob -JobName TestWFJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +``` -Get the jobs. The Get-Job command does not get scheduled jobs, but it gets +Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets instances of the scheduled job that are started. +```powershell PS C:> Get-Job -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Completed True localhost Get-Process +4 RemoteData RemoteJob Completed True Server01 Get-Process +6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob +8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +``` To get scheduled jobs, use the Get-ScheduledJob cmdlet. + +```powershell PS C:> Get-ScheduledJob Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` # SEE ALSO @@ -328,31 +357,30 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../PSScheduledJob/About/about_Scheduled_Jobs.md) - -Invoke-Command +[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -Suspend-Job +[Remove-Job](../Remove-Job.md) -Resume-Job +[Suspend-Job](../Remove-Job.md) -New-PSSession +[Resume-Job](../Resume-Job) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Register-ScheduledJob +[Exit-PSSession](../Exit-PSSession.md) -Get-ScheduleJob +[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) +[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md index 170a44e2c7e3..e2cf58d05dc1 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,13 +7,10 @@ title: about_Functions_CmdletBindingAttribute --- # About Functions CmdletBindingAttribute -## about_Functions_CmdletBindingAttribute - # SHORT DESCRIPTION -Describes the attribute that makes a function work like a -compiled cmdlet. +Describes the attribute that makes a function work like a compiled cmdlet. # LONG DESCRIPTION @@ -124,13 +121,15 @@ to an advanced function. function Get-Numbers { [CmdletBinding(SupportsPaging = $true)] param() - + $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100) - $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100) - + $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + + $FirstNumber - 1, 100) + if ($PSCmdlet.PagingParameters.IncludeTotalCount) { $TotalCountAccuracy = 1.0 - $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy) + $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, + $TotalCountAccuracy) Write-Output $TotalCount } $FirstNumber .. $LastNumber | Write-Output @@ -173,8 +172,7 @@ must be included when the parameter is used in a function. The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. You can use the Position argument to specify a position value for a parameter. For more information about the Position -argument, see about_Functions_Advanced_Parameters -(http://go.microsoft.com/fwlink/?LinkID=135173). +argument, see [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). # NOTES diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index 15463e8deb2d..ff4eed688151 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,8 +7,6 @@ title: about_Group_Policy_Settings --- # About Group Policy Settings -## about_Group_Policy_Settings - # SHORT DESCRIPTION @@ -16,28 +14,32 @@ Describes the Group Policy settings for Windows PowerShell # LONG DESCRIPTION - Windows PowerShell includes Group Policy settings to help you define consistent option values for servers in an enterprise environment. The Windows PowerShell Group Policy settings are in the following Group Policy paths: -Computer Configuration\Administrative Templates\Windows Components\Windows PowerShell -User Configuration\Administrative Templates\Windows Components\Windows PowerShell + Computer Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell + + User Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell Group policy settings in the User Configuration path take precedence over Group Policy settings in the Computer Configuration path. The policies are as follows: -Turn on Script Execution: Sets the Windows PowerShell execution -policy. -Turn on Module Logging: Sets the LogPipelineExecutionDetails -property of modules. -Set the default source path for Update-Help: -Sets the source for UpdatableHelp to -a directory, not the Internet. +- Turn on Script Execution: Sets the Windows PowerShell execution policy. +- Turn on Module Logging: Sets the LogPipelineExecutionDetails property of + modules. +- Set the default source path for Update-Help: Sets the source for + UpdatableHelp to a directory, not the Internet. To download spreadsheets that list all of the Group Policy settings for each version of Windows, see "Group Policy Settings Reference for Windows @@ -53,28 +55,27 @@ run. If you enable the policy setting, you can select from among the following policy settings. --- "Allow only signed scripts" allows scripts to execute only if they -are signed by a trusted publisher. This policy setting is equivalent -to the AllSigned execution policy. +- "Allow only signed scripts" allows scripts to execute only if they are + signed by a trusted publisher. This policy setting is equivalent to the + AllSigned execution policy. --- "Allow local scripts and remote signed scripts" allows all local -scripts to run. Scripts that originate from the Internet must be -signed by a trusted publisher. This policy setting is equivalent -to the RemoteSigned execution policy. +- "Allow local scripts and remote signed scripts" allows all local scripts to + run. Scripts that originate from the Internet must be signed by a trusted + publisher. This policy setting is equivalent to the RemoteSigned execution + policy. --- "Allow all scripts" allows all scripts to run. This policy -setting is equivalent to the Unrestricted execution policy. +- "Allow all scripts" allows all scripts to run. This policy setting is + equivalent to the Unrestricted execution policy. -If you disable this policy setting, no scripts are allowed to run. -This policy setting is equivalent to the Restricted execution policy. +If you disable this policy setting, no scripts are allowed to run. This policy +setting is equivalent to the Restricted execution policy. -If you disable or do not configure this policy setting, the execution -policy that is set for the computer or user by the Set-ExecutionPolicy -cmdlet determines whether scripts are permitted to run. The default -value is Restricted. +If you disable or do not configure this policy setting, the execution policy +that is set for the computer or user by the Set-ExecutionPolicy cmdlet +determines whether scripts are permitted to run. The default value is +Restricted. -For more information, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](about_Execution_Policies.md). # TURN ON MODULE LOGGING @@ -99,56 +100,54 @@ To turn on module logging for a module, use the following command format. The module must be imported into the session and the setting is effective only in the current session. +```powershell PS C:> Import-Module PS C:> (Get-Module ).LogPipelineExecutionDetails = $true +``` To turn on module logging for all sessions on a particular computer, add the previous commands to the all-users Windows PowerShell profile ($Profile.AllUsers.AllHosts). -For more information about module logging, see about_Modules -(http://go.microsoft.com/fwlink/?LinkID=144311). +For more information about module logging, see [about_Modules](about_Modules.md). # SET THE DEFAULT SOURCE PATH FOR UPDATE-HELP The "Set the Default Source Path for Update-Help" policy setting sets a -default value for the SourcePath parameter of the Update-Help cmdlet. -This setting prevents users from using the Update-Help cmdlet to download -help files from the Internet. +default value for the SourcePath parameter of the Update-Help cmdlet. This +setting prevents users from using the Update-Help cmdlet to download help +files from the Internet. -NOTE: The "Set the default source path for Update-Help" Group -Policy setting appears under Computer Configuration and -User Configuration. However, only the Group Policy setting -under Computer Configuration is effective. The Group Policy -setting under User Configuration is ignored. +NOTE: The "Set the default source path for Update-Help" Group Policy setting +appears under Computer Configuration and User Configuration. However, only the +Group Policy setting under Computer Configuration is effective. The Group +Policy setting under User Configuration is ignored. The Update-Help cmdlet downloads and installs the newest help files for Windows PowerShell modules and installs them on the computer. By default, -Update-Help downloads new help files from an Internet location specified -by the module. +Update-Help downloads new help files from an Internet location specified by +the module. -However, you can use the Save-Help cmdlet to download the newest help -files to a file system location, such as a network share, and then use -the Update-Help cmdlet to get the help files from the file system -location and install them on the computer. The SourcePath parameter of -the Update-Help cmdlet specifies the file system location. +However, you can use the Save-Help cmdlet to download the newest help files to +a file system location, such as a network share, and then use the Update-Help +cmdlet to get the help files from the file system location and install them on +the computer. The SourcePath parameter of the Update-Help cmdlet specifies the +file system location. -By providing a default value for the SourcePath parameter, this Group -Policy setting implicitly adds the SourcePath parameter to all Update-Help -commands. Users can override the particular file system location specified -as the default value by entering a different file system location. But they -cannot remove the SourcePath parameter from the Update-Help command. +By providing a default value for the SourcePath parameter, this Group Policy +setting implicitly adds the SourcePath parameter to all Update-Help commands. +Users can override the particular file system location specified as the +default value by entering a different file system location. But they cannot +remove the SourcePath parameter from the Update-Help command. If you enable this policy setting, you can specify a default value for the SourcePath parameter. Enter a file system location. -If this policy setting is disabled or not configured, there is no -default value for the SourcePath parameter of the Update-Help cmdlet. -Users can download help from the Internet or from any file system -location. +If this policy setting is disabled or not configured, there is no default +value for the SourcePath parameter of the `Update-Help` cmdlet. Users can +download help from the Internet or from any file system location. -For more information, see about_Updatable_Help -(http://go.microsoft.com/fwlink/?LinkID=235801). +For more information, see [about_Updatable_Help](about_Updatable_Help.md). # KEYWORDS @@ -163,13 +162,12 @@ about_GroupPolicy [about_Updatable_Help](about_Updatable_Help.md) -Get-ExecutionPolicy - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Get-Module +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -Update-Help +[Get-Module](../Get-Module.md) -Save-Help +[Update-Help](../Update-Help.md) +[Save-Help](../../Save-Help.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 4e1214891b13..174cf4dd2d6a 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,477 +7,483 @@ title: about_Hash_Tables --- # About Hash Tables -## about_Hash_Tables - ## SHORT DESCRIPTION -Describes how to create, use, and sort hash tables in Windows PowerShell. +Describes how to create, use, and sort hash tables in PowerShell. ## LONG DESCRIPTION -A hash table, also known as a dictionary or associative array, is a compact data structure that stores one or more key\/value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In Windows PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) object. You can use the properties and methods of Hashtable objects in Windows PowerShell. +A hash table, also known as a dictionary or associative array, is a compact +data structure that stores one or more key/value pairs. For example, a hash +table might contain a series of IP addresses and computer names, where the IP +addresses are the keys and the computer names are the values, or vice versa. -Beginning in Windows PowerShell 3.0, you can use the [ordered] attribute to create an ordered dictionary (System.Collections.Specialized.OrderedDictionary) in Windows PowerShell. +In PowerShell, each hash table is a Hashtable (System.Collections.Hashtable) +object. You can use the properties and methods of Hashtable objects in +PowerShell. -Ordered dictionaries differ from hash tables in that the keys always appear in the order in which you list them. The order of keys in a hash table is not determined. +Beginning in PowerShell 3.0, you can use the [ordered] attribute to create an +ordered dictionary (System.Collections.Specialized.OrderedDictionary) in +PowerShell. -The keys and value in hash tables are also .NET objects. They are most often strings or integers, but they can have any object type. You can also create nested hash tables, in which the value of a key is another hash table. +Ordered dictionaries differ from hash tables in that the keys always appear in +the order in which you list them. The order of keys in a hash table is not +determined. -Hash tables are frequently used because they are very efficient for finding and retrieving data. You can use hash tables to store lists and to create calculated properties in Windows PowerShell. And, Windows PowerShell has a cmdlet, ConvertFrom-StringData, that converts strings to a hash table. +The keys and value in hash tables are also .NET objects. They are most often +strings or integers, but they can have any object type. You can also create +nested hash tables, in which the value of a key is another hash table. +Hash tables are frequently used because they are very efficient for finding +and retrieving data. You can use hash tables to store lists and to create +calculated properties in PowerShell. And, PowerShell has a cmdlet, +ConvertFrom-StringData, that converts strings to a hash table. ### Syntax -The syntax of a hash table is as follows: +The syntax of a hash table is as follows: -``` +```powershell @{ = ; [ = ] ...} ``` - The syntax of an ordered dictionary is as follows: - -``` +```powershell [ordered]@{ = ; [ = ] ...} ``` - -The [ordered] attribute was introduced in Windows PowerShell 3.0. - +The [ordered] attribute was introduced in PowerShell 3.0. ### Creating Hash Tables + To create a hash table, follow these guidelines: - Begin the hash table with an at sign (@). - - Enclose the hash table in braces ({}). - -- Enter one or more key\/value pairs for the content of the hash table. - -- Use an equal sign (\=) to separate each key from its value. - -- Use a semicolon (;) or a line break to separate the key\/value pairs. - -- Key that contains spaces must be enclosed in quotation marks. Values must be valid Windows PowerShell expressions. Strings must appear in quotation marks, even if they do not include spaces. - +- Enter one or more key/value pairs for the content of the hash table. +- Use an equal sign (=) to separate each key from its value. +- Use a semicolon (;) or a line break to separate the key/value pairs. +- Key that contains spaces must be enclosed in quotation marks. Values must be + valid PowerShell expressions. Strings must appear in quotation marks, even if + they do not include spaces. - To manage the hash table, save it in a variable. - -- When assigning an ordered hash table to a variable, place the [ordered] attribute before the "@" symbol. If you place it before the variable name, the command fails. +- When assigning an ordered hash table to a variable, place the [ordered] + attribute before the "@" symbol. If you place it before the variable name, the + command fails. To create an empty hash table in the value of $hash, type: - -``` +```powershell $hash = @{} ``` +You can also add keys and values to a hash table when you create it. For +example, the following statement creates a hash table with three keys. -You can also add keys and values to a hash table when you create it. For example, the following statement creates a hash table with three keys. - - -``` +```powershell $hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} ``` - - ### Creating Ordered Dictionaries -You can create an ordered dictionary by adding an object of the OrderedDictionary type, but the easiest way to create an ordered dictionary is use the [Ordered] attribute. -The [ordered] attribute is introduced in Windows PowerShell 3.0. +You can create an ordered dictionary by adding an object of the +OrderedDictionary type, but the easiest way to create an ordered dictionary is +use the [Ordered] attribute. -Place the attribute immediately before the "@" symbol. +The [ordered] attribute is introduced in PowerShell 3.0. +Place the attribute immediately before the "@" symbol. -``` +```powershell $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` +You can use ordered dictionaries in the same way that you use hash tables. +Either type can be used as the value of parameters that take a hash table or +dictionary (iDictionary). -You can use ordered dictionaries in the same way that you use hash tables. Either type can be used as the value of parameters that take a hash table or dictionary (iDictionary). - -You cannot use the [ordered] attribute to convert or cast a hash table. If you place the ordered attribute before the variable name, the command fails with the following error message. - +You cannot use the [ordered] attribute to convert or cast a hash table. If you +place the ordered attribute before the variable name, the command fails with +the following error message. -``` -PS C:\> [ordered]$hash = @{} -At line:1 char:1 -+ [ordered]$hash = @{} -+ [!INCLUDE[]()] -The ordered attribute can be specified only on a hash literal node. -+ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException +```powershell +PS C:\> [ordered]$hash = @{} +At line:1 char:1 ++ [ordered]$hash = @{} ++ [!INCLUDE[]()] +The ordered attribute can be specified only on a hash literal node. ++ CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordExc +eption + FullyQualifiedErrorId : OrderedAttributeOnlyOnHashLiteralNode ``` - To correct the expression, move the [ordered] attribute. - -``` +```powershell PS C:\> $hash = [ordered]@{} ``` - -You can cast an ordered dictionary to a hash table, but you cannot recover the ordered attribute, even if you clear the variable and enter new values. To re-establish the order, you must remove and recreate the variable. - +You can cast an ordered dictionary to a hash table, but you cannot recover the +ordered attribute, even if you clear the variable and enter new values. To +re-establish the order, you must remove and recreate the variable. ``` -PS C:\> [hashtable]$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} -PS C:\ps-test> $hash - -Name Value ----- ----- -Color Blue -Shape Square +PS C:\> [hashtable]$hash = [ordered]@{ +>> Number = 1; Shape = "Square"; Color = "Blue"} +PS C:\> $hash + +Name Value +---- ----- +Color Blue +Shape Square Number 1 ``` - - ### Displaying Hash Tables -To display a hash table that is saved in a variable, type the variable name. By default, a hash tables is displayed as a table with one column for keys and one for values. +To display a hash table that is saved in a variable, type the variable name. +By default, a hash tables is displayed as a table with one column for keys and +one for values. -``` -C:\PS> $hash - -Name Value ----- ----- -Shape Square -Color Blue +```powershell +C:\PS> $hash + +Name Value +---- ----- +Shape Square +Color Blue Number 1 ``` +Hash tables have Keys and Values properties. Use dot notation to display all +of the keys or all of the values. -Hash tables have Keys and Values properties. Use dot notation to display all of the keys or all of the values. - +```powershell +C:\PS> $hash.keys +Number +Shape +Color -``` -C:\PS> $hash.keys -Number -Shape -Color - -C:\PS> $hash.values -1 -Square +C:\PS> $hash.values +1 +Square Blue ``` +Each key name is also a property of the hash table, and its value is the value +of the key-name property. Use the following format to display the property +values. -Each key name is also a property of the hash table, and its value is the value of the key-name property. Use the following format to display the property values. - - -``` -$hashtable. +```powershell +$hashtable. ``` For example: +```powershell +C:\PS> $hash.Number +1 -``` -C:\PS> $hash.Number -1 - -C:\PS> $hash.Color +C:\PS> $hash.Color Blue ``` - -If the key name collides with one of the property names of the HashTable type, you can use `PSBase` to access those properties. -For example, if the key name is `keys` and you want to return the collection of Keys, use this syntax: +If the key name collides with one of the property names of the HashTable type, +you can use `PSBase` to access those properties. For example, if the key name +is `keys` and you want to return the collection of Keys, use this syntax: ```powershell $hashtable.PSBase.Keys ``` +Hash tables have a Count property that indicates the number of key-value pairs +in the hash table. -Hash tables have a Count property that indicates the number of key-value pairs in the hash table. - - -``` -C:\PS> $hash.count +```powershell +C:\PS> $hash.count 3 ``` - -Hash table tables are not arrays, so you cannot use an integer as an index into the hash table, but you can use a key name to index into the hash table. If the key is a string value, enclose the key name in quotation marks. +Hash table tables are not arrays, so you cannot use an integer as an index +into the hash table, but you can use a key name to index into the hash table. +If the key is a string value, enclose the key name in quotation marks. For example: - -``` -C:\PS> $hash["Number"] +```powershell +C:\PS> $hash["Number"] 1 ``` - - ### Adding and Removing Keys and Values -To add keys and values to a hash table, use the following command format. +To add keys and values to a hash table, use the following command format. -``` +```powershell $hash[""] = "" ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash["Time"] = "Now" ``` +You can also add keys and values to a hash table by using the Add method of +the System.Collections.Hashtable object. The Add method has the following +syntax: -You can also add keys and values to a hash table by using the Add method of the System.Collections.Hashtable object. The Add method has the following syntax: - - -``` +```powershell Add(Key, Value) ``` +For example, to add a "Time" key with a value of "Now" to the hash table, use +the following statement format. -For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. - - -``` +```powershell $hash = $hash.Add("Time", "Now") ``` +And, you can add keys and values to a hash table by using the addition +operator (+) to add a hash table to an existing hash table. For example, the +following statement adds a "Time" key with a value of "Now" to the hash table +in the $hash variable. -And, you can add keys and values to a hash table by using the addition operator (\+) to add a hash table to an existing hash table. For example, the following statement adds a "Time" key with a value of "Now" to the hash table in the $hash variable. - - -``` +```powershell $hash = $hash + @{Time="Now"} ``` - You can also add values that are stored in variables. +```powershell +$t = "Today" +$now = (Get-Date) -``` -$t = "Today" -$now = (Get-Date) - $hash.Add($t, $now) ``` - -You cannot use a subtraction operator to remove a key\/value pair from a hash table, but you can use the Remove method of the Hashtable object. The Remove method takes the key as its value. +You cannot use a subtraction operator to remove a key/value pair from a hash +table, but you can use the Remove method of the Hashtable object. The Remove +method takes the key as its value. The Remove method has the following syntax: - ``` Remove(Key) ``` +For example, to remove the Time=Now key/value pair from the hash table in the +value of the $hash variable, type: -For example, to remove the Time\=Now key\/value pair from the hash table in the value of the $hash variable, type: - - -``` +```powershell $hash.Remove("Time") ``` - -You can use all of the properties and methods of Hashtable objects in Windows PowerShell, including Contains, Clear, Clone, and CopyTo. For more information about Hashtable objects, see "System.Collections.Hashtable" on MSDN. - +You can use all of the properties and methods of Hashtable objects in +PowerShell, including Contains, Clear, Clone, and CopyTo. For more information +about Hashtable objects, see "System.Collections.Hashtable" on MSDN. ### Object Types in HashTables -The keys and values in a hash table can have any .NET object type, and a single hash table can have keys and values of multiple types. -The following statement creates a hash table of process name strings and process object values and saves it in the $p variable. +The keys and values in a hash table can have any .NET object type, and a +single hash table can have keys and values of multiple types. +The following statement creates a hash table of process name strings and +process object values and saves it in the \$p variable. -``` -$p = @{"PowerShell" = (get-process PowerShell); +```powershell +$p = @{"PowerShell" = (get-process PowerShell); "Notepad" = (get-process notepad)} ``` +You can display the hash table in \$p and use the key-name properties to +display the values. -You can display the hash table in $p and use the key-name properties to display the values. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) - -C:\PS> $p.PowerShell - -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName -------- ------ ----- ----- ----- ------ -- ----------- - 441 24 54196 54012 571 5.10 1788 PowerShell - -C:\PS> $p.keys | foreach {$p.$_.handles} -441 -251 -``` +C:\PS> $p.PowerShell +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 441 24 54196 54012 571 5.10 1788 PowerShell -The keys in a hash table can also be any .NET type. The following statement adds a key\/value pair to the hash table in the $p variable. The key is a Service object that represents the WinRM service, and the value is the current status of the service. +C:\PS> $p.keys | foreach {$p.$_.handles} +441 +251 +``` +The keys in a hash table can also be any .NET type. The following statement +adds a key/value pair to the hash table in the \$p variable. The key is a +Service object that represents the WinRM service, and the value is the current +status of the service. -``` +```powershell C:\PS> $p = $p + @{(Get-Service WinRM) = ((Get-Service WinRM).Status)} ``` +You can display and access the new key/value pair by using the same methods +that you use for other pairs in the hash table. -You can display and access the new key\/value pair by using the same methods that you use for other pairs in the hash table. +```powershell +C:\PS> $p +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running - -C:\PS> $p.keys -PowerShell -Notepad - -Status Name DisplayName ------- ---- ----------- -Running winrm Windows Remote Management (WS-Manag... - -C:\PS> $p.keys | foreach {$_.name} -winrm -``` +C:\PS> $p.keys +PowerShell +Notepad +Status Name DisplayName +------ ---- ----------- +Running winrm Windows Remote Management (WS-Manag... -The keys and values in a hash table can also be Hashtable objects. The following statement adds key\/value pair to the hash table in the $p variable in which the key is a string, Hash2, and the value is a hash table with three key\/value pairs. +C:\PS> $p.keys | foreach {$_.name} +winrm +``` +The keys and values in a hash table can also be Hashtable objects. The +following statement adds key/value pair to the hash table in the \$p variable +in which the key is a string, Hash2, and the value is a hash table with three +key/value pairs. -``` +```powershell C:\PS> $p = $p + @{"Hash2"= @{a=1; b=2; c=3}} ``` - You can display and access the new values by using the same methods. +```powershell +C:\PS> $p -``` -C:\PS> $p - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) -System.ServiceProcess.Servi... Running -Hash2 {a, b, c} - -C:\PS> $p.Hash2 - -Name Value ----- ----- -a 1 -b 2 -c 3 - -C:\PS> $p.Hash2.b -2 -``` +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) +System.ServiceProcess.Servi... Running +Hash2 {a, b, c} +C:\PS> $p.Hash2 +Name Value +---- ----- +a 1 +b 2 +c 3 + +C:\PS> $p.Hash2.b +2 +``` ### Sorting Keys and Values -The items in a hash table are intrinsically unordered. The key\/value pairs might appear in a different order each time that you display them. -Although you cannot sort a hash table, you can use the GetEnumerator method of hash tables to enumerate the keys and values, and then use the Sort-Object cmdlet to sort the enumerated values for display. +The items in a hash table are intrinsically unordered. The key/value pairs +might appear in a different order each time that you display them. -For example, the following commands enumerate the keys and values in the hash table in the $p variable and then sort the keys in alphabetical order. +Although you cannot sort a hash table, you can use the GetEnumerator method of +hash tables to enumerate the keys and values, and then use the Sort-Object +cmdlet to sort the enumerated values for display. +For example, the following commands enumerate the keys and values in the hash +table in the \$p variable and then sort the keys in alphabetical order. -``` -C:\PS> $p.GetEnumerator() | Sort-Object -Property key - -Name Value ----- ----- -Notepad System.Diagnostics.Process (notepad) -PowerShell System.Diagnostics.Process (PowerShell) +```powershell +C:\PS> $p.GetEnumerator() | Sort-Object -Property key + +Name Value +---- ----- +Notepad System.Diagnostics.Process (notepad) +PowerShell System.Diagnostics.Process (PowerShell) System.ServiceProcess.Servi... Running ``` +The following command uses the same procedure to sort the hash values in +descending order. -The following command uses the same procedure to sort the hash values in descending order. - +```powershell +C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending -``` -C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending - -Name Value ----- ----- -PowerShell System.Diagnostics.Process (PowerShell) -Notepad System.Diagnostics.Process (notepad) +Name Value +---- ----- +PowerShell System.Diagnostics.Process (PowerShell) +Notepad System.Diagnostics.Process (notepad) System.ServiceProcess.Servi... Running ``` - - ### Creating Objects from Hash Tables -Beginning in Windows PowerShell 3.0, you can create an object from a hash table of properties and property values. -The syntax is as follows: +Beginning in PowerShell 3.0, you can create an object from a hash table of +properties and property values. +The syntax is as follows: -``` -[]@{=;=} +```powershell +[]@{ + = + = +} ``` +This method works only for classes that have a null constructor, that is, a +constructor that has no parameters. The object properties must be public and +settable. -This method works only for classes that have a null constructor, that is, a constructor that has no parameters. The object properties must be public and settable. - -For more information, see about_Object_Creation. - +For more information, see [about_Object_Creation(about_Object_Creation.md)]. ### ConvertFrom-StringData -The ConvertFrom-StringData cmdlet converts a string or a here-string of key\/value pairs into a hash table. You can use the ConvertFrom-StringData cmdlet safely in the Data section of a script, and you can use it with the Import-LocalizedData cmdlet to display user messages in the user-interface (UI) culture of the current user. -Here-strings are especially useful when the values in the hash table include quotation marks. (For more information about here-strings, see about_Quoting_Rules.) +The `ConvertFrom-StringData` cmdlet converts a string or a here-string of +key/value pairs into a hash table. You can use the `ConvertFrom-StringData` +cmdlet safely in the Data section of a script, and you can use it with the +`Import-LocalizedData` cmdlet to display user messages in the user-interface +(UI) culture of the current user. -The following example shows how to create a here-string of the user messages in the previous example and how to use ConvertFrom-StringData to convert them from a string into a hash table. +Here-strings are especially useful when the values in the hash table include +quotation marks. For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). -The following command creates a here-string of the key\/value pairs and then saves it in the $string variable. +The following example shows how to create a here-string of the user messages +in the previous example and how to use `ConvertFrom-StringData` to convert them +from a string into a hash table. +The following command creates a here-string of the key/value pairs and then +saves it in the \$string variable. -``` -C:\PS> $string = @" -Msg1 = Type "Windows". -Msg2 = She said, "Hello, World." -Msg3 = Enter an alias (or "nickname"). +```powershell +C:\PS> $string = @" +Msg1 = Type "Windows". +Msg2 = She said, "Hello, World." +Msg3 = Enter an alias (or "nickname"). "@ ``` +This command uses the ConvertFrom-StringData cmdlet to convert the here-string +into a hash table. -This command uses the ConvertFrom-StringData cmdlet to convert the here-string into a hash table. - +```powershell +C:\PS> ConvertFrom-StringData $string -``` -C:\PS> ConvertFrom-StringData $string - -Name Value ----- ----- -Msg3 Enter an alias (or "nickname"). -Msg2 She said, "Hello, World." +Name Value +---- ----- +Msg3 Enter an alias (or "nickname"). +Msg2 She said, "Hello, World." Msg1 Type "Windows". ``` - -For more information about here-strings, see about_Quoting_Rules. - +For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). ## SEE ALSO @@ -489,9 +495,9 @@ For more information about here-strings, see about_Quoting_Rules. [about_Script_Internationalization](about_Script_Internationalization.md) -ConvertFrom-StringData +[ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) -Import-LocalizedData +[Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) -"System.Collections.Hashtable" on MSDN +[System.Collections.Hashtable](http://msdn.microsoft.com/en-us/library/system.collections.hashtable\(v=vs.110\).aspx) on MSDN diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_If.md b/reference/6/Microsoft.PowerShell.Core/About/about_If.md index bacd41016bfc..43c54fe84cb6 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_If.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_If.md @@ -73,7 +73,8 @@ if ($a -gt 2) { Write-Host "The value $a is greater than 2." } else { - Write-Host "The value $a is less than or equal to 2, is not created or is not initialized." + Write-Host ("The value $a is less than or equal to 2," + + " is not created or is not initialized.") } ``` @@ -89,7 +90,8 @@ elseif ($a -eq 2) { Write-Host "The value $a is equal to 2." } else { - Write-Host "The value $a is less than 2 or was not created or initialized." + Write-Host ("The value $a is less than 2 or" + + " was not created or initialized.") } ``` diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md index 0eec4f86dc06..61ddaa58384e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Job_Details --- # About Job Details -## about_Job_Details - - # SHORT DESCRIPTION @@ -20,7 +17,8 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in Windows PowerShell. -This topic is a supplement to the about_Jobs and about_Remote_Jobs topics. +This topic is a supplement to the [about_Jobs](about_Jobs.md) and +[about_Remote_Jobs](about_Remote_Jobs.md) topics. # ABOUT BACKGROUND JOBS @@ -94,65 +92,71 @@ To get the parent and child jobs of a job, use the IncludeChildJobs parameter of the Get-Job cmdlet. The IncludeChildJob parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -IncludeChildJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the parent job and only the child jobs with a particular State value, use the ChildJobState parameter of the Get-Job cmdlet. The ChildJobState parameter is introduced in Windows PowerShell 3.0. +```powershell C:\PS> Get-Job -ChildJobState Failed -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 RemoteJob Failed True localhost Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 RemoteJob Failed True localhost Get-Process +3 Job3 Failed False localhost Get-Process +``` To get the child jobs of a job on all versions of Windows PowerShell, use the ChildJob property of the parent job. +```powershell C:\PS> (Get-Job Job1).ChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 Job2 Completed True Server01 Get-Process -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 Job2 Completed True Server01 Get-Process +3 Job3 Failed False localhost Get-Process +``` You can also use a Get-Job command on the child job, as shown in the following command: +```powershell C:\PS> Get-Job Job3 -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 Failed False localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 Failed False localhost Get-Process +``` The configuration of the child job depends on the command that you use to start the job. --- When you use Start-Job to start a job on a local computer, the job -consists of an executive parent job and a child job that runs the -command. +- When you use Start-Job to start a job on a local computer, the job consists + of an executive parent job and a child job that runs the command. --- When you use the AsJob parameter of Invoke-Command to start a job on -one or more computers, the job consists of an executive parent job -and a child job for each job run on each computer. +- When you use the AsJob parameter of Invoke-Command to start a job on one or + more computers, the job consists of an executive parent job and a child job + for each job run on each computer. --- When you use Invoke-Command to run a Start-Job command on one or more -remote computers, the result is the same as a local command run on -each remote computer. The command returns a job object for each -computer. The job object consists of an executive parent job and -one child job that runs the command. +- When you use Invoke-Command to run a Start-Job command on one or more remote + computers, the result is the same as a local command run on each remote + computer. The command returns a job object for each computer. The job object + consists of an executive parent job and one child job that runs the command. -The parent job represents all of the child jobs. When you manage a parent -job, you also manage the associated child jobs. For example, if you stop a -parent job, all child jobs are stopped. If you get the results of a parent -job, you get the results of all child jobs. +The parent job represents all of the child jobs. When you manage a parent job, +you also manage the associated child jobs. For example, if you stop a parent +job, all child jobs are stopped. If you get the results of a parent job, you +get the results of all child jobs. However, you can also manage child jobs individually. This is most useful when you want to investigate a problem with a job or get the results of @@ -161,49 +165,60 @@ Invoke-Command. (The backtick character [`] is the continuation character.) The following command uses the AsJob parameter of Invoke-Command to start background jobs on the local computer and two remote computers. The command -saves the job in the $j variable. +saves the job in the \$j variable. +```powershell PS C:> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` -Command {Get-Date} -AsJob +``` -When you display the Name and ChildJob properties of the job in $j, it +When you display the Name and ChildJob properties of the job in \$j, it shows that the command returned a job object with three child jobs, one for each computer. +```powershell PS C:> $j | Format-List Name, ChildJobs Name : Job3 ChildJobs : {Job4, Job5, Job6} +``` When you display the parent job, it shows that the job failed. +```powershell C:\PS> $j -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- -3 Job3 RemotingJob Failed False localhost,Server... +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- +3 Job3 RemotingJob Failed False localhost,Server... +``` But when you run a Get-Job command that gets the child jobs, the output shows that only one child job failed. +```powershell PS C:> Get-Job -IncludeChildJobs -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -3 Job3 RemotingJob Failed False localhost,Server... -4 Job4 Completed True localhost Get-Date -5 Job5 Failed False Server01 Get-Date -6 Job6 Completed True Server02 Get-Date +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +3 Job3 RemotingJob Failed False localhost,Server... +4 Job4 Completed True localhost Get-Date +5 Job5 Failed False Server01 Get-Date +6 Job6 Completed True Server02 Get-Date +``` To get the results of all child jobs, use the Receive-Job cmdlet to get the results of the parent job. But you can also get the results of a particular child job, as shown in the following command. -C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, DateTime -Auto +```powershell +C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, +>> DateTime -Auto ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM +``` The child jobs feature of Windows PowerShell background jobs gives you more control over the jobs that you run. @@ -239,86 +254,100 @@ Get-Job returns indicates the job type. The following table lists the job types that come with Windows PowerShell. -Job Type Description --------- ----------- -BackgroundJob Started by using the Start-Job cmdlet. -RemoteJob Started by using the AsJob parameter of the -Invoke-Command cmdlet. -PSWorkflowJob Started by using the AsJob parameter of a -workflow. -PSScheduledJob An instance of a scheduled job started by -a job trigger. -CIMJob Started by using the AsJob parameter of -a cmdlet from a CDXML module. -WMIJob Started by using the AsJob parameter of -a cmdlet from a WMI module. -PSEventJob Created by running Register-ObjectEvent -and specifying an action with the Action -parameter. - -NOTE: Before using the Get-Job cmdlet to get jobs of a particular -type, verify that the module that adds the job type is imported -into the current session. Otherwise, Get-Job does not get jobs of -that type. +|Job Type |Description | +|--------------|----------------------------------------------------------| +|BackgroundJob |Started by using the Start-Job cmdlet. | +|RemoteJob |Started by using the AsJob parameter of the Invoke-Command| +| |cmdlet. | +|PSWorkflowJob |Started by using the AsJob parameter of a workflow. | +|PSScheduledJob|An instance of a scheduled job started by a job trigger. | +|CIMJob |Started by using the AsJob parameter of a cmdlet from a | +| |CDXML module. | +|WMIJob |Started by using the AsJob parameter of a cmdlet from a | +| |WMI module. | +|PSEventJob |Created by running Register-ObjectEvent and specifying an | +| |action with the Action parameter. | + +NOTE: Before using the Get-Job cmdlet to get jobs of a particular type, verify +that the module that adds the job type is imported into the current session. +Otherwise, Get-Job does not get jobs of that type. # EXAMPLE -The following commands create a local background job, a -remote background job, a workflow job, and a scheduled job. -Then, it uses the Get-Job cmdlet to get the jobs. Get-Job -does not get the scheduled job, but it gets any started +The following commands create a local background job, a remote background job, +a workflow job, and a scheduled job. Then, it uses the Get-Job cmdlet to get +the jobs. `Get-Job` does not get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. + +```powershell PS C:> Start-Job -Name LocalData {Get-Process} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Running True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Running True localhost Get-Process +``` Start a background job that runs on a remote computer. -PS C:> Invoke-Command -ComputerName Server01 {Get-Process} -AsJob -JobName RemoteData -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 RemoteData RemoteJob Running True Server01 Get-Process +```powershell +PS C:> Invoke-Command -ComputerName Server01 {Get-Process} ` +-AsJob -JobName RemoteData + +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 RemoteData RemoteJob Running True Server01 Get-Process +``` Create a scheduled job -PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock {Get-Process} ` --Trigger (New-JobTrigger -Once -At "3 PM") +```powershell +PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` + {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` Create a workflow. +```powershell PS C:> workflow Test-Workflow {Get-Process} +``` Run the workflow as a job. +```powershell + PS C:> Test-Workflow -AsJob -JobName TestWFJob -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process +``` -Get the jobs. The Get-Job command does not get scheduled jobs, but it gets +Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets instances of the scheduled job that are started. +```powershell PS C:> Get-Job -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +2 LocalData BackgroundJob Completed True localhost Get-Process +4 RemoteData RemoteJob Completed True Server01 Get-Process +6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob +8 ScheduledJob PSScheduledJob Completed True localhost Get-Process +``` To get scheduled jobs, use the Get-ScheduledJob cmdlet. + +```powershell PS C:> Get-ScheduledJob Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True +``` # SEE ALSO @@ -330,29 +359,28 @@ Id Name JobTriggers Command Enabled [about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) -Invoke-Command - -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -Suspend-Job +[Remove-Job](../Remove-Job.md) -Resume-Job +[Suspend-Job](../Remove-Job.md) -New-PSSession +[Resume-Job](../Resume-Job) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Register-ScheduledJob +[Exit-PSSession](../Exit-PSSession.md) -Get-ScheduleJob +[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) +[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) From 7463af34b9230fa2f995d68465811d9b52ce6674 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 29 Nov 2017 10:15:22 -0800 Subject: [PATCH 2/5] reformatting About_* part 3 --- .../About/about_Jobs.md | 287 +++++++------- .../About/about_Methods.md | 218 ++++++----- .../About/about_Modules.md | 350 +++++++++--------- .../About/about_Jobs.md | 287 +++++++------- .../About/about_Methods.md | 218 ++++++----- .../About/about_Modules.md | 350 +++++++++--------- .../About/about_Jobs.md | 287 +++++++------- .../About/about_Methods.md | 218 ++++++----- .../About/about_Modules.md | 350 +++++++++--------- .../About/about_Jobs.md | 287 +++++++------- .../About/about_Methods.md | 218 ++++++----- .../About/about_Modules.md | 350 +++++++++--------- .../About/about_Jobs.md | 287 +++++++------- .../About/about_Methods.md | 218 ++++++----- .../About/about_Modules.md | 350 +++++++++--------- 15 files changed, 2210 insertions(+), 2065 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md index 2791902df4b1..c90d48ee71a1 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,49 +7,41 @@ title: about_Jobs --- # About Jobs -## about_Jobs +## SHORT DESCRIPTION - -# SHORT DESCRIPTION - -Provides information about how Windows PowerShell background jobs run a +Provides information about how PowerShell background jobs run a command or expression in the background without interacting with the current session. -# LONG DESCRIPTION +## LONG DESCRIPTION -This topic explains how to run background jobs in Windows PowerShell on a +This topic explains how to run background jobs in PowerShell on a local computer. For information about running background jobs on remote -computers, see about_Remote_Jobs. +computers, see [about_Remote_Jobs](about_Remote_Jobs.md). When you start a background job, the command prompt returns immediately, even if the job takes an extended time to complete. You can continue to work in the session without interruption while the job runs. -# THE JOB CMDLETS - - -Start-Job Starts a background job on a local computer. - -Get-Job Gets the background jobs that were started in the current -session. - -Receive-Job Gets the results of background jobs. - -Stop-Job Stops a background job. - -Wait-Job Suppresses the command prompt until one or all jobs are -complete. - -Remove-Job Deletes a background job. - -Invoke-Command The AsJob parameter runs any command as a background job on a -remote computer. You can also use Invoke-Command to run -any job command remotely, including a Start-Job command. - -# HOW TO START A JOB ON THE LOCAL COMPUTER - +## THE JOB CMDLETS + +|Cmdlet |Description | +|----------------|-------------------------------------------------------| +|`Start-Job` |Starts a background job on a local computer. | +|`Get-Job` |Gets the background jobs that were started in the | +| |current session. | +|`Receive-Job` |Gets the results of background jobs. | +|`Stop-Job` |Stops a background job. | +|`Wait-Job` |Suppresses the command prompt until one or all jobs are| +| |complete. | +|`Remove-Job` |Deletes a background job. | +|`Invoke-Command`|The AsJob parameter runs any command as a background | +| |job on a remote computer. You can also use | +| |`Invoke-Command` to run any job command remotely, | +| |including a Start-Job command. | + +## HOW TO START A JOB ON THE LOCAL COMPUTER To start a background job on the local computer, use the Start-Job cmdlet. @@ -57,251 +49,279 @@ cmdlet. To write a Start-Job command, enclose the command that the job runs in braces ( { } ). Use the ScriptBlock parameter to specify the command. -The following command starts a background job that runs a Get-Process +The following command starts a background job that runs a `Get-Process` command on the local computer. +```powershell Start-Job -ScriptBlock {Get-Process} +``` -The Start-Job command returns an object that represents the job. The job +The `Start-Job` command returns an object that represents the job. The job object contains useful information about the job, but it does not contain the job results. Save the job object in a variable, and then use it with the other Job cmdlets to manage the background job. The following command starts a job -object and saves the resulting job object in the $job variable. +object and saves the resulting job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-Process} +``` -You can also use the Get-Job cmdlet to get objects that represent the jobs -started in the current session. Get-Job returns the same job object that +You can also use the `Get-Job` cmdlet to get objects that represent the jobs +started in the current session. `Get-Job` returns the same job object that Start-Job returns. -# GETTING JOB OBJECTS - +## GETTING JOB OBJECTS To get object that represent the background jobs that were started in the -current session, use the Get-Job cmdlet. Without parameters, Get-Job +current session, use the `Get-Job` cmdlet. Without parameters, `Get-Job` returns all of the jobs that were started in the current session. For example, the following command gets the jobs in the current session. +```powershell PS C:> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Running True localhost Get-Process +``` You can also save the job object in a variable and use it to represent the job in a later command. The following command gets the job with ID 1 and -saves it in the $job variable. +saves it in the \$job variable. +```powershell $job = Get-Job -Id 1 +``` The job object contains the state of the job, which indicates whether the job has finished. A finished job has a state of "Complete" or "Failed". A job might also be blocked or running. +```powershell Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Complete True localhost Get-Process +``` -# GETTING THE RESULTS OF A JOB - +## GETTING THE RESULTS OF A JOB When you run a background job, the results do not appear immediately. Instead, the Start-Job cmdlet returns a job object that represents the job, but it does not contain the results. To get the results of a -background job, use the Receive-Job cmdlet. +background job, use the `Receive-Job` cmdlet. -The following command uses the Receive-Job cmdlet to get the results of -the job. It uses a job object saved in the $job variable to identify the +The following command uses the `Receive-Job` cmdlet to get the results of +the job. It uses a job object saved in the \$job variable to identify the job. +```powershell Receive-Job -Job $job +``` The Receive-Job cmdlet returns the results of the job. +``` Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -668 7 2672 6168 104 32.26 488 csrss + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 668 7 2672 6168 104 32.26 488 csrss # ... +``` +You can also save the results of a job in a variable. The following command +saves the results of the job in the \$job variable to the \$results variable. -You can also save the results of a job in a variable. The following -command saves the results of the job in the $job variable to the $results -variable. - +```powershell $results = Receive-Job -Job $job +``` And, you can save the results of the job in a file by using the redirection operator (>) or the Out-File cmdlet. The following command uses the -redirection operator to save the results of the job in the $job variable in +redirection operator to save the results of the job in the \$job variable in the Results.txt file. +```powershell Receive-Job -Job $job > results.txt +``` -# GETTING AND KEEPING PARTIAL JOB RESULTS - +## GETTING AND KEEPING PARTIAL JOB RESULTS The Receive-Job cmdlet gets the results of a background job. If the -job is complete, Receive-Job gets all job results. If the job is still +job is complete, `Receive-Job` gets all job results. If the job is still running, Receive-Job gets the results that have been generated thus far. -You can run Receive-Job commands again to get the remaining results. +You can run `Receive-Job` commands again to get the remaining results. -When Receive-Job returns results, by default, it deletes those results from -the cache where job results are stored. If you run another Receive-Job +When `Receive-Job` returns results, by default, it deletes those results from +the cache where job results are stored. If you run another `Receive-Job` command, you get only the results that are not yet received. -The following commands show the results of Receive-Job commands run +The following commands show the results of `Receive-Job` commands run before the job is complete. +```powershell C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -To prevent Receive-Job from deleting the job results that it has -returned, use the Keep parameter. As a result, Receive-Job returns all + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +To prevent `Receive-Job` from deleting the job results that it has +returned, use the **Keep** parameter. As a result, `Receive-Job` returns all of the results that have been generated until that time. The following commands show the effect of using the Keep parameter on a job that is not yet complete. +```powershell C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -# WAITING FOR THE RESULTS - - -If you run a command that takes a long time to complete, you can use -the properties of the job object to determine when the job is complete. -The following command uses the Get-Job object to get all of the background -jobs in the current session. - + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +## WAITING FOR THE RESULTS + +If you run a command that takes a long time to complete, you can use the +properties of the job object to determine when the job is complete. The +following command uses the `Get-Job` object to get all of the background jobs +in the current session. + +```powershell Get-Job +``` The results appear in a table. The status of the job appears in the State column. -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Complete True localhost Get-Process -2 Job2 BackgroundJob Running True localhost Get-EventLog -Log Syst... -3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Recurse - -In this case, the State property reveals that Job 2 is still running. If -you were to use the Receive-Job cmdlet to get the job results now, the -results would be incomplete. You can use the Receive-Job cmdlet -repeatedly to get all of the results. By default, each time you use it, -you get only the results that were not already received, but you can use -the Keep parameter of the Receive-Job cmdlet to retain the results, even -though they were already received. +``` +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Complete True localhost Get-Process +2 Job2 BackgroundJob Running True localhost Get-EventLog -Log ... +3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Re... +``` + +In this case, the State property reveals that Job 2 is still running. If you +were to use the `Receive-Job` cmdlet to get the job results now, the results +would be incomplete. You can use the `Receive-Job` cmdlet repeatedly to get +all of the results. By default, each time you use it, you get only the results +that were not already received, but you can use the Keep parameter of the +Receive-Job cmdlet to retain the results, even though they were already +received. You can write the partial results to a file and then append newer results as they arrive or you can wait and check the state of the job later. -You can use the Wait parameter of the Receive-Job cmdlet, which +You can use the Wait parameter of the `Receive-Job` cmdlet, which does not return the command prompt until the job is complete and all results are available. -You can also use the Wait-Job cmdlet to wait for any or all of the results -of the job. Wait-Job lets you wait for a particular job, for all jobs, or +You can also use the `Wait-Job` cmdlet to wait for any or all of the results +of the job. `Wait-Job` lets you wait for a particular job, for all jobs, or for any of the jobs to be completed. -The following command uses the Wait-Job cmdlet to wait for a job with -# ID 10. - +The following command uses the Wait-Job cmdlet to wait for a job with ID 10. +```powershell Wait-Job -ID 10 +``` -As a result, the Windows PowerShell prompt is suppressed until the job -is completed. +As a result, the PowerShell prompt is suppressed until the job is completed. You can also wait for a predetermined period of time. This command uses the Timeout parameter to limit the wait to 120 seconds. When the time expires, the command prompt returns, but the job continues to run in the background. +```powershell Wait-Job -ID 10 -Timeout 120 +``` -# STOPPING A JOB +## STOPPING A JOB - -To stop a background job, use the Stop-Job cmdlet. The following command +To stop a background job, use the `Stop-Job` cmdlet. The following command starts a job to get every entry in the System event log. It saves the job -object in the $job variable. +object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-EventLog -Log System} +``` The following command stops the job. It uses a pipeline operator (|) to -send the job in the $job variable to Stop-Job. +send the job in the \$job variable to `Stop-Job`. +```powershell $job | Stop-Job +``` -# DELETING A JOB - +## DELETING A JOB -To delete a background job, use the Remove-Job cmdlet. The following -command deletes the job in the $job variable. +To delete a background job, use the `Remove-Job` cmdlet. The following +command deletes the job in the \$job variable. +```powershell Remove-Job -Job $job +``` -# INVESTIGATING A FAILED JOB - +## INVESTIGATING A FAILED JOB To find out why a job failed, use the Reason subproperty of the job object. The following command starts a job without the required credentials. It -saves the job object in the $job variable. +saves the job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {New-Item -Path HKLM:\Software\MyCompany} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:\S... +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:... +``` The following command uses the Reason property to find the error that caused the job to fail. +```powershell $job.ChildJobs[0].JobStateInfo.Reason +``` In this case, the job failed because the remote computer required explicit credentials to run the command. The value of the Reason property is: -Connecting to remote server failed with the following error -message : Access is denied. +Connecting to remote server failed with the following error message : Access +is denied. -# SEE ALSO +## SEE ALSO [about_Remote_Jobs](about_Remote_Jobs.md) @@ -311,17 +331,16 @@ message : Access is denied. [about_PSSessions](about_PSSessions.md) -Start-Job - -Get-Job +[Start-Job](../Start-Job.md) -Receive-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Receive-Job](../Receive-Job.md) -Wait-Job +[Stop-Job](../Stop-Job.md) -Remove-Job +[Wait-Job](../Wait-Job.md) -Invoke-Command +[Remove-Job](../Remove-Job.md) +[Invoke-Command](../../Microsoft.PowerShell.Core/Invoke-Command.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Methods.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Methods.md index 5b5afddb2dcd..a32eb5d38a92 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Methods.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Methods.md @@ -7,188 +7,202 @@ title: about_Methods --- # About methods -## about_methods - ## SHORT DESCRIPTION -Describes how to use methods to perform actions on objects in Windows PowerShell®. +Describes how to use methods to perform actions on objects in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses objects to represent the items in data stores or the state of the computer. For example, FileInfo objects represent the files in file system drives and ProcessInfo objects represent the processes on the computer. -Objects have properties, which store data about the object, and methods that let you change the object. +PowerShell uses objects to represent the items in data stores or the state of +the computer. For example, FileInfo objects represent the files in file system +drives and ProcessInfo objects represent the processes on the computer. -A "method" is a set of instructions that specify an action you can perform on the object. For example, the FileInfo object includes the CopyTo method that copies the file that the FileInfo object represents. +Objects have properties, which store data about the object, and methods that +let you change the object. -To get the methods of any object, use the Get-Member cmdlet. Use its MemberType property with a value of "Method". The following command gets the methods of process objects. +A "method" is a set of instructions that specify an action you can perform on +the object. For example, the `FileInfo` object includes the `CopyTo` method that +copies the file that the `FileInfo` object represents. +To get the methods of any object, use the `Get-Member` cmdlet. Use its +**MemberType** property with a value of "Method". The following command gets +the methods of process objects. -``` +```powershell PS C:\> Get-Process | Get-Member -MemberType Method ``` +```output +TypeName: System.Diagnostics.Process - +Name MemberType Definition +---- ---------- ---------- +BeginErrorReadLine Method System.Void BeginErrorReadLine() +BeginOutputReadLine Method System.Void BeginOutputReadLine() +... +Kill Method System.Void Kill() +Refresh Method System.Void Refresh() +Start Method bool Start() +ToString Method string ToString() +WaitForExit Method bool WaitForExit(int milliseconds), ... +WaitForInputIdle Method bool WaitForInputIdle(int millisecon... ``` -TypeName: System.Diagnostics.Process - -Name MemberType Definition ----- ---------- ---------- -BeginErrorReadLine Method System.Void BeginErrorReadLine() -BeginOutputReadLine Method System.Void BeginOutputReadLine() -... -Kill Method System.Void Kill() -Refresh Method System.Void Refresh() -Start Method bool Start() -ToString Method string ToString() -WaitForExit Method bool WaitForExit(int milliseconds), System.Void WaitForExit() -WaitForInputIdle Method bool WaitForInputIdle(int milliseconds), bool WaitForInputIdle() -``` - - -To perform or "invoke" a method of an object, type a dot (.), the method name, and a set of parentheses "()". If the method has arguments, place the argument values inside the parentheses. The parentheses are required for every method call, even when there are no arguments. -For example, the following command invokes the Kill method of processes to end the Notepad process on the computer. As a result, the instance of Notepad closes. (The Get-Process command is enclosed in parentheses to insure that it runs before the Kill method is invoked. +To perform or "invoke" a method of an object, type a dot (.), the method name, +and a set of parentheses "()". If the method has arguments, place the argument +values inside the parentheses. The parentheses are required for every method +call, even when there are no arguments. +For example, the following command invokes the Kill method of processes to end +the Notepad process on the computer. As a result, the instance of Notepad +closes. (The `Get-Process` command is enclosed in parentheses to insure that +it runs before the Kill method is invoked. -``` +```powershell (Get-Process Notepad).Kill() ``` +Another very useful process is the Split method of strings. The split method +takes a delimiter character argument that tells the method where to split the +string. -Another very useful process is the Split method of strings. The split method takes a delimiter character argument that tells the method where to split the string. - - -``` -PS C:\> $a = "Try-Catch-Finally" -PS C:\> $a.Split("-") -Try -Catch +```powershell +PS C:\> $a = "Try-Catch-Finally" +PS C:\> $a.Split("-") +Try +Catch Finally ``` +As shown in the previous examples, you can invoke a method on an object that +you get by using a command or an object in a variable. -As shown in the previous examples, you can invoke a method on an object that you get by using a command or an object in a variable. - -Starting in Windows PowerShell 4.0, method invocation by using dynamic method names is supported. - +Starting in PowerShell 4.0, method invocation by using dynamic method names is +supported. ### LEARNING ABOUT METHODS -To find definitions of the methods of an object, go to help topic for the object type in MSDN and look for its methods page. For example, the following page describes the methods of process objects (System.Diagnostics.Process). - - -``` -http://msdn.microsoft.com/library/system.diagnostics.process_methods -``` +To find definitions of the methods of an object, go to help topic for the +object type in MSDN and look for its methods page. For example, the following +page describes the methods of process objects +[System.Diagnostics.Process](http://msdn.microsoft.com/library/system.diagnostics.process_methods). -To determine the arguments of a method, review the method definition, which is like the syntax diagram of a Windows PowerShell cmdlet. +To determine the arguments of a method, review the method definition, which is +like the syntax diagram of a PowerShell cmdlet. -A method definition might have one or more method signatures, which are like the parameter sets of Windows PowerShell cmdlets. The signatures show all of the valid formats of commands to invoke the method. - -For example, the CopyTo method of the FileInfo class contains the following two method signatures: - - -``` -1. CopyTo(String destFileName) -2. CopyTo(String destFileName, Boolean overwrite) -``` +A method definition might have one or more method signatures, which are like +the parameter sets of PowerShell cmdlets. The signatures show all of the valid +formats of commands to invoke the method. +For example, the `CopyTo` method of the `FileInfo` class contains the following +two method signatures: -The first method signature takes the destination file name (and a path). The following example use The first CopyTo method to copy the Final.txt file to the C:\Bin directory. + CopyTo(String destFileName) + CopyTo(String destFileName, Boolean overwrite) +The first method signature takes the destination file name (and a path). The +following example use The first `CopyTo` method to copy the Final.txt file to +the C:\\Bin directory. -``` +```powershell (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt") ``` +The second method signature take a destination file name and a Boolean value +that determines whether the destination file should be overwritten, if it +already exists. -The second method signature take a destination file name and a Boolean value that determines whether the destination file should be overwritten, if it already exists. - -The following example use The second CopyTo method to copy the Final.txt file to the C:\Bin directory, and to overwrite existing files. - +The following example use The second `CopyTo` method to copy the Final.txt file +to the C:\\Bin directory, and to overwrite existing files. ``` (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` - - ### METHODS OF SCALAR OBJECTS AND COLLECTIONS -The methods of one ("scalar") object of a particular type are often different from the methods of a collection of objects of the same type. -For example, every process has a Kill method, but a collection of processes does not have a Kill method. +The methods of one ("scalar") object of a particular type are often different +from the methods of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing methods of scalar objects and collections. +For example, every process has a `Kill` method, but a collection of processes +does not have a Kill method. -Beginning in Windows PowerShell 4.0, collection filtering by using a method syntax is supported. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing methods of scalar objects and collections. -If you submit a collection, but request a method that exists only on single ("scalar") objects, Windows invokes the method on every object in the collection. +Beginning in PowerShell 4.0, collection filtering by using a method syntax is +supported. -If the method exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you submit a collection, but request a method that exists only on single +("scalar") objects, PowerShell invokes the method on every object in the +collection. -This feature also works on properties of scalar objects and collections. For more information, see about_Properties. +If the method exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on properties of scalar objects and collections. For +more information, see [about_Properties](about_Properties.md). ### EXAMPLES -The following example runs the Kill method of individual process objects on a collection of process objects. This example works only on Windows PowerShell 3.0 and later versions of Windows PowerShell. -The first command starts three instances of the Notepad process. The second command uses the Get-Process command to get all three instance of the Notepad process and save them in the $p variable. +The following example runs the Kill method of individual process objects on a +collection of process objects. This example works only on PowerShell 3.0 and +later versions of PowerShell. +The first command starts three instances of the Notepad process. The second +command uses the `Get-Process` command to get all three instance of the Notepad +process and save them in the \$p variable. -``` -PS C:\> Notepad; Notepad; Notepad +```powershell +PS C:\> Notepad; Notepad; Notepad PS C:\> $p = Get-Process Notepad ``` +The third command uses the Count property of all collections to verify that +there are three processes in the \$p variable. -The third command uses the Count property of all collections to verify that there are three processes in the $p variable. - - -``` -PS C:\> $p.Count +```powershell +PS C:\> $p.Count 3 ``` +The fourth command runs the Kill method on all three processes in the \$p +variable. -The fourth command runs the Kill method on all three processes in the $p variable. - -This command works even though a collection of processes does not have a Kill method. - +This command works even though a collection of processes does not have a `Kill` +method. ``` PS C:\> $p.Kill() ``` +The fifth command uses the Get-Process command to confirm that the `Kill` +command worked. -The fifth command uses the Get-Process command to confirm that the Kill command worked. - - +```powershell +PS C:\> Get-Process Notepad +Get-Process : Cannot find a process with the name "notepad". Verify the proc +ess name and call the cmdlet again. +At line:1 char:12 ++ get-process <<<< notepad + + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process] +, ProcessCommandException + + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShel +l.Commands.GetProcessCommand ``` -PS C:\> Get-Process Notepad -Get-Process : Cannot find a process with the name "notepad". Verify the process name and call the cmdlet again. -At line:1 char:12 -+ get-process <<<< notepad - + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process], ProcessCommandException - + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.Commands.GetProcessCommand -``` - -To perform the same task on Windows PowerShell 2.0, use the Foreach-Object cmdlet to run the method on each object in the collection. +To perform the same task on PowerShell 2.0, use the `Foreach-Object` cmdlet to +run the method on each object in the collection. - -``` +```powershell PS C:\> $p | Foreach-Object {$_.Kill()} ``` - - ## SEE ALSO [about_Objects](about_Objects.md) [about_Properties](about_Properties.md) -Get-Member - +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md index 6d1f8847f78e..931280614067 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,51 +10,53 @@ title: about_Modules ## Short Description -Explains how to install, import, and use Windows PowerShell modules. +Explains how to install, import, and use PowerShell modules. ## Long Description -A module is a package that contains Windows PowerShell commands, such as -cmdlets, providers, functions, workflows, variables, and aliases. +A module is a package that contains PowerShell commands, such as cmdlets, +providers, functions, workflows, variables, and aliases. -People who write commands can use modules to organize their commands and -share them with others. People who receive modules can add the commands -in the modules to their Windows PowerShell sessions and use them just like -the built-in commands. +People who write commands can use modules to organize their commands and share +them with others. People who receive modules can add the commands in the +modules to their PowerShell sessions and use them just like the built-in +commands. -This topic explains how to use Windows PowerShell modules. -For information about how to write Windows PowerShell modules, see -[Writing a Windows PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) in the MSDN library. +This topic explains how to use PowerShell modules. For information about how +to write PowerShell modules, see [Writing a PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) +in the MSDN library. ## What Is a Module? -A module is a package of commands. All cmdlets and providers in your -session are added by a module or a snap-in. +A module is a package of commands. All cmdlets and providers in your session +are added by a module or a snap-in. ## Module Auto-Loading -Beginning in Windows PowerShell 3.0, Windows PowerShell imports -modules automatically the first time that you run any command in -an installed module. You can now use the commands in a module -without any set-up or profile configuration, so there's no need to -manage modules after you install them on your computer. +Beginning in PowerShell 3.0, PowerShell imports modules automatically the +first time that you run any command in an installed module. You can now use +the commands in a module without any set-up or profile configuration, so +there's no need to manage modules after you install them on your computer. -The commands in a module are also easier to find. The `Get-Command` cmdlet -now gets all commands in all installed modules, even if they are not yet -in the session, so you can find a command and use it without importing. +The commands in a module are also easier to find. The `Get-Command` cmdlet now +gets all commands in all installed modules, even if they are not yet in the +session, so you can find a command and use it without importing. Any of the following commands will import a module into your session. ### Run the Command + ```powershell Get-Mailbox -Identity Chris ``` ### Get the Command + ```powershell Get-Command Get-Mailbox ``` ### Get Help for the Command + ```powershell Get-Help Get-Mailbox ``` @@ -66,7 +68,7 @@ Only modules that are stored in the location specified by the PSModulePath environment variable are automatically imported. Modules in other locations must be imported by running the `Import-Module` cmdlet. -Also, commands that use Windows PowerShell providers do not automatically +Also, commands that use PowerShell providers do not automatically import a module. For example, if you use a command that requires the WSMan: drive, such as the `Get-PSSessionConfiguration` cmdlet, you might need to run the `Import-Module` cmdlet to import the Microsoft.WSMan.Management @@ -90,43 +92,40 @@ other useful information about managing modules. ## How to Install a Module -If you receive a module as a folder with files in it, you need -to install it on your computer before you can use it in Windows -PowerShell. +If you receive a module as a folder with files in it, you need to install it +on your computer before you can use it in PowerShell. -Most modules are installed for you. Windows PowerShell comes with -several preinstalled modules, sometimes called the "core" modules. -On Windows-based computers, if features that are included with the -operating system have cmdlets to manage them, those modules are preinstalled. -When you install a Windows feature, by using, for example, the Add Roles -and Features Wizard in Server Manager, or the Turn Windows features on or off -dialog box in Control Panel, any Windows PowerShell modules that are part -of the feature are installed. Many other modules come in an installer or -Setup program that installs the module. +Most modules are installed for you. PowerShell comes with several preinstalled +modules, sometimes called the "core" modules. On Windows-based computers, if +features that are included with the operating system have cmdlets to manage +them, those modules are preinstalled. When you install a Windows feature, by +using, for example, the Add Roles and Features Wizard in Server Manager, or +the Turn Windows features on or off dialog box in Control Panel, any +PowerShell modules that are part of the feature are installed. Many other +modules come in an installer or Setup program that installs the module. -To install a module folder: -1. Create a Modules directory for the current user if one does not exist. -To create a Modules directory, type: +Create a Modules directory for the current user if one does not exist. To +create a Modules directory, type: ```powershell New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules ``` -2. Copy the entire module folder into the Modules directory. -You can use any method to copy the folder, including Windows -Explorer and Cmd.exe, as well as Windows PowerShell. -In Windows PowerShell use the `Copy-Item` cmdlet. For example, to copy the -MyModule folder from C:\ps-test\MyModule to the Modules directory, type: +Copy the entire module folder into the Modules directory. You can use any +method to copy the folder, including Windows Explorer and Cmd.exe, as well as +PowerShell. In PowerShell use the `Copy-Item` cmdlet. For example, to copy the +MyModule folder from C:\\ps-test\\MyModule to the Modules directory, type: ```powershell -Copy-Item -Path C:\ps-test\MyModule -Destination $HOME\Documents\WindowsPowerShell\Modules +Copy-Item -Path C:\ps-test\MyModule -Destination ` + $HOME\Documents\WindowsPowerShell\Modules ``` You can install a module in any location, but installing your modules in a -default module location makes them easier to manage. For more information about -the default module locations, see the "Module and DSC Resource Locations, -and PSModulePath" section. +default module location makes them easier to manage. For more information +about the default module locations, see the "Module and DSC Resource +Locations, and PSModulePath" section. ## How to Find Installed Modules @@ -138,19 +137,20 @@ Get-Module -ListAvailable ``` To find the modules that have already been imported into your session, -at the Windows PowerShell prompt, type: +at the PowerShell prompt, type: ```powershell Get-Module ``` -For more information about the `Get-Module` cmdlet, see [Get-Module](../Get-Module.md). +For more information about the `Get-Module` cmdlet, see +[Get-Module](../Get-Module.md). ## How to Find the Commands in a Module -Use the `Get-Command` cmdlet to find all available commands. -You can use the parameters of the `Get-Command` cmdlet to filter commands -such as by module, name, and noun. +Use the `Get-Command` cmdlet to find all available commands. You can use the +parameters of the `Get-Command` cmdlet to filter commands such as by module, +name, and noun. To find all commands in a module, type: @@ -164,18 +164,17 @@ For example, to find the commands in the BitsTransfer module, type: Get-Command -Module BitsTransfer ``` -For more information about the `Get-Command` cmdlet, see [Get-Command](../Get-Command.md). +For more information about the `Get-Command` cmdlet, see +[Get-Command](../Get-Command.md). ## How to Get Help for the Commands in a Module -If the module contains Help files for the commands that it exports, -the `Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` -command format that you would use to get help for any command in Windows -PowerShell. +If the module contains Help files for the commands that it exports, the +`Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` +command format that you would use to get help for any command in PowerShell. -Beginning in Windows PowerShell 3.0, you can download Help files for -a module and download updates to the Help files so they are never -obsolete. +Beginning in PowerShell 3.0, you can download Help files for a module and +download updates to the Help files so they are never obsolete. To get help for a commands in a module, type: @@ -195,20 +194,22 @@ To download and install the help files for the commands in a module, type: Update-Help -Module ``` -For more information, see [Get-Help](../Get-Help.md) and [Update-Help](../Update-Help.md). +For more information, see [Get-Help](../Get-Help.md) and +[Update-Help](../Update-Help.md). ## How to Import a Module -You might have to import a module or import a module file. Importing is required -when a module is not installed in the locations specified by the PSModulePath -environment variable ($env:PSModulePath), or the module consists of file, such -as a .dll or .psm1 file, instead of typical module that is delivered as a folder. +You might have to import a module or import a module file. Importing is +required when a module is not installed in the locations specified by the +PSModulePath environment variable ($env:PSModulePath), or the module consists +of file, such as a .dll or .psm1 file, instead of typical module that is +delivered as a folder. -You might also choose to import a module so that you can use the parameters of the -`Import-Module` command, such as the Prefix parameter, which adds a distinctive prefix -to the noun names of all imported commands, or the **NoClobber** parameter, which prevents -the module from adding commands that would hide or replace existing commands in the -session. +You might also choose to import a module so that you can use the parameters of +the `Import-Module` command, such as the Prefix parameter, which adds a +distinctive prefix to the noun names of all imported commands, or the +**NoClobber** parameter, which prevents the module from adding commands that +would hide or replace existing commands in the session. To import modules, use the `Import-Module` cmdlet. @@ -254,8 +255,8 @@ For more information about adding modules to your session, see The `Import-Module` command imports modules into your current Windows PowerShell session. This command affects only the current session. -To import a module into every Windows PowerShell session that you -start, add the `Import-Module` command to your Windows PowerShell +To import a module into every PowerShell session that you +start, add the `Import-Module` command to your PowerShell profile. For more information about profiles, see [about_Profiles](about_Profiles.md). @@ -285,46 +286,42 @@ a module does not uninstall the module. For more information about the ## Module and DSC Resource Locations, and PSModulePath -The following are default locations for Windows PowerShell modules. -Starting in Windows PowerShell 4.0, with the introduction of DSC, a -new default module and DSC resource folder was introduced. For more -information about DSC, see about_DesiredStateConfiguration. +The following are default locations for PowerShell modules. Starting in +PowerShell 4.0, with the introduction of DSC, a new default module and DSC +resource folder was introduced. For more information about DSC, see +about_DesiredStateConfiguration. -System: $pshome\Modules -(%windir%\System32\WindowsPowerShell\v1.0\Modules) -System modules are those that ship with Windows and Windows PowerShell. +- System: $pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) + System modules are those that ship with Windows and PowerShell. -Starting in Windows Powershell 4.0, when Windows PowerShell -Desired State Configuration (DSC) was introduced, DSC resources that are -included with Windows PowerShell are also stored in $pshome\Modules, -in the $pshome\Modules\PSDesiredStateConfiguration\DSCResources -folder. + Starting in PowerShell 4.0, when PowerShell Desired State Configuration + (DSC) was introduced, DSC resources that are included with PowerShell are + also stored in \$pshome\\Modules, in the + \$pshome\\Modules\\PSDesiredStateConfiguration\\DSCResources folder. -Current user: $home\Documents\WindowsPowerShell\Modules -(%UserProfile%\Documents\WindowsPowerShell\Modules) +- Current user: \$home\\Documents\\WindowsPowerShell\\Modules + (%UserProfile%\Documents\WindowsPowerShell\Modules) -or + or -$home\My Documents\WindowsPowerShell\Modules -(%UserProfile%\My Documents\WindowsPowerShell\Modules) -This is the location for user-added modules prior to Windows PowerShell 4.0. + \$home\\My Documents\\WindowsPowerShell\\Modules + (%UserProfile%\My Documents\WindowsPowerShell\Modules) + This is the location for user-added modules prior to PowerShell 4.0. -In Windows PowerShell 4.0 and later releases of Windows PowerShell, -user-added modules and DSC resources are stored in -C:\Program Files\WindowsPowerShell\Modules. Modules and DSC resources -in this location are accessible by all users of the computer. -This change was required because the DSC engine runs as local +In PowerShell 4.0 and later releases of PowerShell, user-added modules and DSC +resources are stored in C:\\Program Files\\WindowsPowerShell\\Modules. Modules +and DSC resources in this location are accessible by all users of the +computer. This change was required because the DSC engine runs as local system, and could not access user-specific paths, such as -$home\Documents\WindowsPowerShell\Modules. +\$home\\Documents\\WindowsPowerShell\\Modules. -Starting in Windows PowerShell 5.0, with the addition of the -PowerShellGet module, and the [PowerShell Gallery](https://www.powershellgallery.com) -of community- and Microsoft-created resources, -the `Install-Module` command installs modules and DSC resources to -C:\Program Files\WindowsPowerShell\Modules by default. +Starting in PowerShell 5.0, with the addition of the PowerShellGet module, and +the [PowerShell Gallery](https://www.powershellgallery.com) of community- and +Microsoft-created resources, the `Install-Module` command installs modules and +DSC resources to C:\\Program Files\\WindowsPowerShell\\Modules by default. -Note: To add or change files in the %Windir%\System32 directory, -start Windows PowerShell with the "Run as administrator" option. +Note: To add or change files in the %Windir%\\System32 directory, start +PowerShell with the "Run as administrator" option. You can change the default module locations on your system by changing the value of the PSModulePath environment variable ($Env:PSModulePath). The @@ -356,7 +353,7 @@ When you add a path to PSModulePath, `Get-Module` and `Import-Module` commands include modules in that path. The value that you set affects only the current session. To make the -change persistent, add the command to your Windows PowerShell profile +change persistent, add the command to your PowerShell profile or use System in Control Panel to change the value of the PSModulePath environment variable in the registry. @@ -369,70 +366,72 @@ For more information about the PSModulePath variable, see ## Modules and Name Conflicts -Name conflicts occur when more than one command in the session -has the same name. Importing a module causes a name conflict when -commands in the module have the same names as commands or items -in the session. +Name conflicts occur when more than one command in the session has the same +name. Importing a module causes a name conflict when commands in the module +have the same names as commands or items in the session. Name conflicts can result in commands being hidden or replaced. ### Hidden -A command is hidden when it is not the command that runs -when you type the command name, but you can run it -by using another method, such as by qualifying the command -name with the name of the module or snap-in in which it + +A command is hidden when it is not the command that runs when you type the +command name, but you can run it by using another method, such as by +qualifying the command name with the name of the module or snap-in in which it originated. ### Replaced -A command is replaced when you cannot run it because -it has been overwritten by a command with the same name. Even -when you remove the module that caused the conflict, you cannot -run a replaced command unless you restart the session. + +A command is replaced when you cannot run it because it has been overwritten +by a command with the same name. Even when you remove the module that caused +the conflict, you cannot run a replaced command unless you restart the +session. `Import-Module` might add commands that hide and replace commands in the current session. Also, commands in your session can hide commands that the module added. -To detect name conflicts, use the **All** parameter of the `Get-Command` cmdlet. -Beginning in Windows PowerShell 3.0, `Get-Command` gets only that commands -that run when you type the command name. The **All** parameter gets all commands -with the specific name in the session. +To detect name conflicts, use the **All** parameter of the `Get-Command` +cmdlet. Beginning in PowerShell 3.0, `Get-Command` gets only that commands +that run when you type the command name. The **All** parameter gets all +commands with the specific name in the session. To prevent name conflicts, use the **NoClobber** or **Prefix** parameters of -the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the names -of imported commands so that they are unique in the session. The **NoClobber** -parameter does not import any commands that would hide or replace existing -commands in the session. - -You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** parameters -of `Import-Module` to select only the commands that you want to import, -and you can exclude commands that cause name conflicts in your session. +the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the +names of imported commands so that they are unique in the session. The +**NoClobber** parameter does not import any commands that would hide or +replace existing commands in the session. + +You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** +parameters of `Import-Module` to select only the commands that you want to +import, and you can exclude commands that cause name conflicts in your +session. Module authors can prevent name conflicts by using the DefaultCommandPrefix -property of the module manifest to add a default prefix to all command -names. The value of the Prefix parameter takes precedence over the value -of DefaultCommandPrefix. +property of the module manifest to add a default prefix to all command names. +The value of the Prefix parameter takes precedence over the value of +DefaultCommandPrefix. -Even if a command is hidden, you can run it by qualifying the command -name with the name of the module or snap-in in which it originated. +Even if a command is hidden, you can run it by qualifying the command name +with the name of the module or snap-in in which it originated. -The Windows PowerShell command precedence rules determine which command -runs when the session includes commands with the same name. +The PowerShell command precedence rules determine which command runs when the +session includes commands with the same name. For example, when a session includes a function and a cmdlet with the same -name, Windows PowerShell runs the function by default. When the session -includes commands of the same type with the same name, such as two cmdlets -with the same name, by default, it runs the most recently added command. +name, PowerShell runs the function by default. When the session includes +commands of the same type with the same name, such as two cmdlets with the +same name, by default, it runs the most recently added command. For more information, including an explanation of the precedence rules and -instructions for running hidden commands, see [about_Command_Precedence](about_Command_Precedence.md). +instructions for running hidden commands, see +[about_Command_Precedence](about_Command_Precedence.md). ## Modules and Snap-ins -You can add commands to your session from modules and snap-ins. Modules -can add all types of commands, including cmdlets, providers, and functions, -and items, such as variables, aliases, and Windows PowerShell drives. -Snap-ins can add only cmdlets and providers. +You can add commands to your session from modules and snap-ins. Modules can +add all types of commands, including cmdlets, providers, and functions, and +items, such as variables, aliases, and PowerShell drives. Snap-ins can add +only cmdlets and providers. Before removing a module or snap-in from your session, use the following commands to determine which commands will be removed. @@ -441,55 +440,52 @@ To find the source of a cmdlet in your session, use the following command format: ```powershell -Get-Command | Format-List -Property verb, noun, pssnapin, module +Get-Command | Format-List -Property verb,noun,pssnapin,module ``` For example, to find the source of the `Get-Date` cmdlet, type: ```powershell -Get-Command Get-Date | Format-List -Property verb, noun, pssnapin, module +Get-Command Get-Date | Format-List -Property verb,noun,pssnapin,module ``` -For more information about Windows PowerShell snap-ins, see [about_PSSnapins](about_PSSnapins.md). +For more information about PowerShell snap-ins, see +[about_PSSnapins](about_PSSnapins.md). ## Module-related Warnings and Errors -The commands that a module exports should follow the Windows PowerShell -command naming rules. If the module that you import exports cmdlets or -functions that have unapproved verbs in their names, the `Import-Module` -cmdlet displays the following warning message. +The commands that a module exports should follow the PowerShell command naming +rules. If the module that you import exports cmdlets or functions that have +unapproved verbs in their names, the `Import-Module` cmdlet displays the +following warning message. -WARNING: Some imported command names include unapproved verbs -which might make them less discoverable. Use the Verbose parameter -for more detail or type `Get-Verb` to see the list of approved verbs. +WARNING: Some imported command names include unapproved verbs which might make +them less discoverable. Use the Verbose parameter for more detail or type +`Get-Verb` to see the list of approved verbs. This message is only a warning. The complete module is still imported, -including the non-conforming commands. Although the message is displayed -to module users, the naming problem should be fixed by the module author. +including the non-conforming commands. Although the message is displayed to +module users, the naming problem should be fixed by the module author. -To suppress the warning message, use the **DisableNameChecking** parameter -of the `Import-Module` cmdlet. +To suppress the warning message, use the **DisableNameChecking** parameter of +the `Import-Module` cmdlet. ## Built-in Modules and Snap-ins -In Windows PowerShell 2.0 and in older-style host programs in Windows -PowerShell 3.0 and later, the core commands that are installed with -Windows PowerShell are packaged in snap-ins that are added automatically -to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that -implement the InitialSessionState.CreateDefault2 initial session state API -- -the core commands are packaged in modules. The default is -Microsoft.PowerShell.Core, which is always a snap-in. +In PowerShell 2.0 and in older-style host programs in PowerShell 3.0 and +later, the core commands that are installed with PowerShell are packaged in +snap-ins that are added automatically to every PowerShell session. -The Microsoft.PowerShell.Core snap-in is added to every session by -default. Modules are loaded automatically on first-use. +Beginning in PowerShell 3.0, for host programs that implement the +`InitialSessionState.CreateDefault2` initial session state API the +Microsoft.PowerShell.Core snap-in is added to every session by default. +Modules are loaded automatically on first-use. -NOTE: Remote sessions, including sessions that are started by using -the New-PSSession cmdlet, are older-style sessions in which the built-in +NOTE: Remote sessions, including sessions that are started by using the +`New-PSSession` cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. -The following modules (or snap-ins) are installed with Windows PowerShell. +The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics @@ -509,13 +505,13 @@ The following modules (or snap-ins) are installed with Windows PowerShell. ## Logging Module Events -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets -and functions in Windows PowerShell modules and snap-ins by setting the -LogPipelineExecutionDetails property of modules and snap-ins to $True. -You can also use a Group Policy setting, Turn on Module Logging, -to enable module logging in all Windows PowerShell sessions. -For more information, see [about_EventLogs](about_EventLogs.md) -and [about_Group_Policy_Settings](about_Group_Policy_Settings.md). +Beginning in PowerShell 3.0, you can record execution events for the cmdlets +and functions in PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to \$True. You can +also use a Group Policy setting, Turn on Module Logging, to enable module +logging in all PowerShell sessions. For more information, see +[about_EventLogs](about_EventLogs.md) and +[about_Group_Policy_Settings](about_Group_Policy_Settings.md). ## See Also diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Jobs.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Jobs.md index 2791902df4b1..c90d48ee71a1 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Jobs.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,49 +7,41 @@ title: about_Jobs --- # About Jobs -## about_Jobs +## SHORT DESCRIPTION - -# SHORT DESCRIPTION - -Provides information about how Windows PowerShell background jobs run a +Provides information about how PowerShell background jobs run a command or expression in the background without interacting with the current session. -# LONG DESCRIPTION +## LONG DESCRIPTION -This topic explains how to run background jobs in Windows PowerShell on a +This topic explains how to run background jobs in PowerShell on a local computer. For information about running background jobs on remote -computers, see about_Remote_Jobs. +computers, see [about_Remote_Jobs](about_Remote_Jobs.md). When you start a background job, the command prompt returns immediately, even if the job takes an extended time to complete. You can continue to work in the session without interruption while the job runs. -# THE JOB CMDLETS - - -Start-Job Starts a background job on a local computer. - -Get-Job Gets the background jobs that were started in the current -session. - -Receive-Job Gets the results of background jobs. - -Stop-Job Stops a background job. - -Wait-Job Suppresses the command prompt until one or all jobs are -complete. - -Remove-Job Deletes a background job. - -Invoke-Command The AsJob parameter runs any command as a background job on a -remote computer. You can also use Invoke-Command to run -any job command remotely, including a Start-Job command. - -# HOW TO START A JOB ON THE LOCAL COMPUTER - +## THE JOB CMDLETS + +|Cmdlet |Description | +|----------------|-------------------------------------------------------| +|`Start-Job` |Starts a background job on a local computer. | +|`Get-Job` |Gets the background jobs that were started in the | +| |current session. | +|`Receive-Job` |Gets the results of background jobs. | +|`Stop-Job` |Stops a background job. | +|`Wait-Job` |Suppresses the command prompt until one or all jobs are| +| |complete. | +|`Remove-Job` |Deletes a background job. | +|`Invoke-Command`|The AsJob parameter runs any command as a background | +| |job on a remote computer. You can also use | +| |`Invoke-Command` to run any job command remotely, | +| |including a Start-Job command. | + +## HOW TO START A JOB ON THE LOCAL COMPUTER To start a background job on the local computer, use the Start-Job cmdlet. @@ -57,251 +49,279 @@ cmdlet. To write a Start-Job command, enclose the command that the job runs in braces ( { } ). Use the ScriptBlock parameter to specify the command. -The following command starts a background job that runs a Get-Process +The following command starts a background job that runs a `Get-Process` command on the local computer. +```powershell Start-Job -ScriptBlock {Get-Process} +``` -The Start-Job command returns an object that represents the job. The job +The `Start-Job` command returns an object that represents the job. The job object contains useful information about the job, but it does not contain the job results. Save the job object in a variable, and then use it with the other Job cmdlets to manage the background job. The following command starts a job -object and saves the resulting job object in the $job variable. +object and saves the resulting job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-Process} +``` -You can also use the Get-Job cmdlet to get objects that represent the jobs -started in the current session. Get-Job returns the same job object that +You can also use the `Get-Job` cmdlet to get objects that represent the jobs +started in the current session. `Get-Job` returns the same job object that Start-Job returns. -# GETTING JOB OBJECTS - +## GETTING JOB OBJECTS To get object that represent the background jobs that were started in the -current session, use the Get-Job cmdlet. Without parameters, Get-Job +current session, use the `Get-Job` cmdlet. Without parameters, `Get-Job` returns all of the jobs that were started in the current session. For example, the following command gets the jobs in the current session. +```powershell PS C:> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Running True localhost Get-Process +``` You can also save the job object in a variable and use it to represent the job in a later command. The following command gets the job with ID 1 and -saves it in the $job variable. +saves it in the \$job variable. +```powershell $job = Get-Job -Id 1 +``` The job object contains the state of the job, which indicates whether the job has finished. A finished job has a state of "Complete" or "Failed". A job might also be blocked or running. +```powershell Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Complete True localhost Get-Process +``` -# GETTING THE RESULTS OF A JOB - +## GETTING THE RESULTS OF A JOB When you run a background job, the results do not appear immediately. Instead, the Start-Job cmdlet returns a job object that represents the job, but it does not contain the results. To get the results of a -background job, use the Receive-Job cmdlet. +background job, use the `Receive-Job` cmdlet. -The following command uses the Receive-Job cmdlet to get the results of -the job. It uses a job object saved in the $job variable to identify the +The following command uses the `Receive-Job` cmdlet to get the results of +the job. It uses a job object saved in the \$job variable to identify the job. +```powershell Receive-Job -Job $job +``` The Receive-Job cmdlet returns the results of the job. +``` Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -668 7 2672 6168 104 32.26 488 csrss + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 668 7 2672 6168 104 32.26 488 csrss # ... +``` +You can also save the results of a job in a variable. The following command +saves the results of the job in the \$job variable to the \$results variable. -You can also save the results of a job in a variable. The following -command saves the results of the job in the $job variable to the $results -variable. - +```powershell $results = Receive-Job -Job $job +``` And, you can save the results of the job in a file by using the redirection operator (>) or the Out-File cmdlet. The following command uses the -redirection operator to save the results of the job in the $job variable in +redirection operator to save the results of the job in the \$job variable in the Results.txt file. +```powershell Receive-Job -Job $job > results.txt +``` -# GETTING AND KEEPING PARTIAL JOB RESULTS - +## GETTING AND KEEPING PARTIAL JOB RESULTS The Receive-Job cmdlet gets the results of a background job. If the -job is complete, Receive-Job gets all job results. If the job is still +job is complete, `Receive-Job` gets all job results. If the job is still running, Receive-Job gets the results that have been generated thus far. -You can run Receive-Job commands again to get the remaining results. +You can run `Receive-Job` commands again to get the remaining results. -When Receive-Job returns results, by default, it deletes those results from -the cache where job results are stored. If you run another Receive-Job +When `Receive-Job` returns results, by default, it deletes those results from +the cache where job results are stored. If you run another `Receive-Job` command, you get only the results that are not yet received. -The following commands show the results of Receive-Job commands run +The following commands show the results of `Receive-Job` commands run before the job is complete. +```powershell C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -To prevent Receive-Job from deleting the job results that it has -returned, use the Keep parameter. As a result, Receive-Job returns all + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +To prevent `Receive-Job` from deleting the job results that it has +returned, use the **Keep** parameter. As a result, `Receive-Job` returns all of the results that have been generated until that time. The following commands show the effect of using the Keep parameter on a job that is not yet complete. +```powershell C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -# WAITING FOR THE RESULTS - - -If you run a command that takes a long time to complete, you can use -the properties of the job object to determine when the job is complete. -The following command uses the Get-Job object to get all of the background -jobs in the current session. - + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +## WAITING FOR THE RESULTS + +If you run a command that takes a long time to complete, you can use the +properties of the job object to determine when the job is complete. The +following command uses the `Get-Job` object to get all of the background jobs +in the current session. + +```powershell Get-Job +``` The results appear in a table. The status of the job appears in the State column. -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Complete True localhost Get-Process -2 Job2 BackgroundJob Running True localhost Get-EventLog -Log Syst... -3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Recurse - -In this case, the State property reveals that Job 2 is still running. If -you were to use the Receive-Job cmdlet to get the job results now, the -results would be incomplete. You can use the Receive-Job cmdlet -repeatedly to get all of the results. By default, each time you use it, -you get only the results that were not already received, but you can use -the Keep parameter of the Receive-Job cmdlet to retain the results, even -though they were already received. +``` +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Complete True localhost Get-Process +2 Job2 BackgroundJob Running True localhost Get-EventLog -Log ... +3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Re... +``` + +In this case, the State property reveals that Job 2 is still running. If you +were to use the `Receive-Job` cmdlet to get the job results now, the results +would be incomplete. You can use the `Receive-Job` cmdlet repeatedly to get +all of the results. By default, each time you use it, you get only the results +that were not already received, but you can use the Keep parameter of the +Receive-Job cmdlet to retain the results, even though they were already +received. You can write the partial results to a file and then append newer results as they arrive or you can wait and check the state of the job later. -You can use the Wait parameter of the Receive-Job cmdlet, which +You can use the Wait parameter of the `Receive-Job` cmdlet, which does not return the command prompt until the job is complete and all results are available. -You can also use the Wait-Job cmdlet to wait for any or all of the results -of the job. Wait-Job lets you wait for a particular job, for all jobs, or +You can also use the `Wait-Job` cmdlet to wait for any or all of the results +of the job. `Wait-Job` lets you wait for a particular job, for all jobs, or for any of the jobs to be completed. -The following command uses the Wait-Job cmdlet to wait for a job with -# ID 10. - +The following command uses the Wait-Job cmdlet to wait for a job with ID 10. +```powershell Wait-Job -ID 10 +``` -As a result, the Windows PowerShell prompt is suppressed until the job -is completed. +As a result, the PowerShell prompt is suppressed until the job is completed. You can also wait for a predetermined period of time. This command uses the Timeout parameter to limit the wait to 120 seconds. When the time expires, the command prompt returns, but the job continues to run in the background. +```powershell Wait-Job -ID 10 -Timeout 120 +``` -# STOPPING A JOB +## STOPPING A JOB - -To stop a background job, use the Stop-Job cmdlet. The following command +To stop a background job, use the `Stop-Job` cmdlet. The following command starts a job to get every entry in the System event log. It saves the job -object in the $job variable. +object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-EventLog -Log System} +``` The following command stops the job. It uses a pipeline operator (|) to -send the job in the $job variable to Stop-Job. +send the job in the \$job variable to `Stop-Job`. +```powershell $job | Stop-Job +``` -# DELETING A JOB - +## DELETING A JOB -To delete a background job, use the Remove-Job cmdlet. The following -command deletes the job in the $job variable. +To delete a background job, use the `Remove-Job` cmdlet. The following +command deletes the job in the \$job variable. +```powershell Remove-Job -Job $job +``` -# INVESTIGATING A FAILED JOB - +## INVESTIGATING A FAILED JOB To find out why a job failed, use the Reason subproperty of the job object. The following command starts a job without the required credentials. It -saves the job object in the $job variable. +saves the job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {New-Item -Path HKLM:\Software\MyCompany} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:\S... +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:... +``` The following command uses the Reason property to find the error that caused the job to fail. +```powershell $job.ChildJobs[0].JobStateInfo.Reason +``` In this case, the job failed because the remote computer required explicit credentials to run the command. The value of the Reason property is: -Connecting to remote server failed with the following error -message : Access is denied. +Connecting to remote server failed with the following error message : Access +is denied. -# SEE ALSO +## SEE ALSO [about_Remote_Jobs](about_Remote_Jobs.md) @@ -311,17 +331,16 @@ message : Access is denied. [about_PSSessions](about_PSSessions.md) -Start-Job - -Get-Job +[Start-Job](../Start-Job.md) -Receive-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Receive-Job](../Receive-Job.md) -Wait-Job +[Stop-Job](../Stop-Job.md) -Remove-Job +[Wait-Job](../Wait-Job.md) -Invoke-Command +[Remove-Job](../Remove-Job.md) +[Invoke-Command](../../Microsoft.PowerShell.Core/Invoke-Command.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Methods.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Methods.md index 5b5afddb2dcd..a32eb5d38a92 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Methods.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Methods.md @@ -7,188 +7,202 @@ title: about_Methods --- # About methods -## about_methods - ## SHORT DESCRIPTION -Describes how to use methods to perform actions on objects in Windows PowerShell®. +Describes how to use methods to perform actions on objects in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses objects to represent the items in data stores or the state of the computer. For example, FileInfo objects represent the files in file system drives and ProcessInfo objects represent the processes on the computer. -Objects have properties, which store data about the object, and methods that let you change the object. +PowerShell uses objects to represent the items in data stores or the state of +the computer. For example, FileInfo objects represent the files in file system +drives and ProcessInfo objects represent the processes on the computer. -A "method" is a set of instructions that specify an action you can perform on the object. For example, the FileInfo object includes the CopyTo method that copies the file that the FileInfo object represents. +Objects have properties, which store data about the object, and methods that +let you change the object. -To get the methods of any object, use the Get-Member cmdlet. Use its MemberType property with a value of "Method". The following command gets the methods of process objects. +A "method" is a set of instructions that specify an action you can perform on +the object. For example, the `FileInfo` object includes the `CopyTo` method that +copies the file that the `FileInfo` object represents. +To get the methods of any object, use the `Get-Member` cmdlet. Use its +**MemberType** property with a value of "Method". The following command gets +the methods of process objects. -``` +```powershell PS C:\> Get-Process | Get-Member -MemberType Method ``` +```output +TypeName: System.Diagnostics.Process - +Name MemberType Definition +---- ---------- ---------- +BeginErrorReadLine Method System.Void BeginErrorReadLine() +BeginOutputReadLine Method System.Void BeginOutputReadLine() +... +Kill Method System.Void Kill() +Refresh Method System.Void Refresh() +Start Method bool Start() +ToString Method string ToString() +WaitForExit Method bool WaitForExit(int milliseconds), ... +WaitForInputIdle Method bool WaitForInputIdle(int millisecon... ``` -TypeName: System.Diagnostics.Process - -Name MemberType Definition ----- ---------- ---------- -BeginErrorReadLine Method System.Void BeginErrorReadLine() -BeginOutputReadLine Method System.Void BeginOutputReadLine() -... -Kill Method System.Void Kill() -Refresh Method System.Void Refresh() -Start Method bool Start() -ToString Method string ToString() -WaitForExit Method bool WaitForExit(int milliseconds), System.Void WaitForExit() -WaitForInputIdle Method bool WaitForInputIdle(int milliseconds), bool WaitForInputIdle() -``` - - -To perform or "invoke" a method of an object, type a dot (.), the method name, and a set of parentheses "()". If the method has arguments, place the argument values inside the parentheses. The parentheses are required for every method call, even when there are no arguments. -For example, the following command invokes the Kill method of processes to end the Notepad process on the computer. As a result, the instance of Notepad closes. (The Get-Process command is enclosed in parentheses to insure that it runs before the Kill method is invoked. +To perform or "invoke" a method of an object, type a dot (.), the method name, +and a set of parentheses "()". If the method has arguments, place the argument +values inside the parentheses. The parentheses are required for every method +call, even when there are no arguments. +For example, the following command invokes the Kill method of processes to end +the Notepad process on the computer. As a result, the instance of Notepad +closes. (The `Get-Process` command is enclosed in parentheses to insure that +it runs before the Kill method is invoked. -``` +```powershell (Get-Process Notepad).Kill() ``` +Another very useful process is the Split method of strings. The split method +takes a delimiter character argument that tells the method where to split the +string. -Another very useful process is the Split method of strings. The split method takes a delimiter character argument that tells the method where to split the string. - - -``` -PS C:\> $a = "Try-Catch-Finally" -PS C:\> $a.Split("-") -Try -Catch +```powershell +PS C:\> $a = "Try-Catch-Finally" +PS C:\> $a.Split("-") +Try +Catch Finally ``` +As shown in the previous examples, you can invoke a method on an object that +you get by using a command or an object in a variable. -As shown in the previous examples, you can invoke a method on an object that you get by using a command or an object in a variable. - -Starting in Windows PowerShell 4.0, method invocation by using dynamic method names is supported. - +Starting in PowerShell 4.0, method invocation by using dynamic method names is +supported. ### LEARNING ABOUT METHODS -To find definitions of the methods of an object, go to help topic for the object type in MSDN and look for its methods page. For example, the following page describes the methods of process objects (System.Diagnostics.Process). - - -``` -http://msdn.microsoft.com/library/system.diagnostics.process_methods -``` +To find definitions of the methods of an object, go to help topic for the +object type in MSDN and look for its methods page. For example, the following +page describes the methods of process objects +[System.Diagnostics.Process](http://msdn.microsoft.com/library/system.diagnostics.process_methods). -To determine the arguments of a method, review the method definition, which is like the syntax diagram of a Windows PowerShell cmdlet. +To determine the arguments of a method, review the method definition, which is +like the syntax diagram of a PowerShell cmdlet. -A method definition might have one or more method signatures, which are like the parameter sets of Windows PowerShell cmdlets. The signatures show all of the valid formats of commands to invoke the method. - -For example, the CopyTo method of the FileInfo class contains the following two method signatures: - - -``` -1. CopyTo(String destFileName) -2. CopyTo(String destFileName, Boolean overwrite) -``` +A method definition might have one or more method signatures, which are like +the parameter sets of PowerShell cmdlets. The signatures show all of the valid +formats of commands to invoke the method. +For example, the `CopyTo` method of the `FileInfo` class contains the following +two method signatures: -The first method signature takes the destination file name (and a path). The following example use The first CopyTo method to copy the Final.txt file to the C:\Bin directory. + CopyTo(String destFileName) + CopyTo(String destFileName, Boolean overwrite) +The first method signature takes the destination file name (and a path). The +following example use The first `CopyTo` method to copy the Final.txt file to +the C:\\Bin directory. -``` +```powershell (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt") ``` +The second method signature take a destination file name and a Boolean value +that determines whether the destination file should be overwritten, if it +already exists. -The second method signature take a destination file name and a Boolean value that determines whether the destination file should be overwritten, if it already exists. - -The following example use The second CopyTo method to copy the Final.txt file to the C:\Bin directory, and to overwrite existing files. - +The following example use The second `CopyTo` method to copy the Final.txt file +to the C:\\Bin directory, and to overwrite existing files. ``` (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` - - ### METHODS OF SCALAR OBJECTS AND COLLECTIONS -The methods of one ("scalar") object of a particular type are often different from the methods of a collection of objects of the same type. -For example, every process has a Kill method, but a collection of processes does not have a Kill method. +The methods of one ("scalar") object of a particular type are often different +from the methods of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing methods of scalar objects and collections. +For example, every process has a `Kill` method, but a collection of processes +does not have a Kill method. -Beginning in Windows PowerShell 4.0, collection filtering by using a method syntax is supported. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing methods of scalar objects and collections. -If you submit a collection, but request a method that exists only on single ("scalar") objects, Windows invokes the method on every object in the collection. +Beginning in PowerShell 4.0, collection filtering by using a method syntax is +supported. -If the method exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you submit a collection, but request a method that exists only on single +("scalar") objects, PowerShell invokes the method on every object in the +collection. -This feature also works on properties of scalar objects and collections. For more information, see about_Properties. +If the method exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on properties of scalar objects and collections. For +more information, see [about_Properties](about_Properties.md). ### EXAMPLES -The following example runs the Kill method of individual process objects on a collection of process objects. This example works only on Windows PowerShell 3.0 and later versions of Windows PowerShell. -The first command starts three instances of the Notepad process. The second command uses the Get-Process command to get all three instance of the Notepad process and save them in the $p variable. +The following example runs the Kill method of individual process objects on a +collection of process objects. This example works only on PowerShell 3.0 and +later versions of PowerShell. +The first command starts three instances of the Notepad process. The second +command uses the `Get-Process` command to get all three instance of the Notepad +process and save them in the \$p variable. -``` -PS C:\> Notepad; Notepad; Notepad +```powershell +PS C:\> Notepad; Notepad; Notepad PS C:\> $p = Get-Process Notepad ``` +The third command uses the Count property of all collections to verify that +there are three processes in the \$p variable. -The third command uses the Count property of all collections to verify that there are three processes in the $p variable. - - -``` -PS C:\> $p.Count +```powershell +PS C:\> $p.Count 3 ``` +The fourth command runs the Kill method on all three processes in the \$p +variable. -The fourth command runs the Kill method on all three processes in the $p variable. - -This command works even though a collection of processes does not have a Kill method. - +This command works even though a collection of processes does not have a `Kill` +method. ``` PS C:\> $p.Kill() ``` +The fifth command uses the Get-Process command to confirm that the `Kill` +command worked. -The fifth command uses the Get-Process command to confirm that the Kill command worked. - - +```powershell +PS C:\> Get-Process Notepad +Get-Process : Cannot find a process with the name "notepad". Verify the proc +ess name and call the cmdlet again. +At line:1 char:12 ++ get-process <<<< notepad + + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process] +, ProcessCommandException + + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShel +l.Commands.GetProcessCommand ``` -PS C:\> Get-Process Notepad -Get-Process : Cannot find a process with the name "notepad". Verify the process name and call the cmdlet again. -At line:1 char:12 -+ get-process <<<< notepad - + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process], ProcessCommandException - + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.Commands.GetProcessCommand -``` - -To perform the same task on Windows PowerShell 2.0, use the Foreach-Object cmdlet to run the method on each object in the collection. +To perform the same task on PowerShell 2.0, use the `Foreach-Object` cmdlet to +run the method on each object in the collection. - -``` +```powershell PS C:\> $p | Foreach-Object {$_.Kill()} ``` - - ## SEE ALSO [about_Objects](about_Objects.md) [about_Properties](about_Properties.md) -Get-Member - +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md index 6d1f8847f78e..931280614067 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,51 +10,53 @@ title: about_Modules ## Short Description -Explains how to install, import, and use Windows PowerShell modules. +Explains how to install, import, and use PowerShell modules. ## Long Description -A module is a package that contains Windows PowerShell commands, such as -cmdlets, providers, functions, workflows, variables, and aliases. +A module is a package that contains PowerShell commands, such as cmdlets, +providers, functions, workflows, variables, and aliases. -People who write commands can use modules to organize their commands and -share them with others. People who receive modules can add the commands -in the modules to their Windows PowerShell sessions and use them just like -the built-in commands. +People who write commands can use modules to organize their commands and share +them with others. People who receive modules can add the commands in the +modules to their PowerShell sessions and use them just like the built-in +commands. -This topic explains how to use Windows PowerShell modules. -For information about how to write Windows PowerShell modules, see -[Writing a Windows PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) in the MSDN library. +This topic explains how to use PowerShell modules. For information about how +to write PowerShell modules, see [Writing a PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) +in the MSDN library. ## What Is a Module? -A module is a package of commands. All cmdlets and providers in your -session are added by a module or a snap-in. +A module is a package of commands. All cmdlets and providers in your session +are added by a module or a snap-in. ## Module Auto-Loading -Beginning in Windows PowerShell 3.0, Windows PowerShell imports -modules automatically the first time that you run any command in -an installed module. You can now use the commands in a module -without any set-up or profile configuration, so there's no need to -manage modules after you install them on your computer. +Beginning in PowerShell 3.0, PowerShell imports modules automatically the +first time that you run any command in an installed module. You can now use +the commands in a module without any set-up or profile configuration, so +there's no need to manage modules after you install them on your computer. -The commands in a module are also easier to find. The `Get-Command` cmdlet -now gets all commands in all installed modules, even if they are not yet -in the session, so you can find a command and use it without importing. +The commands in a module are also easier to find. The `Get-Command` cmdlet now +gets all commands in all installed modules, even if they are not yet in the +session, so you can find a command and use it without importing. Any of the following commands will import a module into your session. ### Run the Command + ```powershell Get-Mailbox -Identity Chris ``` ### Get the Command + ```powershell Get-Command Get-Mailbox ``` ### Get Help for the Command + ```powershell Get-Help Get-Mailbox ``` @@ -66,7 +68,7 @@ Only modules that are stored in the location specified by the PSModulePath environment variable are automatically imported. Modules in other locations must be imported by running the `Import-Module` cmdlet. -Also, commands that use Windows PowerShell providers do not automatically +Also, commands that use PowerShell providers do not automatically import a module. For example, if you use a command that requires the WSMan: drive, such as the `Get-PSSessionConfiguration` cmdlet, you might need to run the `Import-Module` cmdlet to import the Microsoft.WSMan.Management @@ -90,43 +92,40 @@ other useful information about managing modules. ## How to Install a Module -If you receive a module as a folder with files in it, you need -to install it on your computer before you can use it in Windows -PowerShell. +If you receive a module as a folder with files in it, you need to install it +on your computer before you can use it in PowerShell. -Most modules are installed for you. Windows PowerShell comes with -several preinstalled modules, sometimes called the "core" modules. -On Windows-based computers, if features that are included with the -operating system have cmdlets to manage them, those modules are preinstalled. -When you install a Windows feature, by using, for example, the Add Roles -and Features Wizard in Server Manager, or the Turn Windows features on or off -dialog box in Control Panel, any Windows PowerShell modules that are part -of the feature are installed. Many other modules come in an installer or -Setup program that installs the module. +Most modules are installed for you. PowerShell comes with several preinstalled +modules, sometimes called the "core" modules. On Windows-based computers, if +features that are included with the operating system have cmdlets to manage +them, those modules are preinstalled. When you install a Windows feature, by +using, for example, the Add Roles and Features Wizard in Server Manager, or +the Turn Windows features on or off dialog box in Control Panel, any +PowerShell modules that are part of the feature are installed. Many other +modules come in an installer or Setup program that installs the module. -To install a module folder: -1. Create a Modules directory for the current user if one does not exist. -To create a Modules directory, type: +Create a Modules directory for the current user if one does not exist. To +create a Modules directory, type: ```powershell New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules ``` -2. Copy the entire module folder into the Modules directory. -You can use any method to copy the folder, including Windows -Explorer and Cmd.exe, as well as Windows PowerShell. -In Windows PowerShell use the `Copy-Item` cmdlet. For example, to copy the -MyModule folder from C:\ps-test\MyModule to the Modules directory, type: +Copy the entire module folder into the Modules directory. You can use any +method to copy the folder, including Windows Explorer and Cmd.exe, as well as +PowerShell. In PowerShell use the `Copy-Item` cmdlet. For example, to copy the +MyModule folder from C:\\ps-test\\MyModule to the Modules directory, type: ```powershell -Copy-Item -Path C:\ps-test\MyModule -Destination $HOME\Documents\WindowsPowerShell\Modules +Copy-Item -Path C:\ps-test\MyModule -Destination ` + $HOME\Documents\WindowsPowerShell\Modules ``` You can install a module in any location, but installing your modules in a -default module location makes them easier to manage. For more information about -the default module locations, see the "Module and DSC Resource Locations, -and PSModulePath" section. +default module location makes them easier to manage. For more information +about the default module locations, see the "Module and DSC Resource +Locations, and PSModulePath" section. ## How to Find Installed Modules @@ -138,19 +137,20 @@ Get-Module -ListAvailable ``` To find the modules that have already been imported into your session, -at the Windows PowerShell prompt, type: +at the PowerShell prompt, type: ```powershell Get-Module ``` -For more information about the `Get-Module` cmdlet, see [Get-Module](../Get-Module.md). +For more information about the `Get-Module` cmdlet, see +[Get-Module](../Get-Module.md). ## How to Find the Commands in a Module -Use the `Get-Command` cmdlet to find all available commands. -You can use the parameters of the `Get-Command` cmdlet to filter commands -such as by module, name, and noun. +Use the `Get-Command` cmdlet to find all available commands. You can use the +parameters of the `Get-Command` cmdlet to filter commands such as by module, +name, and noun. To find all commands in a module, type: @@ -164,18 +164,17 @@ For example, to find the commands in the BitsTransfer module, type: Get-Command -Module BitsTransfer ``` -For more information about the `Get-Command` cmdlet, see [Get-Command](../Get-Command.md). +For more information about the `Get-Command` cmdlet, see +[Get-Command](../Get-Command.md). ## How to Get Help for the Commands in a Module -If the module contains Help files for the commands that it exports, -the `Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` -command format that you would use to get help for any command in Windows -PowerShell. +If the module contains Help files for the commands that it exports, the +`Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` +command format that you would use to get help for any command in PowerShell. -Beginning in Windows PowerShell 3.0, you can download Help files for -a module and download updates to the Help files so they are never -obsolete. +Beginning in PowerShell 3.0, you can download Help files for a module and +download updates to the Help files so they are never obsolete. To get help for a commands in a module, type: @@ -195,20 +194,22 @@ To download and install the help files for the commands in a module, type: Update-Help -Module ``` -For more information, see [Get-Help](../Get-Help.md) and [Update-Help](../Update-Help.md). +For more information, see [Get-Help](../Get-Help.md) and +[Update-Help](../Update-Help.md). ## How to Import a Module -You might have to import a module or import a module file. Importing is required -when a module is not installed in the locations specified by the PSModulePath -environment variable ($env:PSModulePath), or the module consists of file, such -as a .dll or .psm1 file, instead of typical module that is delivered as a folder. +You might have to import a module or import a module file. Importing is +required when a module is not installed in the locations specified by the +PSModulePath environment variable ($env:PSModulePath), or the module consists +of file, such as a .dll or .psm1 file, instead of typical module that is +delivered as a folder. -You might also choose to import a module so that you can use the parameters of the -`Import-Module` command, such as the Prefix parameter, which adds a distinctive prefix -to the noun names of all imported commands, or the **NoClobber** parameter, which prevents -the module from adding commands that would hide or replace existing commands in the -session. +You might also choose to import a module so that you can use the parameters of +the `Import-Module` command, such as the Prefix parameter, which adds a +distinctive prefix to the noun names of all imported commands, or the +**NoClobber** parameter, which prevents the module from adding commands that +would hide or replace existing commands in the session. To import modules, use the `Import-Module` cmdlet. @@ -254,8 +255,8 @@ For more information about adding modules to your session, see The `Import-Module` command imports modules into your current Windows PowerShell session. This command affects only the current session. -To import a module into every Windows PowerShell session that you -start, add the `Import-Module` command to your Windows PowerShell +To import a module into every PowerShell session that you +start, add the `Import-Module` command to your PowerShell profile. For more information about profiles, see [about_Profiles](about_Profiles.md). @@ -285,46 +286,42 @@ a module does not uninstall the module. For more information about the ## Module and DSC Resource Locations, and PSModulePath -The following are default locations for Windows PowerShell modules. -Starting in Windows PowerShell 4.0, with the introduction of DSC, a -new default module and DSC resource folder was introduced. For more -information about DSC, see about_DesiredStateConfiguration. +The following are default locations for PowerShell modules. Starting in +PowerShell 4.0, with the introduction of DSC, a new default module and DSC +resource folder was introduced. For more information about DSC, see +about_DesiredStateConfiguration. -System: $pshome\Modules -(%windir%\System32\WindowsPowerShell\v1.0\Modules) -System modules are those that ship with Windows and Windows PowerShell. +- System: $pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) + System modules are those that ship with Windows and PowerShell. -Starting in Windows Powershell 4.0, when Windows PowerShell -Desired State Configuration (DSC) was introduced, DSC resources that are -included with Windows PowerShell are also stored in $pshome\Modules, -in the $pshome\Modules\PSDesiredStateConfiguration\DSCResources -folder. + Starting in PowerShell 4.0, when PowerShell Desired State Configuration + (DSC) was introduced, DSC resources that are included with PowerShell are + also stored in \$pshome\\Modules, in the + \$pshome\\Modules\\PSDesiredStateConfiguration\\DSCResources folder. -Current user: $home\Documents\WindowsPowerShell\Modules -(%UserProfile%\Documents\WindowsPowerShell\Modules) +- Current user: \$home\\Documents\\WindowsPowerShell\\Modules + (%UserProfile%\Documents\WindowsPowerShell\Modules) -or + or -$home\My Documents\WindowsPowerShell\Modules -(%UserProfile%\My Documents\WindowsPowerShell\Modules) -This is the location for user-added modules prior to Windows PowerShell 4.0. + \$home\\My Documents\\WindowsPowerShell\\Modules + (%UserProfile%\My Documents\WindowsPowerShell\Modules) + This is the location for user-added modules prior to PowerShell 4.0. -In Windows PowerShell 4.0 and later releases of Windows PowerShell, -user-added modules and DSC resources are stored in -C:\Program Files\WindowsPowerShell\Modules. Modules and DSC resources -in this location are accessible by all users of the computer. -This change was required because the DSC engine runs as local +In PowerShell 4.0 and later releases of PowerShell, user-added modules and DSC +resources are stored in C:\\Program Files\\WindowsPowerShell\\Modules. Modules +and DSC resources in this location are accessible by all users of the +computer. This change was required because the DSC engine runs as local system, and could not access user-specific paths, such as -$home\Documents\WindowsPowerShell\Modules. +\$home\\Documents\\WindowsPowerShell\\Modules. -Starting in Windows PowerShell 5.0, with the addition of the -PowerShellGet module, and the [PowerShell Gallery](https://www.powershellgallery.com) -of community- and Microsoft-created resources, -the `Install-Module` command installs modules and DSC resources to -C:\Program Files\WindowsPowerShell\Modules by default. +Starting in PowerShell 5.0, with the addition of the PowerShellGet module, and +the [PowerShell Gallery](https://www.powershellgallery.com) of community- and +Microsoft-created resources, the `Install-Module` command installs modules and +DSC resources to C:\\Program Files\\WindowsPowerShell\\Modules by default. -Note: To add or change files in the %Windir%\System32 directory, -start Windows PowerShell with the "Run as administrator" option. +Note: To add or change files in the %Windir%\\System32 directory, start +PowerShell with the "Run as administrator" option. You can change the default module locations on your system by changing the value of the PSModulePath environment variable ($Env:PSModulePath). The @@ -356,7 +353,7 @@ When you add a path to PSModulePath, `Get-Module` and `Import-Module` commands include modules in that path. The value that you set affects only the current session. To make the -change persistent, add the command to your Windows PowerShell profile +change persistent, add the command to your PowerShell profile or use System in Control Panel to change the value of the PSModulePath environment variable in the registry. @@ -369,70 +366,72 @@ For more information about the PSModulePath variable, see ## Modules and Name Conflicts -Name conflicts occur when more than one command in the session -has the same name. Importing a module causes a name conflict when -commands in the module have the same names as commands or items -in the session. +Name conflicts occur when more than one command in the session has the same +name. Importing a module causes a name conflict when commands in the module +have the same names as commands or items in the session. Name conflicts can result in commands being hidden or replaced. ### Hidden -A command is hidden when it is not the command that runs -when you type the command name, but you can run it -by using another method, such as by qualifying the command -name with the name of the module or snap-in in which it + +A command is hidden when it is not the command that runs when you type the +command name, but you can run it by using another method, such as by +qualifying the command name with the name of the module or snap-in in which it originated. ### Replaced -A command is replaced when you cannot run it because -it has been overwritten by a command with the same name. Even -when you remove the module that caused the conflict, you cannot -run a replaced command unless you restart the session. + +A command is replaced when you cannot run it because it has been overwritten +by a command with the same name. Even when you remove the module that caused +the conflict, you cannot run a replaced command unless you restart the +session. `Import-Module` might add commands that hide and replace commands in the current session. Also, commands in your session can hide commands that the module added. -To detect name conflicts, use the **All** parameter of the `Get-Command` cmdlet. -Beginning in Windows PowerShell 3.0, `Get-Command` gets only that commands -that run when you type the command name. The **All** parameter gets all commands -with the specific name in the session. +To detect name conflicts, use the **All** parameter of the `Get-Command` +cmdlet. Beginning in PowerShell 3.0, `Get-Command` gets only that commands +that run when you type the command name. The **All** parameter gets all +commands with the specific name in the session. To prevent name conflicts, use the **NoClobber** or **Prefix** parameters of -the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the names -of imported commands so that they are unique in the session. The **NoClobber** -parameter does not import any commands that would hide or replace existing -commands in the session. - -You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** parameters -of `Import-Module` to select only the commands that you want to import, -and you can exclude commands that cause name conflicts in your session. +the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the +names of imported commands so that they are unique in the session. The +**NoClobber** parameter does not import any commands that would hide or +replace existing commands in the session. + +You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** +parameters of `Import-Module` to select only the commands that you want to +import, and you can exclude commands that cause name conflicts in your +session. Module authors can prevent name conflicts by using the DefaultCommandPrefix -property of the module manifest to add a default prefix to all command -names. The value of the Prefix parameter takes precedence over the value -of DefaultCommandPrefix. +property of the module manifest to add a default prefix to all command names. +The value of the Prefix parameter takes precedence over the value of +DefaultCommandPrefix. -Even if a command is hidden, you can run it by qualifying the command -name with the name of the module or snap-in in which it originated. +Even if a command is hidden, you can run it by qualifying the command name +with the name of the module or snap-in in which it originated. -The Windows PowerShell command precedence rules determine which command -runs when the session includes commands with the same name. +The PowerShell command precedence rules determine which command runs when the +session includes commands with the same name. For example, when a session includes a function and a cmdlet with the same -name, Windows PowerShell runs the function by default. When the session -includes commands of the same type with the same name, such as two cmdlets -with the same name, by default, it runs the most recently added command. +name, PowerShell runs the function by default. When the session includes +commands of the same type with the same name, such as two cmdlets with the +same name, by default, it runs the most recently added command. For more information, including an explanation of the precedence rules and -instructions for running hidden commands, see [about_Command_Precedence](about_Command_Precedence.md). +instructions for running hidden commands, see +[about_Command_Precedence](about_Command_Precedence.md). ## Modules and Snap-ins -You can add commands to your session from modules and snap-ins. Modules -can add all types of commands, including cmdlets, providers, and functions, -and items, such as variables, aliases, and Windows PowerShell drives. -Snap-ins can add only cmdlets and providers. +You can add commands to your session from modules and snap-ins. Modules can +add all types of commands, including cmdlets, providers, and functions, and +items, such as variables, aliases, and PowerShell drives. Snap-ins can add +only cmdlets and providers. Before removing a module or snap-in from your session, use the following commands to determine which commands will be removed. @@ -441,55 +440,52 @@ To find the source of a cmdlet in your session, use the following command format: ```powershell -Get-Command | Format-List -Property verb, noun, pssnapin, module +Get-Command | Format-List -Property verb,noun,pssnapin,module ``` For example, to find the source of the `Get-Date` cmdlet, type: ```powershell -Get-Command Get-Date | Format-List -Property verb, noun, pssnapin, module +Get-Command Get-Date | Format-List -Property verb,noun,pssnapin,module ``` -For more information about Windows PowerShell snap-ins, see [about_PSSnapins](about_PSSnapins.md). +For more information about PowerShell snap-ins, see +[about_PSSnapins](about_PSSnapins.md). ## Module-related Warnings and Errors -The commands that a module exports should follow the Windows PowerShell -command naming rules. If the module that you import exports cmdlets or -functions that have unapproved verbs in their names, the `Import-Module` -cmdlet displays the following warning message. +The commands that a module exports should follow the PowerShell command naming +rules. If the module that you import exports cmdlets or functions that have +unapproved verbs in their names, the `Import-Module` cmdlet displays the +following warning message. -WARNING: Some imported command names include unapproved verbs -which might make them less discoverable. Use the Verbose parameter -for more detail or type `Get-Verb` to see the list of approved verbs. +WARNING: Some imported command names include unapproved verbs which might make +them less discoverable. Use the Verbose parameter for more detail or type +`Get-Verb` to see the list of approved verbs. This message is only a warning. The complete module is still imported, -including the non-conforming commands. Although the message is displayed -to module users, the naming problem should be fixed by the module author. +including the non-conforming commands. Although the message is displayed to +module users, the naming problem should be fixed by the module author. -To suppress the warning message, use the **DisableNameChecking** parameter -of the `Import-Module` cmdlet. +To suppress the warning message, use the **DisableNameChecking** parameter of +the `Import-Module` cmdlet. ## Built-in Modules and Snap-ins -In Windows PowerShell 2.0 and in older-style host programs in Windows -PowerShell 3.0 and later, the core commands that are installed with -Windows PowerShell are packaged in snap-ins that are added automatically -to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that -implement the InitialSessionState.CreateDefault2 initial session state API -- -the core commands are packaged in modules. The default is -Microsoft.PowerShell.Core, which is always a snap-in. +In PowerShell 2.0 and in older-style host programs in PowerShell 3.0 and +later, the core commands that are installed with PowerShell are packaged in +snap-ins that are added automatically to every PowerShell session. -The Microsoft.PowerShell.Core snap-in is added to every session by -default. Modules are loaded automatically on first-use. +Beginning in PowerShell 3.0, for host programs that implement the +`InitialSessionState.CreateDefault2` initial session state API the +Microsoft.PowerShell.Core snap-in is added to every session by default. +Modules are loaded automatically on first-use. -NOTE: Remote sessions, including sessions that are started by using -the New-PSSession cmdlet, are older-style sessions in which the built-in +NOTE: Remote sessions, including sessions that are started by using the +`New-PSSession` cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. -The following modules (or snap-ins) are installed with Windows PowerShell. +The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics @@ -509,13 +505,13 @@ The following modules (or snap-ins) are installed with Windows PowerShell. ## Logging Module Events -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets -and functions in Windows PowerShell modules and snap-ins by setting the -LogPipelineExecutionDetails property of modules and snap-ins to $True. -You can also use a Group Policy setting, Turn on Module Logging, -to enable module logging in all Windows PowerShell sessions. -For more information, see [about_EventLogs](about_EventLogs.md) -and [about_Group_Policy_Settings](about_Group_Policy_Settings.md). +Beginning in PowerShell 3.0, you can record execution events for the cmdlets +and functions in PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to \$True. You can +also use a Group Policy setting, Turn on Module Logging, to enable module +logging in all PowerShell sessions. For more information, see +[about_EventLogs](about_EventLogs.md) and +[about_Group_Policy_Settings](about_Group_Policy_Settings.md). ## See Also diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Jobs.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Jobs.md index 2791902df4b1..c90d48ee71a1 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Jobs.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,49 +7,41 @@ title: about_Jobs --- # About Jobs -## about_Jobs +## SHORT DESCRIPTION - -# SHORT DESCRIPTION - -Provides information about how Windows PowerShell background jobs run a +Provides information about how PowerShell background jobs run a command or expression in the background without interacting with the current session. -# LONG DESCRIPTION +## LONG DESCRIPTION -This topic explains how to run background jobs in Windows PowerShell on a +This topic explains how to run background jobs in PowerShell on a local computer. For information about running background jobs on remote -computers, see about_Remote_Jobs. +computers, see [about_Remote_Jobs](about_Remote_Jobs.md). When you start a background job, the command prompt returns immediately, even if the job takes an extended time to complete. You can continue to work in the session without interruption while the job runs. -# THE JOB CMDLETS - - -Start-Job Starts a background job on a local computer. - -Get-Job Gets the background jobs that were started in the current -session. - -Receive-Job Gets the results of background jobs. - -Stop-Job Stops a background job. - -Wait-Job Suppresses the command prompt until one or all jobs are -complete. - -Remove-Job Deletes a background job. - -Invoke-Command The AsJob parameter runs any command as a background job on a -remote computer. You can also use Invoke-Command to run -any job command remotely, including a Start-Job command. - -# HOW TO START A JOB ON THE LOCAL COMPUTER - +## THE JOB CMDLETS + +|Cmdlet |Description | +|----------------|-------------------------------------------------------| +|`Start-Job` |Starts a background job on a local computer. | +|`Get-Job` |Gets the background jobs that were started in the | +| |current session. | +|`Receive-Job` |Gets the results of background jobs. | +|`Stop-Job` |Stops a background job. | +|`Wait-Job` |Suppresses the command prompt until one or all jobs are| +| |complete. | +|`Remove-Job` |Deletes a background job. | +|`Invoke-Command`|The AsJob parameter runs any command as a background | +| |job on a remote computer. You can also use | +| |`Invoke-Command` to run any job command remotely, | +| |including a Start-Job command. | + +## HOW TO START A JOB ON THE LOCAL COMPUTER To start a background job on the local computer, use the Start-Job cmdlet. @@ -57,251 +49,279 @@ cmdlet. To write a Start-Job command, enclose the command that the job runs in braces ( { } ). Use the ScriptBlock parameter to specify the command. -The following command starts a background job that runs a Get-Process +The following command starts a background job that runs a `Get-Process` command on the local computer. +```powershell Start-Job -ScriptBlock {Get-Process} +``` -The Start-Job command returns an object that represents the job. The job +The `Start-Job` command returns an object that represents the job. The job object contains useful information about the job, but it does not contain the job results. Save the job object in a variable, and then use it with the other Job cmdlets to manage the background job. The following command starts a job -object and saves the resulting job object in the $job variable. +object and saves the resulting job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-Process} +``` -You can also use the Get-Job cmdlet to get objects that represent the jobs -started in the current session. Get-Job returns the same job object that +You can also use the `Get-Job` cmdlet to get objects that represent the jobs +started in the current session. `Get-Job` returns the same job object that Start-Job returns. -# GETTING JOB OBJECTS - +## GETTING JOB OBJECTS To get object that represent the background jobs that were started in the -current session, use the Get-Job cmdlet. Without parameters, Get-Job +current session, use the `Get-Job` cmdlet. Without parameters, `Get-Job` returns all of the jobs that were started in the current session. For example, the following command gets the jobs in the current session. +```powershell PS C:> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Running True localhost Get-Process +``` You can also save the job object in a variable and use it to represent the job in a later command. The following command gets the job with ID 1 and -saves it in the $job variable. +saves it in the \$job variable. +```powershell $job = Get-Job -Id 1 +``` The job object contains the state of the job, which indicates whether the job has finished. A finished job has a state of "Complete" or "Failed". A job might also be blocked or running. +```powershell Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Complete True localhost Get-Process +``` -# GETTING THE RESULTS OF A JOB - +## GETTING THE RESULTS OF A JOB When you run a background job, the results do not appear immediately. Instead, the Start-Job cmdlet returns a job object that represents the job, but it does not contain the results. To get the results of a -background job, use the Receive-Job cmdlet. +background job, use the `Receive-Job` cmdlet. -The following command uses the Receive-Job cmdlet to get the results of -the job. It uses a job object saved in the $job variable to identify the +The following command uses the `Receive-Job` cmdlet to get the results of +the job. It uses a job object saved in the \$job variable to identify the job. +```powershell Receive-Job -Job $job +``` The Receive-Job cmdlet returns the results of the job. +``` Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -668 7 2672 6168 104 32.26 488 csrss + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 668 7 2672 6168 104 32.26 488 csrss # ... +``` +You can also save the results of a job in a variable. The following command +saves the results of the job in the \$job variable to the \$results variable. -You can also save the results of a job in a variable. The following -command saves the results of the job in the $job variable to the $results -variable. - +```powershell $results = Receive-Job -Job $job +``` And, you can save the results of the job in a file by using the redirection operator (>) or the Out-File cmdlet. The following command uses the -redirection operator to save the results of the job in the $job variable in +redirection operator to save the results of the job in the \$job variable in the Results.txt file. +```powershell Receive-Job -Job $job > results.txt +``` -# GETTING AND KEEPING PARTIAL JOB RESULTS - +## GETTING AND KEEPING PARTIAL JOB RESULTS The Receive-Job cmdlet gets the results of a background job. If the -job is complete, Receive-Job gets all job results. If the job is still +job is complete, `Receive-Job` gets all job results. If the job is still running, Receive-Job gets the results that have been generated thus far. -You can run Receive-Job commands again to get the remaining results. +You can run `Receive-Job` commands again to get the remaining results. -When Receive-Job returns results, by default, it deletes those results from -the cache where job results are stored. If you run another Receive-Job +When `Receive-Job` returns results, by default, it deletes those results from +the cache where job results are stored. If you run another `Receive-Job` command, you get only the results that are not yet received. -The following commands show the results of Receive-Job commands run +The following commands show the results of `Receive-Job` commands run before the job is complete. +```powershell C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -To prevent Receive-Job from deleting the job results that it has -returned, use the Keep parameter. As a result, Receive-Job returns all + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +To prevent `Receive-Job` from deleting the job results that it has +returned, use the **Keep** parameter. As a result, `Receive-Job` returns all of the results that have been generated until that time. The following commands show the effect of using the Keep parameter on a job that is not yet complete. +```powershell C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -# WAITING FOR THE RESULTS - - -If you run a command that takes a long time to complete, you can use -the properties of the job object to determine when the job is complete. -The following command uses the Get-Job object to get all of the background -jobs in the current session. - + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +## WAITING FOR THE RESULTS + +If you run a command that takes a long time to complete, you can use the +properties of the job object to determine when the job is complete. The +following command uses the `Get-Job` object to get all of the background jobs +in the current session. + +```powershell Get-Job +``` The results appear in a table. The status of the job appears in the State column. -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Complete True localhost Get-Process -2 Job2 BackgroundJob Running True localhost Get-EventLog -Log Syst... -3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Recurse - -In this case, the State property reveals that Job 2 is still running. If -you were to use the Receive-Job cmdlet to get the job results now, the -results would be incomplete. You can use the Receive-Job cmdlet -repeatedly to get all of the results. By default, each time you use it, -you get only the results that were not already received, but you can use -the Keep parameter of the Receive-Job cmdlet to retain the results, even -though they were already received. +``` +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Complete True localhost Get-Process +2 Job2 BackgroundJob Running True localhost Get-EventLog -Log ... +3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Re... +``` + +In this case, the State property reveals that Job 2 is still running. If you +were to use the `Receive-Job` cmdlet to get the job results now, the results +would be incomplete. You can use the `Receive-Job` cmdlet repeatedly to get +all of the results. By default, each time you use it, you get only the results +that were not already received, but you can use the Keep parameter of the +Receive-Job cmdlet to retain the results, even though they were already +received. You can write the partial results to a file and then append newer results as they arrive or you can wait and check the state of the job later. -You can use the Wait parameter of the Receive-Job cmdlet, which +You can use the Wait parameter of the `Receive-Job` cmdlet, which does not return the command prompt until the job is complete and all results are available. -You can also use the Wait-Job cmdlet to wait for any or all of the results -of the job. Wait-Job lets you wait for a particular job, for all jobs, or +You can also use the `Wait-Job` cmdlet to wait for any or all of the results +of the job. `Wait-Job` lets you wait for a particular job, for all jobs, or for any of the jobs to be completed. -The following command uses the Wait-Job cmdlet to wait for a job with -# ID 10. - +The following command uses the Wait-Job cmdlet to wait for a job with ID 10. +```powershell Wait-Job -ID 10 +``` -As a result, the Windows PowerShell prompt is suppressed until the job -is completed. +As a result, the PowerShell prompt is suppressed until the job is completed. You can also wait for a predetermined period of time. This command uses the Timeout parameter to limit the wait to 120 seconds. When the time expires, the command prompt returns, but the job continues to run in the background. +```powershell Wait-Job -ID 10 -Timeout 120 +``` -# STOPPING A JOB +## STOPPING A JOB - -To stop a background job, use the Stop-Job cmdlet. The following command +To stop a background job, use the `Stop-Job` cmdlet. The following command starts a job to get every entry in the System event log. It saves the job -object in the $job variable. +object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-EventLog -Log System} +``` The following command stops the job. It uses a pipeline operator (|) to -send the job in the $job variable to Stop-Job. +send the job in the \$job variable to `Stop-Job`. +```powershell $job | Stop-Job +``` -# DELETING A JOB - +## DELETING A JOB -To delete a background job, use the Remove-Job cmdlet. The following -command deletes the job in the $job variable. +To delete a background job, use the `Remove-Job` cmdlet. The following +command deletes the job in the \$job variable. +```powershell Remove-Job -Job $job +``` -# INVESTIGATING A FAILED JOB - +## INVESTIGATING A FAILED JOB To find out why a job failed, use the Reason subproperty of the job object. The following command starts a job without the required credentials. It -saves the job object in the $job variable. +saves the job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {New-Item -Path HKLM:\Software\MyCompany} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:\S... +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:... +``` The following command uses the Reason property to find the error that caused the job to fail. +```powershell $job.ChildJobs[0].JobStateInfo.Reason +``` In this case, the job failed because the remote computer required explicit credentials to run the command. The value of the Reason property is: -Connecting to remote server failed with the following error -message : Access is denied. +Connecting to remote server failed with the following error message : Access +is denied. -# SEE ALSO +## SEE ALSO [about_Remote_Jobs](about_Remote_Jobs.md) @@ -311,17 +331,16 @@ message : Access is denied. [about_PSSessions](about_PSSessions.md) -Start-Job - -Get-Job +[Start-Job](../Start-Job.md) -Receive-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Receive-Job](../Receive-Job.md) -Wait-Job +[Stop-Job](../Stop-Job.md) -Remove-Job +[Wait-Job](../Wait-Job.md) -Invoke-Command +[Remove-Job](../Remove-Job.md) +[Invoke-Command](../../Microsoft.PowerShell.Core/Invoke-Command.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Methods.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Methods.md index 527d296ea180..a32eb5d38a92 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Methods.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Methods.md @@ -7,188 +7,202 @@ title: about_Methods --- # About methods -## about_methods - ## SHORT DESCRIPTION -Describes how to use methods to perform actions on objects in Windows PowerShell? +Describes how to use methods to perform actions on objects in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses objects to represent the items in data stores or the state of the computer. For example, FileInfo objects represent the files in file system drives and ProcessInfo objects represent the processes on the computer. -Objects have properties, which store data about the object, and methods that let you change the object. +PowerShell uses objects to represent the items in data stores or the state of +the computer. For example, FileInfo objects represent the files in file system +drives and ProcessInfo objects represent the processes on the computer. -A "method" is a set of instructions that specify an action you can perform on the object. For example, the FileInfo object includes the CopyTo method that copies the file that the FileInfo object represents. +Objects have properties, which store data about the object, and methods that +let you change the object. -To get the methods of any object, use the Get-Member cmdlet. Use its MemberType property with a value of "Method". The following command gets the methods of process objects. +A "method" is a set of instructions that specify an action you can perform on +the object. For example, the `FileInfo` object includes the `CopyTo` method that +copies the file that the `FileInfo` object represents. +To get the methods of any object, use the `Get-Member` cmdlet. Use its +**MemberType** property with a value of "Method". The following command gets +the methods of process objects. -``` +```powershell PS C:\> Get-Process | Get-Member -MemberType Method ``` +```output +TypeName: System.Diagnostics.Process - +Name MemberType Definition +---- ---------- ---------- +BeginErrorReadLine Method System.Void BeginErrorReadLine() +BeginOutputReadLine Method System.Void BeginOutputReadLine() +... +Kill Method System.Void Kill() +Refresh Method System.Void Refresh() +Start Method bool Start() +ToString Method string ToString() +WaitForExit Method bool WaitForExit(int milliseconds), ... +WaitForInputIdle Method bool WaitForInputIdle(int millisecon... ``` -TypeName: System.Diagnostics.Process - -Name MemberType Definition ----- ---------- ---------- -BeginErrorReadLine Method System.Void BeginErrorReadLine() -BeginOutputReadLine Method System.Void BeginOutputReadLine() -... -Kill Method System.Void Kill() -Refresh Method System.Void Refresh() -Start Method bool Start() -ToString Method string ToString() -WaitForExit Method bool WaitForExit(int milliseconds), System.Void WaitForExit() -WaitForInputIdle Method bool WaitForInputIdle(int milliseconds), bool WaitForInputIdle() -``` - - -To perform or "invoke" a method of an object, type a dot (.), the method name, and a set of parentheses "()". If the method has arguments, place the argument values inside the parentheses. The parentheses are required for every method call, even when there are no arguments. -For example, the following command invokes the Kill method of processes to end the Notepad process on the computer. As a result, the instance of Notepad closes. (The Get-Process command is enclosed in parentheses to insure that it runs before the Kill method is invoked. +To perform or "invoke" a method of an object, type a dot (.), the method name, +and a set of parentheses "()". If the method has arguments, place the argument +values inside the parentheses. The parentheses are required for every method +call, even when there are no arguments. +For example, the following command invokes the Kill method of processes to end +the Notepad process on the computer. As a result, the instance of Notepad +closes. (The `Get-Process` command is enclosed in parentheses to insure that +it runs before the Kill method is invoked. -``` +```powershell (Get-Process Notepad).Kill() ``` +Another very useful process is the Split method of strings. The split method +takes a delimiter character argument that tells the method where to split the +string. -Another very useful process is the Split method of strings. The split method takes a delimiter character argument that tells the method where to split the string. - - -``` -PS C:\> $a = "Try-Catch-Finally" -PS C:\> $a.Split("-") -Try -Catch +```powershell +PS C:\> $a = "Try-Catch-Finally" +PS C:\> $a.Split("-") +Try +Catch Finally ``` +As shown in the previous examples, you can invoke a method on an object that +you get by using a command or an object in a variable. -As shown in the previous examples, you can invoke a method on an object that you get by using a command or an object in a variable. - -Starting in Windows PowerShell 4.0, method invocation by using dynamic method names is supported. - +Starting in PowerShell 4.0, method invocation by using dynamic method names is +supported. ### LEARNING ABOUT METHODS -To find definitions of the methods of an object, go to help topic for the object type in MSDN and look for its methods page. For example, the following page describes the methods of process objects (System.Diagnostics.Process). - - -``` -http://msdn.microsoft.com/library/system.diagnostics.process_methods -``` +To find definitions of the methods of an object, go to help topic for the +object type in MSDN and look for its methods page. For example, the following +page describes the methods of process objects +[System.Diagnostics.Process](http://msdn.microsoft.com/library/system.diagnostics.process_methods). -To determine the arguments of a method, review the method definition, which is like the syntax diagram of a Windows PowerShell cmdlet. +To determine the arguments of a method, review the method definition, which is +like the syntax diagram of a PowerShell cmdlet. -A method definition might have one or more method signatures, which are like the parameter sets of Windows PowerShell cmdlets. The signatures show all of the valid formats of commands to invoke the method. - -For example, the CopyTo method of the FileInfo class contains the following two method signatures: - - -``` -1. CopyTo(String destFileName) -2. CopyTo(String destFileName, Boolean overwrite) -``` +A method definition might have one or more method signatures, which are like +the parameter sets of PowerShell cmdlets. The signatures show all of the valid +formats of commands to invoke the method. +For example, the `CopyTo` method of the `FileInfo` class contains the following +two method signatures: -The first method signature takes the destination file name (and a path). The following example use The first CopyTo method to copy the Final.txt file to the C:\Bin directory. + CopyTo(String destFileName) + CopyTo(String destFileName, Boolean overwrite) +The first method signature takes the destination file name (and a path). The +following example use The first `CopyTo` method to copy the Final.txt file to +the C:\\Bin directory. -``` +```powershell (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt") ``` +The second method signature take a destination file name and a Boolean value +that determines whether the destination file should be overwritten, if it +already exists. -The second method signature take a destination file name and a Boolean value that determines whether the destination file should be overwritten, if it already exists. - -The following example use The second CopyTo method to copy the Final.txt file to the C:\Bin directory, and to overwrite existing files. - +The following example use The second `CopyTo` method to copy the Final.txt file +to the C:\\Bin directory, and to overwrite existing files. ``` (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` - - ### METHODS OF SCALAR OBJECTS AND COLLECTIONS -The methods of one ("scalar") object of a particular type are often different from the methods of a collection of objects of the same type. -For example, every process has a Kill method, but a collection of processes does not have a Kill method. +The methods of one ("scalar") object of a particular type are often different +from the methods of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing methods of scalar objects and collections. +For example, every process has a `Kill` method, but a collection of processes +does not have a Kill method. -Beginning in Windows PowerShell 4.0, collection filtering by using a method syntax is supported. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing methods of scalar objects and collections. -If you submit a collection, but request a method that exists only on single ("scalar") objects, Windows invokes the method on every object in the collection. +Beginning in PowerShell 4.0, collection filtering by using a method syntax is +supported. -If the method exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you submit a collection, but request a method that exists only on single +("scalar") objects, PowerShell invokes the method on every object in the +collection. -This feature also works on properties of scalar objects and collections. For more information, see about_Properties. +If the method exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on properties of scalar objects and collections. For +more information, see [about_Properties](about_Properties.md). ### EXAMPLES -The following example runs the Kill method of individual process objects on a collection of process objects. This example works only on Windows PowerShell 3.0 and later versions of Windows PowerShell. -The first command starts three instances of the Notepad process. The second command uses the Get-Process command to get all three instance of the Notepad process and save them in the $p variable. +The following example runs the Kill method of individual process objects on a +collection of process objects. This example works only on PowerShell 3.0 and +later versions of PowerShell. +The first command starts three instances of the Notepad process. The second +command uses the `Get-Process` command to get all three instance of the Notepad +process and save them in the \$p variable. -``` -PS C:\> Notepad; Notepad; Notepad +```powershell +PS C:\> Notepad; Notepad; Notepad PS C:\> $p = Get-Process Notepad ``` +The third command uses the Count property of all collections to verify that +there are three processes in the \$p variable. -The third command uses the Count property of all collections to verify that there are three processes in the $p variable. - - -``` -PS C:\> $p.Count +```powershell +PS C:\> $p.Count 3 ``` +The fourth command runs the Kill method on all three processes in the \$p +variable. -The fourth command runs the Kill method on all three processes in the $p variable. - -This command works even though a collection of processes does not have a Kill method. - +This command works even though a collection of processes does not have a `Kill` +method. ``` PS C:\> $p.Kill() ``` +The fifth command uses the Get-Process command to confirm that the `Kill` +command worked. -The fifth command uses the Get-Process command to confirm that the Kill command worked. - - +```powershell +PS C:\> Get-Process Notepad +Get-Process : Cannot find a process with the name "notepad". Verify the proc +ess name and call the cmdlet again. +At line:1 char:12 ++ get-process <<<< notepad + + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process] +, ProcessCommandException + + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShel +l.Commands.GetProcessCommand ``` -PS C:\> Get-Process Notepad -Get-Process : Cannot find a process with the name "notepad". Verify the process name and call the cmdlet again. -At line:1 char:12 -+ get-process <<<< notepad - + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process], ProcessCommandException - + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.Commands.GetProcessCommand -``` - -To perform the same task on Windows PowerShell 2.0, use the Foreach-Object cmdlet to run the method on each object in the collection. +To perform the same task on PowerShell 2.0, use the `Foreach-Object` cmdlet to +run the method on each object in the collection. - -``` +```powershell PS C:\> $p | Foreach-Object {$_.Kill()} ``` - - ## SEE ALSO [about_Objects](about_Objects.md) [about_Properties](about_Properties.md) -Get-Member - +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md index 6d1f8847f78e..931280614067 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,51 +10,53 @@ title: about_Modules ## Short Description -Explains how to install, import, and use Windows PowerShell modules. +Explains how to install, import, and use PowerShell modules. ## Long Description -A module is a package that contains Windows PowerShell commands, such as -cmdlets, providers, functions, workflows, variables, and aliases. +A module is a package that contains PowerShell commands, such as cmdlets, +providers, functions, workflows, variables, and aliases. -People who write commands can use modules to organize their commands and -share them with others. People who receive modules can add the commands -in the modules to their Windows PowerShell sessions and use them just like -the built-in commands. +People who write commands can use modules to organize their commands and share +them with others. People who receive modules can add the commands in the +modules to their PowerShell sessions and use them just like the built-in +commands. -This topic explains how to use Windows PowerShell modules. -For information about how to write Windows PowerShell modules, see -[Writing a Windows PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) in the MSDN library. +This topic explains how to use PowerShell modules. For information about how +to write PowerShell modules, see [Writing a PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) +in the MSDN library. ## What Is a Module? -A module is a package of commands. All cmdlets and providers in your -session are added by a module or a snap-in. +A module is a package of commands. All cmdlets and providers in your session +are added by a module or a snap-in. ## Module Auto-Loading -Beginning in Windows PowerShell 3.0, Windows PowerShell imports -modules automatically the first time that you run any command in -an installed module. You can now use the commands in a module -without any set-up or profile configuration, so there's no need to -manage modules after you install them on your computer. +Beginning in PowerShell 3.0, PowerShell imports modules automatically the +first time that you run any command in an installed module. You can now use +the commands in a module without any set-up or profile configuration, so +there's no need to manage modules after you install them on your computer. -The commands in a module are also easier to find. The `Get-Command` cmdlet -now gets all commands in all installed modules, even if they are not yet -in the session, so you can find a command and use it without importing. +The commands in a module are also easier to find. The `Get-Command` cmdlet now +gets all commands in all installed modules, even if they are not yet in the +session, so you can find a command and use it without importing. Any of the following commands will import a module into your session. ### Run the Command + ```powershell Get-Mailbox -Identity Chris ``` ### Get the Command + ```powershell Get-Command Get-Mailbox ``` ### Get Help for the Command + ```powershell Get-Help Get-Mailbox ``` @@ -66,7 +68,7 @@ Only modules that are stored in the location specified by the PSModulePath environment variable are automatically imported. Modules in other locations must be imported by running the `Import-Module` cmdlet. -Also, commands that use Windows PowerShell providers do not automatically +Also, commands that use PowerShell providers do not automatically import a module. For example, if you use a command that requires the WSMan: drive, such as the `Get-PSSessionConfiguration` cmdlet, you might need to run the `Import-Module` cmdlet to import the Microsoft.WSMan.Management @@ -90,43 +92,40 @@ other useful information about managing modules. ## How to Install a Module -If you receive a module as a folder with files in it, you need -to install it on your computer before you can use it in Windows -PowerShell. +If you receive a module as a folder with files in it, you need to install it +on your computer before you can use it in PowerShell. -Most modules are installed for you. Windows PowerShell comes with -several preinstalled modules, sometimes called the "core" modules. -On Windows-based computers, if features that are included with the -operating system have cmdlets to manage them, those modules are preinstalled. -When you install a Windows feature, by using, for example, the Add Roles -and Features Wizard in Server Manager, or the Turn Windows features on or off -dialog box in Control Panel, any Windows PowerShell modules that are part -of the feature are installed. Many other modules come in an installer or -Setup program that installs the module. +Most modules are installed for you. PowerShell comes with several preinstalled +modules, sometimes called the "core" modules. On Windows-based computers, if +features that are included with the operating system have cmdlets to manage +them, those modules are preinstalled. When you install a Windows feature, by +using, for example, the Add Roles and Features Wizard in Server Manager, or +the Turn Windows features on or off dialog box in Control Panel, any +PowerShell modules that are part of the feature are installed. Many other +modules come in an installer or Setup program that installs the module. -To install a module folder: -1. Create a Modules directory for the current user if one does not exist. -To create a Modules directory, type: +Create a Modules directory for the current user if one does not exist. To +create a Modules directory, type: ```powershell New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules ``` -2. Copy the entire module folder into the Modules directory. -You can use any method to copy the folder, including Windows -Explorer and Cmd.exe, as well as Windows PowerShell. -In Windows PowerShell use the `Copy-Item` cmdlet. For example, to copy the -MyModule folder from C:\ps-test\MyModule to the Modules directory, type: +Copy the entire module folder into the Modules directory. You can use any +method to copy the folder, including Windows Explorer and Cmd.exe, as well as +PowerShell. In PowerShell use the `Copy-Item` cmdlet. For example, to copy the +MyModule folder from C:\\ps-test\\MyModule to the Modules directory, type: ```powershell -Copy-Item -Path C:\ps-test\MyModule -Destination $HOME\Documents\WindowsPowerShell\Modules +Copy-Item -Path C:\ps-test\MyModule -Destination ` + $HOME\Documents\WindowsPowerShell\Modules ``` You can install a module in any location, but installing your modules in a -default module location makes them easier to manage. For more information about -the default module locations, see the "Module and DSC Resource Locations, -and PSModulePath" section. +default module location makes them easier to manage. For more information +about the default module locations, see the "Module and DSC Resource +Locations, and PSModulePath" section. ## How to Find Installed Modules @@ -138,19 +137,20 @@ Get-Module -ListAvailable ``` To find the modules that have already been imported into your session, -at the Windows PowerShell prompt, type: +at the PowerShell prompt, type: ```powershell Get-Module ``` -For more information about the `Get-Module` cmdlet, see [Get-Module](../Get-Module.md). +For more information about the `Get-Module` cmdlet, see +[Get-Module](../Get-Module.md). ## How to Find the Commands in a Module -Use the `Get-Command` cmdlet to find all available commands. -You can use the parameters of the `Get-Command` cmdlet to filter commands -such as by module, name, and noun. +Use the `Get-Command` cmdlet to find all available commands. You can use the +parameters of the `Get-Command` cmdlet to filter commands such as by module, +name, and noun. To find all commands in a module, type: @@ -164,18 +164,17 @@ For example, to find the commands in the BitsTransfer module, type: Get-Command -Module BitsTransfer ``` -For more information about the `Get-Command` cmdlet, see [Get-Command](../Get-Command.md). +For more information about the `Get-Command` cmdlet, see +[Get-Command](../Get-Command.md). ## How to Get Help for the Commands in a Module -If the module contains Help files for the commands that it exports, -the `Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` -command format that you would use to get help for any command in Windows -PowerShell. +If the module contains Help files for the commands that it exports, the +`Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` +command format that you would use to get help for any command in PowerShell. -Beginning in Windows PowerShell 3.0, you can download Help files for -a module and download updates to the Help files so they are never -obsolete. +Beginning in PowerShell 3.0, you can download Help files for a module and +download updates to the Help files so they are never obsolete. To get help for a commands in a module, type: @@ -195,20 +194,22 @@ To download and install the help files for the commands in a module, type: Update-Help -Module ``` -For more information, see [Get-Help](../Get-Help.md) and [Update-Help](../Update-Help.md). +For more information, see [Get-Help](../Get-Help.md) and +[Update-Help](../Update-Help.md). ## How to Import a Module -You might have to import a module or import a module file. Importing is required -when a module is not installed in the locations specified by the PSModulePath -environment variable ($env:PSModulePath), or the module consists of file, such -as a .dll or .psm1 file, instead of typical module that is delivered as a folder. +You might have to import a module or import a module file. Importing is +required when a module is not installed in the locations specified by the +PSModulePath environment variable ($env:PSModulePath), or the module consists +of file, such as a .dll or .psm1 file, instead of typical module that is +delivered as a folder. -You might also choose to import a module so that you can use the parameters of the -`Import-Module` command, such as the Prefix parameter, which adds a distinctive prefix -to the noun names of all imported commands, or the **NoClobber** parameter, which prevents -the module from adding commands that would hide or replace existing commands in the -session. +You might also choose to import a module so that you can use the parameters of +the `Import-Module` command, such as the Prefix parameter, which adds a +distinctive prefix to the noun names of all imported commands, or the +**NoClobber** parameter, which prevents the module from adding commands that +would hide or replace existing commands in the session. To import modules, use the `Import-Module` cmdlet. @@ -254,8 +255,8 @@ For more information about adding modules to your session, see The `Import-Module` command imports modules into your current Windows PowerShell session. This command affects only the current session. -To import a module into every Windows PowerShell session that you -start, add the `Import-Module` command to your Windows PowerShell +To import a module into every PowerShell session that you +start, add the `Import-Module` command to your PowerShell profile. For more information about profiles, see [about_Profiles](about_Profiles.md). @@ -285,46 +286,42 @@ a module does not uninstall the module. For more information about the ## Module and DSC Resource Locations, and PSModulePath -The following are default locations for Windows PowerShell modules. -Starting in Windows PowerShell 4.0, with the introduction of DSC, a -new default module and DSC resource folder was introduced. For more -information about DSC, see about_DesiredStateConfiguration. +The following are default locations for PowerShell modules. Starting in +PowerShell 4.0, with the introduction of DSC, a new default module and DSC +resource folder was introduced. For more information about DSC, see +about_DesiredStateConfiguration. -System: $pshome\Modules -(%windir%\System32\WindowsPowerShell\v1.0\Modules) -System modules are those that ship with Windows and Windows PowerShell. +- System: $pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) + System modules are those that ship with Windows and PowerShell. -Starting in Windows Powershell 4.0, when Windows PowerShell -Desired State Configuration (DSC) was introduced, DSC resources that are -included with Windows PowerShell are also stored in $pshome\Modules, -in the $pshome\Modules\PSDesiredStateConfiguration\DSCResources -folder. + Starting in PowerShell 4.0, when PowerShell Desired State Configuration + (DSC) was introduced, DSC resources that are included with PowerShell are + also stored in \$pshome\\Modules, in the + \$pshome\\Modules\\PSDesiredStateConfiguration\\DSCResources folder. -Current user: $home\Documents\WindowsPowerShell\Modules -(%UserProfile%\Documents\WindowsPowerShell\Modules) +- Current user: \$home\\Documents\\WindowsPowerShell\\Modules + (%UserProfile%\Documents\WindowsPowerShell\Modules) -or + or -$home\My Documents\WindowsPowerShell\Modules -(%UserProfile%\My Documents\WindowsPowerShell\Modules) -This is the location for user-added modules prior to Windows PowerShell 4.0. + \$home\\My Documents\\WindowsPowerShell\\Modules + (%UserProfile%\My Documents\WindowsPowerShell\Modules) + This is the location for user-added modules prior to PowerShell 4.0. -In Windows PowerShell 4.0 and later releases of Windows PowerShell, -user-added modules and DSC resources are stored in -C:\Program Files\WindowsPowerShell\Modules. Modules and DSC resources -in this location are accessible by all users of the computer. -This change was required because the DSC engine runs as local +In PowerShell 4.0 and later releases of PowerShell, user-added modules and DSC +resources are stored in C:\\Program Files\\WindowsPowerShell\\Modules. Modules +and DSC resources in this location are accessible by all users of the +computer. This change was required because the DSC engine runs as local system, and could not access user-specific paths, such as -$home\Documents\WindowsPowerShell\Modules. +\$home\\Documents\\WindowsPowerShell\\Modules. -Starting in Windows PowerShell 5.0, with the addition of the -PowerShellGet module, and the [PowerShell Gallery](https://www.powershellgallery.com) -of community- and Microsoft-created resources, -the `Install-Module` command installs modules and DSC resources to -C:\Program Files\WindowsPowerShell\Modules by default. +Starting in PowerShell 5.0, with the addition of the PowerShellGet module, and +the [PowerShell Gallery](https://www.powershellgallery.com) of community- and +Microsoft-created resources, the `Install-Module` command installs modules and +DSC resources to C:\\Program Files\\WindowsPowerShell\\Modules by default. -Note: To add or change files in the %Windir%\System32 directory, -start Windows PowerShell with the "Run as administrator" option. +Note: To add or change files in the %Windir%\\System32 directory, start +PowerShell with the "Run as administrator" option. You can change the default module locations on your system by changing the value of the PSModulePath environment variable ($Env:PSModulePath). The @@ -356,7 +353,7 @@ When you add a path to PSModulePath, `Get-Module` and `Import-Module` commands include modules in that path. The value that you set affects only the current session. To make the -change persistent, add the command to your Windows PowerShell profile +change persistent, add the command to your PowerShell profile or use System in Control Panel to change the value of the PSModulePath environment variable in the registry. @@ -369,70 +366,72 @@ For more information about the PSModulePath variable, see ## Modules and Name Conflicts -Name conflicts occur when more than one command in the session -has the same name. Importing a module causes a name conflict when -commands in the module have the same names as commands or items -in the session. +Name conflicts occur when more than one command in the session has the same +name. Importing a module causes a name conflict when commands in the module +have the same names as commands or items in the session. Name conflicts can result in commands being hidden or replaced. ### Hidden -A command is hidden when it is not the command that runs -when you type the command name, but you can run it -by using another method, such as by qualifying the command -name with the name of the module or snap-in in which it + +A command is hidden when it is not the command that runs when you type the +command name, but you can run it by using another method, such as by +qualifying the command name with the name of the module or snap-in in which it originated. ### Replaced -A command is replaced when you cannot run it because -it has been overwritten by a command with the same name. Even -when you remove the module that caused the conflict, you cannot -run a replaced command unless you restart the session. + +A command is replaced when you cannot run it because it has been overwritten +by a command with the same name. Even when you remove the module that caused +the conflict, you cannot run a replaced command unless you restart the +session. `Import-Module` might add commands that hide and replace commands in the current session. Also, commands in your session can hide commands that the module added. -To detect name conflicts, use the **All** parameter of the `Get-Command` cmdlet. -Beginning in Windows PowerShell 3.0, `Get-Command` gets only that commands -that run when you type the command name. The **All** parameter gets all commands -with the specific name in the session. +To detect name conflicts, use the **All** parameter of the `Get-Command` +cmdlet. Beginning in PowerShell 3.0, `Get-Command` gets only that commands +that run when you type the command name. The **All** parameter gets all +commands with the specific name in the session. To prevent name conflicts, use the **NoClobber** or **Prefix** parameters of -the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the names -of imported commands so that they are unique in the session. The **NoClobber** -parameter does not import any commands that would hide or replace existing -commands in the session. - -You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** parameters -of `Import-Module` to select only the commands that you want to import, -and you can exclude commands that cause name conflicts in your session. +the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the +names of imported commands so that they are unique in the session. The +**NoClobber** parameter does not import any commands that would hide or +replace existing commands in the session. + +You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** +parameters of `Import-Module` to select only the commands that you want to +import, and you can exclude commands that cause name conflicts in your +session. Module authors can prevent name conflicts by using the DefaultCommandPrefix -property of the module manifest to add a default prefix to all command -names. The value of the Prefix parameter takes precedence over the value -of DefaultCommandPrefix. +property of the module manifest to add a default prefix to all command names. +The value of the Prefix parameter takes precedence over the value of +DefaultCommandPrefix. -Even if a command is hidden, you can run it by qualifying the command -name with the name of the module or snap-in in which it originated. +Even if a command is hidden, you can run it by qualifying the command name +with the name of the module or snap-in in which it originated. -The Windows PowerShell command precedence rules determine which command -runs when the session includes commands with the same name. +The PowerShell command precedence rules determine which command runs when the +session includes commands with the same name. For example, when a session includes a function and a cmdlet with the same -name, Windows PowerShell runs the function by default. When the session -includes commands of the same type with the same name, such as two cmdlets -with the same name, by default, it runs the most recently added command. +name, PowerShell runs the function by default. When the session includes +commands of the same type with the same name, such as two cmdlets with the +same name, by default, it runs the most recently added command. For more information, including an explanation of the precedence rules and -instructions for running hidden commands, see [about_Command_Precedence](about_Command_Precedence.md). +instructions for running hidden commands, see +[about_Command_Precedence](about_Command_Precedence.md). ## Modules and Snap-ins -You can add commands to your session from modules and snap-ins. Modules -can add all types of commands, including cmdlets, providers, and functions, -and items, such as variables, aliases, and Windows PowerShell drives. -Snap-ins can add only cmdlets and providers. +You can add commands to your session from modules and snap-ins. Modules can +add all types of commands, including cmdlets, providers, and functions, and +items, such as variables, aliases, and PowerShell drives. Snap-ins can add +only cmdlets and providers. Before removing a module or snap-in from your session, use the following commands to determine which commands will be removed. @@ -441,55 +440,52 @@ To find the source of a cmdlet in your session, use the following command format: ```powershell -Get-Command | Format-List -Property verb, noun, pssnapin, module +Get-Command | Format-List -Property verb,noun,pssnapin,module ``` For example, to find the source of the `Get-Date` cmdlet, type: ```powershell -Get-Command Get-Date | Format-List -Property verb, noun, pssnapin, module +Get-Command Get-Date | Format-List -Property verb,noun,pssnapin,module ``` -For more information about Windows PowerShell snap-ins, see [about_PSSnapins](about_PSSnapins.md). +For more information about PowerShell snap-ins, see +[about_PSSnapins](about_PSSnapins.md). ## Module-related Warnings and Errors -The commands that a module exports should follow the Windows PowerShell -command naming rules. If the module that you import exports cmdlets or -functions that have unapproved verbs in their names, the `Import-Module` -cmdlet displays the following warning message. +The commands that a module exports should follow the PowerShell command naming +rules. If the module that you import exports cmdlets or functions that have +unapproved verbs in their names, the `Import-Module` cmdlet displays the +following warning message. -WARNING: Some imported command names include unapproved verbs -which might make them less discoverable. Use the Verbose parameter -for more detail or type `Get-Verb` to see the list of approved verbs. +WARNING: Some imported command names include unapproved verbs which might make +them less discoverable. Use the Verbose parameter for more detail or type +`Get-Verb` to see the list of approved verbs. This message is only a warning. The complete module is still imported, -including the non-conforming commands. Although the message is displayed -to module users, the naming problem should be fixed by the module author. +including the non-conforming commands. Although the message is displayed to +module users, the naming problem should be fixed by the module author. -To suppress the warning message, use the **DisableNameChecking** parameter -of the `Import-Module` cmdlet. +To suppress the warning message, use the **DisableNameChecking** parameter of +the `Import-Module` cmdlet. ## Built-in Modules and Snap-ins -In Windows PowerShell 2.0 and in older-style host programs in Windows -PowerShell 3.0 and later, the core commands that are installed with -Windows PowerShell are packaged in snap-ins that are added automatically -to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that -implement the InitialSessionState.CreateDefault2 initial session state API -- -the core commands are packaged in modules. The default is -Microsoft.PowerShell.Core, which is always a snap-in. +In PowerShell 2.0 and in older-style host programs in PowerShell 3.0 and +later, the core commands that are installed with PowerShell are packaged in +snap-ins that are added automatically to every PowerShell session. -The Microsoft.PowerShell.Core snap-in is added to every session by -default. Modules are loaded automatically on first-use. +Beginning in PowerShell 3.0, for host programs that implement the +`InitialSessionState.CreateDefault2` initial session state API the +Microsoft.PowerShell.Core snap-in is added to every session by default. +Modules are loaded automatically on first-use. -NOTE: Remote sessions, including sessions that are started by using -the New-PSSession cmdlet, are older-style sessions in which the built-in +NOTE: Remote sessions, including sessions that are started by using the +`New-PSSession` cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. -The following modules (or snap-ins) are installed with Windows PowerShell. +The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics @@ -509,13 +505,13 @@ The following modules (or snap-ins) are installed with Windows PowerShell. ## Logging Module Events -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets -and functions in Windows PowerShell modules and snap-ins by setting the -LogPipelineExecutionDetails property of modules and snap-ins to $True. -You can also use a Group Policy setting, Turn on Module Logging, -to enable module logging in all Windows PowerShell sessions. -For more information, see [about_EventLogs](about_EventLogs.md) -and [about_Group_Policy_Settings](about_Group_Policy_Settings.md). +Beginning in PowerShell 3.0, you can record execution events for the cmdlets +and functions in PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to \$True. You can +also use a Group Policy setting, Turn on Module Logging, to enable module +logging in all PowerShell sessions. For more information, see +[about_EventLogs](about_EventLogs.md) and +[about_Group_Policy_Settings](about_Group_Policy_Settings.md). ## See Also diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Jobs.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Jobs.md index 2791902df4b1..c90d48ee71a1 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Jobs.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,49 +7,41 @@ title: about_Jobs --- # About Jobs -## about_Jobs +## SHORT DESCRIPTION - -# SHORT DESCRIPTION - -Provides information about how Windows PowerShell background jobs run a +Provides information about how PowerShell background jobs run a command or expression in the background without interacting with the current session. -# LONG DESCRIPTION +## LONG DESCRIPTION -This topic explains how to run background jobs in Windows PowerShell on a +This topic explains how to run background jobs in PowerShell on a local computer. For information about running background jobs on remote -computers, see about_Remote_Jobs. +computers, see [about_Remote_Jobs](about_Remote_Jobs.md). When you start a background job, the command prompt returns immediately, even if the job takes an extended time to complete. You can continue to work in the session without interruption while the job runs. -# THE JOB CMDLETS - - -Start-Job Starts a background job on a local computer. - -Get-Job Gets the background jobs that were started in the current -session. - -Receive-Job Gets the results of background jobs. - -Stop-Job Stops a background job. - -Wait-Job Suppresses the command prompt until one or all jobs are -complete. - -Remove-Job Deletes a background job. - -Invoke-Command The AsJob parameter runs any command as a background job on a -remote computer. You can also use Invoke-Command to run -any job command remotely, including a Start-Job command. - -# HOW TO START A JOB ON THE LOCAL COMPUTER - +## THE JOB CMDLETS + +|Cmdlet |Description | +|----------------|-------------------------------------------------------| +|`Start-Job` |Starts a background job on a local computer. | +|`Get-Job` |Gets the background jobs that were started in the | +| |current session. | +|`Receive-Job` |Gets the results of background jobs. | +|`Stop-Job` |Stops a background job. | +|`Wait-Job` |Suppresses the command prompt until one or all jobs are| +| |complete. | +|`Remove-Job` |Deletes a background job. | +|`Invoke-Command`|The AsJob parameter runs any command as a background | +| |job on a remote computer. You can also use | +| |`Invoke-Command` to run any job command remotely, | +| |including a Start-Job command. | + +## HOW TO START A JOB ON THE LOCAL COMPUTER To start a background job on the local computer, use the Start-Job cmdlet. @@ -57,251 +49,279 @@ cmdlet. To write a Start-Job command, enclose the command that the job runs in braces ( { } ). Use the ScriptBlock parameter to specify the command. -The following command starts a background job that runs a Get-Process +The following command starts a background job that runs a `Get-Process` command on the local computer. +```powershell Start-Job -ScriptBlock {Get-Process} +``` -The Start-Job command returns an object that represents the job. The job +The `Start-Job` command returns an object that represents the job. The job object contains useful information about the job, but it does not contain the job results. Save the job object in a variable, and then use it with the other Job cmdlets to manage the background job. The following command starts a job -object and saves the resulting job object in the $job variable. +object and saves the resulting job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-Process} +``` -You can also use the Get-Job cmdlet to get objects that represent the jobs -started in the current session. Get-Job returns the same job object that +You can also use the `Get-Job` cmdlet to get objects that represent the jobs +started in the current session. `Get-Job` returns the same job object that Start-Job returns. -# GETTING JOB OBJECTS - +## GETTING JOB OBJECTS To get object that represent the background jobs that were started in the -current session, use the Get-Job cmdlet. Without parameters, Get-Job +current session, use the `Get-Job` cmdlet. Without parameters, `Get-Job` returns all of the jobs that were started in the current session. For example, the following command gets the jobs in the current session. +```powershell PS C:> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Running True localhost Get-Process +``` You can also save the job object in a variable and use it to represent the job in a later command. The following command gets the job with ID 1 and -saves it in the $job variable. +saves it in the \$job variable. +```powershell $job = Get-Job -Id 1 +``` The job object contains the state of the job, which indicates whether the job has finished. A finished job has a state of "Complete" or "Failed". A job might also be blocked or running. +```powershell Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Complete True localhost Get-Process +``` -# GETTING THE RESULTS OF A JOB - +## GETTING THE RESULTS OF A JOB When you run a background job, the results do not appear immediately. Instead, the Start-Job cmdlet returns a job object that represents the job, but it does not contain the results. To get the results of a -background job, use the Receive-Job cmdlet. +background job, use the `Receive-Job` cmdlet. -The following command uses the Receive-Job cmdlet to get the results of -the job. It uses a job object saved in the $job variable to identify the +The following command uses the `Receive-Job` cmdlet to get the results of +the job. It uses a job object saved in the \$job variable to identify the job. +```powershell Receive-Job -Job $job +``` The Receive-Job cmdlet returns the results of the job. +``` Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -668 7 2672 6168 104 32.26 488 csrss + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 668 7 2672 6168 104 32.26 488 csrss # ... +``` +You can also save the results of a job in a variable. The following command +saves the results of the job in the \$job variable to the \$results variable. -You can also save the results of a job in a variable. The following -command saves the results of the job in the $job variable to the $results -variable. - +```powershell $results = Receive-Job -Job $job +``` And, you can save the results of the job in a file by using the redirection operator (>) or the Out-File cmdlet. The following command uses the -redirection operator to save the results of the job in the $job variable in +redirection operator to save the results of the job in the \$job variable in the Results.txt file. +```powershell Receive-Job -Job $job > results.txt +``` -# GETTING AND KEEPING PARTIAL JOB RESULTS - +## GETTING AND KEEPING PARTIAL JOB RESULTS The Receive-Job cmdlet gets the results of a background job. If the -job is complete, Receive-Job gets all job results. If the job is still +job is complete, `Receive-Job` gets all job results. If the job is still running, Receive-Job gets the results that have been generated thus far. -You can run Receive-Job commands again to get the remaining results. +You can run `Receive-Job` commands again to get the remaining results. -When Receive-Job returns results, by default, it deletes those results from -the cache where job results are stored. If you run another Receive-Job +When `Receive-Job` returns results, by default, it deletes those results from +the cache where job results are stored. If you run another `Receive-Job` command, you get only the results that are not yet received. -The following commands show the results of Receive-Job commands run +The following commands show the results of `Receive-Job` commands run before the job is complete. +```powershell C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -To prevent Receive-Job from deleting the job results that it has -returned, use the Keep parameter. As a result, Receive-Job returns all + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +To prevent `Receive-Job` from deleting the job results that it has +returned, use the **Keep** parameter. As a result, `Receive-Job` returns all of the results that have been generated until that time. The following commands show the effect of using the Keep parameter on a job that is not yet complete. +```powershell C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -# WAITING FOR THE RESULTS - - -If you run a command that takes a long time to complete, you can use -the properties of the job object to determine when the job is complete. -The following command uses the Get-Job object to get all of the background -jobs in the current session. - + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +## WAITING FOR THE RESULTS + +If you run a command that takes a long time to complete, you can use the +properties of the job object to determine when the job is complete. The +following command uses the `Get-Job` object to get all of the background jobs +in the current session. + +```powershell Get-Job +``` The results appear in a table. The status of the job appears in the State column. -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Complete True localhost Get-Process -2 Job2 BackgroundJob Running True localhost Get-EventLog -Log Syst... -3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Recurse - -In this case, the State property reveals that Job 2 is still running. If -you were to use the Receive-Job cmdlet to get the job results now, the -results would be incomplete. You can use the Receive-Job cmdlet -repeatedly to get all of the results. By default, each time you use it, -you get only the results that were not already received, but you can use -the Keep parameter of the Receive-Job cmdlet to retain the results, even -though they were already received. +``` +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Complete True localhost Get-Process +2 Job2 BackgroundJob Running True localhost Get-EventLog -Log ... +3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Re... +``` + +In this case, the State property reveals that Job 2 is still running. If you +were to use the `Receive-Job` cmdlet to get the job results now, the results +would be incomplete. You can use the `Receive-Job` cmdlet repeatedly to get +all of the results. By default, each time you use it, you get only the results +that were not already received, but you can use the Keep parameter of the +Receive-Job cmdlet to retain the results, even though they were already +received. You can write the partial results to a file and then append newer results as they arrive or you can wait and check the state of the job later. -You can use the Wait parameter of the Receive-Job cmdlet, which +You can use the Wait parameter of the `Receive-Job` cmdlet, which does not return the command prompt until the job is complete and all results are available. -You can also use the Wait-Job cmdlet to wait for any or all of the results -of the job. Wait-Job lets you wait for a particular job, for all jobs, or +You can also use the `Wait-Job` cmdlet to wait for any or all of the results +of the job. `Wait-Job` lets you wait for a particular job, for all jobs, or for any of the jobs to be completed. -The following command uses the Wait-Job cmdlet to wait for a job with -# ID 10. - +The following command uses the Wait-Job cmdlet to wait for a job with ID 10. +```powershell Wait-Job -ID 10 +``` -As a result, the Windows PowerShell prompt is suppressed until the job -is completed. +As a result, the PowerShell prompt is suppressed until the job is completed. You can also wait for a predetermined period of time. This command uses the Timeout parameter to limit the wait to 120 seconds. When the time expires, the command prompt returns, but the job continues to run in the background. +```powershell Wait-Job -ID 10 -Timeout 120 +``` -# STOPPING A JOB +## STOPPING A JOB - -To stop a background job, use the Stop-Job cmdlet. The following command +To stop a background job, use the `Stop-Job` cmdlet. The following command starts a job to get every entry in the System event log. It saves the job -object in the $job variable. +object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-EventLog -Log System} +``` The following command stops the job. It uses a pipeline operator (|) to -send the job in the $job variable to Stop-Job. +send the job in the \$job variable to `Stop-Job`. +```powershell $job | Stop-Job +``` -# DELETING A JOB - +## DELETING A JOB -To delete a background job, use the Remove-Job cmdlet. The following -command deletes the job in the $job variable. +To delete a background job, use the `Remove-Job` cmdlet. The following +command deletes the job in the \$job variable. +```powershell Remove-Job -Job $job +``` -# INVESTIGATING A FAILED JOB - +## INVESTIGATING A FAILED JOB To find out why a job failed, use the Reason subproperty of the job object. The following command starts a job without the required credentials. It -saves the job object in the $job variable. +saves the job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {New-Item -Path HKLM:\Software\MyCompany} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:\S... +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:... +``` The following command uses the Reason property to find the error that caused the job to fail. +```powershell $job.ChildJobs[0].JobStateInfo.Reason +``` In this case, the job failed because the remote computer required explicit credentials to run the command. The value of the Reason property is: -Connecting to remote server failed with the following error -message : Access is denied. +Connecting to remote server failed with the following error message : Access +is denied. -# SEE ALSO +## SEE ALSO [about_Remote_Jobs](about_Remote_Jobs.md) @@ -311,17 +331,16 @@ message : Access is denied. [about_PSSessions](about_PSSessions.md) -Start-Job - -Get-Job +[Start-Job](../Start-Job.md) -Receive-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Receive-Job](../Receive-Job.md) -Wait-Job +[Stop-Job](../Stop-Job.md) -Remove-Job +[Wait-Job](../Wait-Job.md) -Invoke-Command +[Remove-Job](../Remove-Job.md) +[Invoke-Command](../../Microsoft.PowerShell.Core/Invoke-Command.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Methods.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Methods.md index 47e1298d7137..a32eb5d38a92 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Methods.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Methods.md @@ -7,188 +7,202 @@ title: about_Methods --- # About methods -## about_methods - ## SHORT DESCRIPTION -Describes how to use methods to perform actions on objects in Windows PowerShell. +Describes how to use methods to perform actions on objects in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses objects to represent the items in data stores or the state of the computer. For example, FileInfo objects represent the files in file system drives and ProcessInfo objects represent the processes on the computer. -Objects have properties, which store data about the object, and methods that let you change the object. +PowerShell uses objects to represent the items in data stores or the state of +the computer. For example, FileInfo objects represent the files in file system +drives and ProcessInfo objects represent the processes on the computer. -A "method" is a set of instructions that specify an action you can perform on the object. For example, the FileInfo object includes the CopyTo method that copies the file that the FileInfo object represents. +Objects have properties, which store data about the object, and methods that +let you change the object. -To get the methods of any object, use the Get-Member cmdlet. Use its MemberType property with a value of "Method". The following command gets the methods of process objects. +A "method" is a set of instructions that specify an action you can perform on +the object. For example, the `FileInfo` object includes the `CopyTo` method that +copies the file that the `FileInfo` object represents. +To get the methods of any object, use the `Get-Member` cmdlet. Use its +**MemberType** property with a value of "Method". The following command gets +the methods of process objects. -``` +```powershell PS C:\> Get-Process | Get-Member -MemberType Method ``` +```output +TypeName: System.Diagnostics.Process - +Name MemberType Definition +---- ---------- ---------- +BeginErrorReadLine Method System.Void BeginErrorReadLine() +BeginOutputReadLine Method System.Void BeginOutputReadLine() +... +Kill Method System.Void Kill() +Refresh Method System.Void Refresh() +Start Method bool Start() +ToString Method string ToString() +WaitForExit Method bool WaitForExit(int milliseconds), ... +WaitForInputIdle Method bool WaitForInputIdle(int millisecon... ``` -TypeName: System.Diagnostics.Process - -Name MemberType Definition ----- ---------- ---------- -BeginErrorReadLine Method System.Void BeginErrorReadLine() -BeginOutputReadLine Method System.Void BeginOutputReadLine() -... -Kill Method System.Void Kill() -Refresh Method System.Void Refresh() -Start Method bool Start() -ToString Method string ToString() -WaitForExit Method bool WaitForExit(int milliseconds), System.Void WaitForExit() -WaitForInputIdle Method bool WaitForInputIdle(int milliseconds), bool WaitForInputIdle() -``` - - -To perform or "invoke" a method of an object, type a dot (.), the method name, and a set of parentheses "()". If the method has arguments, place the argument values inside the parentheses. The parentheses are required for every method call, even when there are no arguments. -For example, the following command invokes the Kill method of processes to end the Notepad process on the computer. As a result, the instance of Notepad closes. (The Get-Process command is enclosed in parentheses to insure that it runs before the Kill method is invoked. +To perform or "invoke" a method of an object, type a dot (.), the method name, +and a set of parentheses "()". If the method has arguments, place the argument +values inside the parentheses. The parentheses are required for every method +call, even when there are no arguments. +For example, the following command invokes the Kill method of processes to end +the Notepad process on the computer. As a result, the instance of Notepad +closes. (The `Get-Process` command is enclosed in parentheses to insure that +it runs before the Kill method is invoked. -``` +```powershell (Get-Process Notepad).Kill() ``` +Another very useful process is the Split method of strings. The split method +takes a delimiter character argument that tells the method where to split the +string. -Another very useful process is the Split method of strings. The split method takes a delimiter character argument that tells the method where to split the string. - - -``` -PS C:\> $a = "Try-Catch-Finally" -PS C:\> $a.Split("-") -Try -Catch +```powershell +PS C:\> $a = "Try-Catch-Finally" +PS C:\> $a.Split("-") +Try +Catch Finally ``` +As shown in the previous examples, you can invoke a method on an object that +you get by using a command or an object in a variable. -As shown in the previous examples, you can invoke a method on an object that you get by using a command or an object in a variable. - -Starting in Windows PowerShell 4.0, method invocation by using dynamic method names is supported. - +Starting in PowerShell 4.0, method invocation by using dynamic method names is +supported. ### LEARNING ABOUT METHODS -To find definitions of the methods of an object, go to help topic for the object type in MSDN and look for its methods page. For example, the following page describes the methods of process objects (System.Diagnostics.Process). - - -``` -http://msdn.microsoft.com/library/system.diagnostics.process_methods -``` +To find definitions of the methods of an object, go to help topic for the +object type in MSDN and look for its methods page. For example, the following +page describes the methods of process objects +[System.Diagnostics.Process](http://msdn.microsoft.com/library/system.diagnostics.process_methods). -To determine the arguments of a method, review the method definition, which is like the syntax diagram of a Windows PowerShell cmdlet. +To determine the arguments of a method, review the method definition, which is +like the syntax diagram of a PowerShell cmdlet. -A method definition might have one or more method signatures, which are like the parameter sets of Windows PowerShell cmdlets. The signatures show all of the valid formats of commands to invoke the method. - -For example, the CopyTo method of the FileInfo class contains the following two method signatures: - - -``` -1. CopyTo(String destFileName) -2. CopyTo(String destFileName, Boolean overwrite) -``` +A method definition might have one or more method signatures, which are like +the parameter sets of PowerShell cmdlets. The signatures show all of the valid +formats of commands to invoke the method. +For example, the `CopyTo` method of the `FileInfo` class contains the following +two method signatures: -The first method signature takes the destination file name (and a path). The following example use The first CopyTo method to copy the Final.txt file to the C:\Bin directory. + CopyTo(String destFileName) + CopyTo(String destFileName, Boolean overwrite) +The first method signature takes the destination file name (and a path). The +following example use The first `CopyTo` method to copy the Final.txt file to +the C:\\Bin directory. -``` +```powershell (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt") ``` +The second method signature take a destination file name and a Boolean value +that determines whether the destination file should be overwritten, if it +already exists. -The second method signature take a destination file name and a Boolean value that determines whether the destination file should be overwritten, if it already exists. - -The following example use The second CopyTo method to copy the Final.txt file to the C:\Bin directory, and to overwrite existing files. - +The following example use The second `CopyTo` method to copy the Final.txt file +to the C:\\Bin directory, and to overwrite existing files. ``` (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` - - ### METHODS OF SCALAR OBJECTS AND COLLECTIONS -The methods of one ("scalar") object of a particular type are often different from the methods of a collection of objects of the same type. -For example, every process has a Kill method, but a collection of processes does not have a Kill method. +The methods of one ("scalar") object of a particular type are often different +from the methods of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing methods of scalar objects and collections. +For example, every process has a `Kill` method, but a collection of processes +does not have a Kill method. -Beginning in Windows PowerShell 4.0, collection filtering by using a method syntax is supported. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing methods of scalar objects and collections. -If you submit a collection, but request a method that exists only on single ("scalar") objects, Windows invokes the method on every object in the collection. +Beginning in PowerShell 4.0, collection filtering by using a method syntax is +supported. -If the method exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you submit a collection, but request a method that exists only on single +("scalar") objects, PowerShell invokes the method on every object in the +collection. -This feature also works on properties of scalar objects and collections. For more information, see about_Properties. +If the method exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on properties of scalar objects and collections. For +more information, see [about_Properties](about_Properties.md). ### EXAMPLES -The following example runs the Kill method of individual process objects on a collection of process objects. This example works only on Windows PowerShell 3.0 and later versions of Windows PowerShell. -The first command starts three instances of the Notepad process. The second command uses the Get-Process command to get all three instance of the Notepad process and save them in the $p variable. +The following example runs the Kill method of individual process objects on a +collection of process objects. This example works only on PowerShell 3.0 and +later versions of PowerShell. +The first command starts three instances of the Notepad process. The second +command uses the `Get-Process` command to get all three instance of the Notepad +process and save them in the \$p variable. -``` -PS C:\> Notepad; Notepad; Notepad +```powershell +PS C:\> Notepad; Notepad; Notepad PS C:\> $p = Get-Process Notepad ``` +The third command uses the Count property of all collections to verify that +there are three processes in the \$p variable. -The third command uses the Count property of all collections to verify that there are three processes in the $p variable. - - -``` -PS C:\> $p.Count +```powershell +PS C:\> $p.Count 3 ``` +The fourth command runs the Kill method on all three processes in the \$p +variable. -The fourth command runs the Kill method on all three processes in the $p variable. - -This command works even though a collection of processes does not have a Kill method. - +This command works even though a collection of processes does not have a `Kill` +method. ``` PS C:\> $p.Kill() ``` +The fifth command uses the Get-Process command to confirm that the `Kill` +command worked. -The fifth command uses the Get-Process command to confirm that the Kill command worked. - - +```powershell +PS C:\> Get-Process Notepad +Get-Process : Cannot find a process with the name "notepad". Verify the proc +ess name and call the cmdlet again. +At line:1 char:12 ++ get-process <<<< notepad + + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process] +, ProcessCommandException + + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShel +l.Commands.GetProcessCommand ``` -PS C:\> Get-Process Notepad -Get-Process : Cannot find a process with the name "notepad". Verify the process name and call the cmdlet again. -At line:1 char:12 -+ get-process <<<< notepad - + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process], ProcessCommandException - + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.Commands.GetProcessCommand -``` - -To perform the same task on Windows PowerShell 2.0, use the Foreach-Object cmdlet to run the method on each object in the collection. +To perform the same task on PowerShell 2.0, use the `Foreach-Object` cmdlet to +run the method on each object in the collection. - -``` +```powershell PS C:\> $p | Foreach-Object {$_.Kill()} ``` - - ## SEE ALSO [about_Objects](about_Objects.md) [about_Properties](about_Properties.md) -Get-Member - +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md index 6d1f8847f78e..931280614067 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,51 +10,53 @@ title: about_Modules ## Short Description -Explains how to install, import, and use Windows PowerShell modules. +Explains how to install, import, and use PowerShell modules. ## Long Description -A module is a package that contains Windows PowerShell commands, such as -cmdlets, providers, functions, workflows, variables, and aliases. +A module is a package that contains PowerShell commands, such as cmdlets, +providers, functions, workflows, variables, and aliases. -People who write commands can use modules to organize their commands and -share them with others. People who receive modules can add the commands -in the modules to their Windows PowerShell sessions and use them just like -the built-in commands. +People who write commands can use modules to organize their commands and share +them with others. People who receive modules can add the commands in the +modules to their PowerShell sessions and use them just like the built-in +commands. -This topic explains how to use Windows PowerShell modules. -For information about how to write Windows PowerShell modules, see -[Writing a Windows PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) in the MSDN library. +This topic explains how to use PowerShell modules. For information about how +to write PowerShell modules, see [Writing a PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) +in the MSDN library. ## What Is a Module? -A module is a package of commands. All cmdlets and providers in your -session are added by a module or a snap-in. +A module is a package of commands. All cmdlets and providers in your session +are added by a module or a snap-in. ## Module Auto-Loading -Beginning in Windows PowerShell 3.0, Windows PowerShell imports -modules automatically the first time that you run any command in -an installed module. You can now use the commands in a module -without any set-up or profile configuration, so there's no need to -manage modules after you install them on your computer. +Beginning in PowerShell 3.0, PowerShell imports modules automatically the +first time that you run any command in an installed module. You can now use +the commands in a module without any set-up or profile configuration, so +there's no need to manage modules after you install them on your computer. -The commands in a module are also easier to find. The `Get-Command` cmdlet -now gets all commands in all installed modules, even if they are not yet -in the session, so you can find a command and use it without importing. +The commands in a module are also easier to find. The `Get-Command` cmdlet now +gets all commands in all installed modules, even if they are not yet in the +session, so you can find a command and use it without importing. Any of the following commands will import a module into your session. ### Run the Command + ```powershell Get-Mailbox -Identity Chris ``` ### Get the Command + ```powershell Get-Command Get-Mailbox ``` ### Get Help for the Command + ```powershell Get-Help Get-Mailbox ``` @@ -66,7 +68,7 @@ Only modules that are stored in the location specified by the PSModulePath environment variable are automatically imported. Modules in other locations must be imported by running the `Import-Module` cmdlet. -Also, commands that use Windows PowerShell providers do not automatically +Also, commands that use PowerShell providers do not automatically import a module. For example, if you use a command that requires the WSMan: drive, such as the `Get-PSSessionConfiguration` cmdlet, you might need to run the `Import-Module` cmdlet to import the Microsoft.WSMan.Management @@ -90,43 +92,40 @@ other useful information about managing modules. ## How to Install a Module -If you receive a module as a folder with files in it, you need -to install it on your computer before you can use it in Windows -PowerShell. +If you receive a module as a folder with files in it, you need to install it +on your computer before you can use it in PowerShell. -Most modules are installed for you. Windows PowerShell comes with -several preinstalled modules, sometimes called the "core" modules. -On Windows-based computers, if features that are included with the -operating system have cmdlets to manage them, those modules are preinstalled. -When you install a Windows feature, by using, for example, the Add Roles -and Features Wizard in Server Manager, or the Turn Windows features on or off -dialog box in Control Panel, any Windows PowerShell modules that are part -of the feature are installed. Many other modules come in an installer or -Setup program that installs the module. +Most modules are installed for you. PowerShell comes with several preinstalled +modules, sometimes called the "core" modules. On Windows-based computers, if +features that are included with the operating system have cmdlets to manage +them, those modules are preinstalled. When you install a Windows feature, by +using, for example, the Add Roles and Features Wizard in Server Manager, or +the Turn Windows features on or off dialog box in Control Panel, any +PowerShell modules that are part of the feature are installed. Many other +modules come in an installer or Setup program that installs the module. -To install a module folder: -1. Create a Modules directory for the current user if one does not exist. -To create a Modules directory, type: +Create a Modules directory for the current user if one does not exist. To +create a Modules directory, type: ```powershell New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules ``` -2. Copy the entire module folder into the Modules directory. -You can use any method to copy the folder, including Windows -Explorer and Cmd.exe, as well as Windows PowerShell. -In Windows PowerShell use the `Copy-Item` cmdlet. For example, to copy the -MyModule folder from C:\ps-test\MyModule to the Modules directory, type: +Copy the entire module folder into the Modules directory. You can use any +method to copy the folder, including Windows Explorer and Cmd.exe, as well as +PowerShell. In PowerShell use the `Copy-Item` cmdlet. For example, to copy the +MyModule folder from C:\\ps-test\\MyModule to the Modules directory, type: ```powershell -Copy-Item -Path C:\ps-test\MyModule -Destination $HOME\Documents\WindowsPowerShell\Modules +Copy-Item -Path C:\ps-test\MyModule -Destination ` + $HOME\Documents\WindowsPowerShell\Modules ``` You can install a module in any location, but installing your modules in a -default module location makes them easier to manage. For more information about -the default module locations, see the "Module and DSC Resource Locations, -and PSModulePath" section. +default module location makes them easier to manage. For more information +about the default module locations, see the "Module and DSC Resource +Locations, and PSModulePath" section. ## How to Find Installed Modules @@ -138,19 +137,20 @@ Get-Module -ListAvailable ``` To find the modules that have already been imported into your session, -at the Windows PowerShell prompt, type: +at the PowerShell prompt, type: ```powershell Get-Module ``` -For more information about the `Get-Module` cmdlet, see [Get-Module](../Get-Module.md). +For more information about the `Get-Module` cmdlet, see +[Get-Module](../Get-Module.md). ## How to Find the Commands in a Module -Use the `Get-Command` cmdlet to find all available commands. -You can use the parameters of the `Get-Command` cmdlet to filter commands -such as by module, name, and noun. +Use the `Get-Command` cmdlet to find all available commands. You can use the +parameters of the `Get-Command` cmdlet to filter commands such as by module, +name, and noun. To find all commands in a module, type: @@ -164,18 +164,17 @@ For example, to find the commands in the BitsTransfer module, type: Get-Command -Module BitsTransfer ``` -For more information about the `Get-Command` cmdlet, see [Get-Command](../Get-Command.md). +For more information about the `Get-Command` cmdlet, see +[Get-Command](../Get-Command.md). ## How to Get Help for the Commands in a Module -If the module contains Help files for the commands that it exports, -the `Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` -command format that you would use to get help for any command in Windows -PowerShell. +If the module contains Help files for the commands that it exports, the +`Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` +command format that you would use to get help for any command in PowerShell. -Beginning in Windows PowerShell 3.0, you can download Help files for -a module and download updates to the Help files so they are never -obsolete. +Beginning in PowerShell 3.0, you can download Help files for a module and +download updates to the Help files so they are never obsolete. To get help for a commands in a module, type: @@ -195,20 +194,22 @@ To download and install the help files for the commands in a module, type: Update-Help -Module ``` -For more information, see [Get-Help](../Get-Help.md) and [Update-Help](../Update-Help.md). +For more information, see [Get-Help](../Get-Help.md) and +[Update-Help](../Update-Help.md). ## How to Import a Module -You might have to import a module or import a module file. Importing is required -when a module is not installed in the locations specified by the PSModulePath -environment variable ($env:PSModulePath), or the module consists of file, such -as a .dll or .psm1 file, instead of typical module that is delivered as a folder. +You might have to import a module or import a module file. Importing is +required when a module is not installed in the locations specified by the +PSModulePath environment variable ($env:PSModulePath), or the module consists +of file, such as a .dll or .psm1 file, instead of typical module that is +delivered as a folder. -You might also choose to import a module so that you can use the parameters of the -`Import-Module` command, such as the Prefix parameter, which adds a distinctive prefix -to the noun names of all imported commands, or the **NoClobber** parameter, which prevents -the module from adding commands that would hide or replace existing commands in the -session. +You might also choose to import a module so that you can use the parameters of +the `Import-Module` command, such as the Prefix parameter, which adds a +distinctive prefix to the noun names of all imported commands, or the +**NoClobber** parameter, which prevents the module from adding commands that +would hide or replace existing commands in the session. To import modules, use the `Import-Module` cmdlet. @@ -254,8 +255,8 @@ For more information about adding modules to your session, see The `Import-Module` command imports modules into your current Windows PowerShell session. This command affects only the current session. -To import a module into every Windows PowerShell session that you -start, add the `Import-Module` command to your Windows PowerShell +To import a module into every PowerShell session that you +start, add the `Import-Module` command to your PowerShell profile. For more information about profiles, see [about_Profiles](about_Profiles.md). @@ -285,46 +286,42 @@ a module does not uninstall the module. For more information about the ## Module and DSC Resource Locations, and PSModulePath -The following are default locations for Windows PowerShell modules. -Starting in Windows PowerShell 4.0, with the introduction of DSC, a -new default module and DSC resource folder was introduced. For more -information about DSC, see about_DesiredStateConfiguration. +The following are default locations for PowerShell modules. Starting in +PowerShell 4.0, with the introduction of DSC, a new default module and DSC +resource folder was introduced. For more information about DSC, see +about_DesiredStateConfiguration. -System: $pshome\Modules -(%windir%\System32\WindowsPowerShell\v1.0\Modules) -System modules are those that ship with Windows and Windows PowerShell. +- System: $pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) + System modules are those that ship with Windows and PowerShell. -Starting in Windows Powershell 4.0, when Windows PowerShell -Desired State Configuration (DSC) was introduced, DSC resources that are -included with Windows PowerShell are also stored in $pshome\Modules, -in the $pshome\Modules\PSDesiredStateConfiguration\DSCResources -folder. + Starting in PowerShell 4.0, when PowerShell Desired State Configuration + (DSC) was introduced, DSC resources that are included with PowerShell are + also stored in \$pshome\\Modules, in the + \$pshome\\Modules\\PSDesiredStateConfiguration\\DSCResources folder. -Current user: $home\Documents\WindowsPowerShell\Modules -(%UserProfile%\Documents\WindowsPowerShell\Modules) +- Current user: \$home\\Documents\\WindowsPowerShell\\Modules + (%UserProfile%\Documents\WindowsPowerShell\Modules) -or + or -$home\My Documents\WindowsPowerShell\Modules -(%UserProfile%\My Documents\WindowsPowerShell\Modules) -This is the location for user-added modules prior to Windows PowerShell 4.0. + \$home\\My Documents\\WindowsPowerShell\\Modules + (%UserProfile%\My Documents\WindowsPowerShell\Modules) + This is the location for user-added modules prior to PowerShell 4.0. -In Windows PowerShell 4.0 and later releases of Windows PowerShell, -user-added modules and DSC resources are stored in -C:\Program Files\WindowsPowerShell\Modules. Modules and DSC resources -in this location are accessible by all users of the computer. -This change was required because the DSC engine runs as local +In PowerShell 4.0 and later releases of PowerShell, user-added modules and DSC +resources are stored in C:\\Program Files\\WindowsPowerShell\\Modules. Modules +and DSC resources in this location are accessible by all users of the +computer. This change was required because the DSC engine runs as local system, and could not access user-specific paths, such as -$home\Documents\WindowsPowerShell\Modules. +\$home\\Documents\\WindowsPowerShell\\Modules. -Starting in Windows PowerShell 5.0, with the addition of the -PowerShellGet module, and the [PowerShell Gallery](https://www.powershellgallery.com) -of community- and Microsoft-created resources, -the `Install-Module` command installs modules and DSC resources to -C:\Program Files\WindowsPowerShell\Modules by default. +Starting in PowerShell 5.0, with the addition of the PowerShellGet module, and +the [PowerShell Gallery](https://www.powershellgallery.com) of community- and +Microsoft-created resources, the `Install-Module` command installs modules and +DSC resources to C:\\Program Files\\WindowsPowerShell\\Modules by default. -Note: To add or change files in the %Windir%\System32 directory, -start Windows PowerShell with the "Run as administrator" option. +Note: To add or change files in the %Windir%\\System32 directory, start +PowerShell with the "Run as administrator" option. You can change the default module locations on your system by changing the value of the PSModulePath environment variable ($Env:PSModulePath). The @@ -356,7 +353,7 @@ When you add a path to PSModulePath, `Get-Module` and `Import-Module` commands include modules in that path. The value that you set affects only the current session. To make the -change persistent, add the command to your Windows PowerShell profile +change persistent, add the command to your PowerShell profile or use System in Control Panel to change the value of the PSModulePath environment variable in the registry. @@ -369,70 +366,72 @@ For more information about the PSModulePath variable, see ## Modules and Name Conflicts -Name conflicts occur when more than one command in the session -has the same name. Importing a module causes a name conflict when -commands in the module have the same names as commands or items -in the session. +Name conflicts occur when more than one command in the session has the same +name. Importing a module causes a name conflict when commands in the module +have the same names as commands or items in the session. Name conflicts can result in commands being hidden or replaced. ### Hidden -A command is hidden when it is not the command that runs -when you type the command name, but you can run it -by using another method, such as by qualifying the command -name with the name of the module or snap-in in which it + +A command is hidden when it is not the command that runs when you type the +command name, but you can run it by using another method, such as by +qualifying the command name with the name of the module or snap-in in which it originated. ### Replaced -A command is replaced when you cannot run it because -it has been overwritten by a command with the same name. Even -when you remove the module that caused the conflict, you cannot -run a replaced command unless you restart the session. + +A command is replaced when you cannot run it because it has been overwritten +by a command with the same name. Even when you remove the module that caused +the conflict, you cannot run a replaced command unless you restart the +session. `Import-Module` might add commands that hide and replace commands in the current session. Also, commands in your session can hide commands that the module added. -To detect name conflicts, use the **All** parameter of the `Get-Command` cmdlet. -Beginning in Windows PowerShell 3.0, `Get-Command` gets only that commands -that run when you type the command name. The **All** parameter gets all commands -with the specific name in the session. +To detect name conflicts, use the **All** parameter of the `Get-Command` +cmdlet. Beginning in PowerShell 3.0, `Get-Command` gets only that commands +that run when you type the command name. The **All** parameter gets all +commands with the specific name in the session. To prevent name conflicts, use the **NoClobber** or **Prefix** parameters of -the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the names -of imported commands so that they are unique in the session. The **NoClobber** -parameter does not import any commands that would hide or replace existing -commands in the session. - -You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** parameters -of `Import-Module` to select only the commands that you want to import, -and you can exclude commands that cause name conflicts in your session. +the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the +names of imported commands so that they are unique in the session. The +**NoClobber** parameter does not import any commands that would hide or +replace existing commands in the session. + +You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** +parameters of `Import-Module` to select only the commands that you want to +import, and you can exclude commands that cause name conflicts in your +session. Module authors can prevent name conflicts by using the DefaultCommandPrefix -property of the module manifest to add a default prefix to all command -names. The value of the Prefix parameter takes precedence over the value -of DefaultCommandPrefix. +property of the module manifest to add a default prefix to all command names. +The value of the Prefix parameter takes precedence over the value of +DefaultCommandPrefix. -Even if a command is hidden, you can run it by qualifying the command -name with the name of the module or snap-in in which it originated. +Even if a command is hidden, you can run it by qualifying the command name +with the name of the module or snap-in in which it originated. -The Windows PowerShell command precedence rules determine which command -runs when the session includes commands with the same name. +The PowerShell command precedence rules determine which command runs when the +session includes commands with the same name. For example, when a session includes a function and a cmdlet with the same -name, Windows PowerShell runs the function by default. When the session -includes commands of the same type with the same name, such as two cmdlets -with the same name, by default, it runs the most recently added command. +name, PowerShell runs the function by default. When the session includes +commands of the same type with the same name, such as two cmdlets with the +same name, by default, it runs the most recently added command. For more information, including an explanation of the precedence rules and -instructions for running hidden commands, see [about_Command_Precedence](about_Command_Precedence.md). +instructions for running hidden commands, see +[about_Command_Precedence](about_Command_Precedence.md). ## Modules and Snap-ins -You can add commands to your session from modules and snap-ins. Modules -can add all types of commands, including cmdlets, providers, and functions, -and items, such as variables, aliases, and Windows PowerShell drives. -Snap-ins can add only cmdlets and providers. +You can add commands to your session from modules and snap-ins. Modules can +add all types of commands, including cmdlets, providers, and functions, and +items, such as variables, aliases, and PowerShell drives. Snap-ins can add +only cmdlets and providers. Before removing a module or snap-in from your session, use the following commands to determine which commands will be removed. @@ -441,55 +440,52 @@ To find the source of a cmdlet in your session, use the following command format: ```powershell -Get-Command | Format-List -Property verb, noun, pssnapin, module +Get-Command | Format-List -Property verb,noun,pssnapin,module ``` For example, to find the source of the `Get-Date` cmdlet, type: ```powershell -Get-Command Get-Date | Format-List -Property verb, noun, pssnapin, module +Get-Command Get-Date | Format-List -Property verb,noun,pssnapin,module ``` -For more information about Windows PowerShell snap-ins, see [about_PSSnapins](about_PSSnapins.md). +For more information about PowerShell snap-ins, see +[about_PSSnapins](about_PSSnapins.md). ## Module-related Warnings and Errors -The commands that a module exports should follow the Windows PowerShell -command naming rules. If the module that you import exports cmdlets or -functions that have unapproved verbs in their names, the `Import-Module` -cmdlet displays the following warning message. +The commands that a module exports should follow the PowerShell command naming +rules. If the module that you import exports cmdlets or functions that have +unapproved verbs in their names, the `Import-Module` cmdlet displays the +following warning message. -WARNING: Some imported command names include unapproved verbs -which might make them less discoverable. Use the Verbose parameter -for more detail or type `Get-Verb` to see the list of approved verbs. +WARNING: Some imported command names include unapproved verbs which might make +them less discoverable. Use the Verbose parameter for more detail or type +`Get-Verb` to see the list of approved verbs. This message is only a warning. The complete module is still imported, -including the non-conforming commands. Although the message is displayed -to module users, the naming problem should be fixed by the module author. +including the non-conforming commands. Although the message is displayed to +module users, the naming problem should be fixed by the module author. -To suppress the warning message, use the **DisableNameChecking** parameter -of the `Import-Module` cmdlet. +To suppress the warning message, use the **DisableNameChecking** parameter of +the `Import-Module` cmdlet. ## Built-in Modules and Snap-ins -In Windows PowerShell 2.0 and in older-style host programs in Windows -PowerShell 3.0 and later, the core commands that are installed with -Windows PowerShell are packaged in snap-ins that are added automatically -to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that -implement the InitialSessionState.CreateDefault2 initial session state API -- -the core commands are packaged in modules. The default is -Microsoft.PowerShell.Core, which is always a snap-in. +In PowerShell 2.0 and in older-style host programs in PowerShell 3.0 and +later, the core commands that are installed with PowerShell are packaged in +snap-ins that are added automatically to every PowerShell session. -The Microsoft.PowerShell.Core snap-in is added to every session by -default. Modules are loaded automatically on first-use. +Beginning in PowerShell 3.0, for host programs that implement the +`InitialSessionState.CreateDefault2` initial session state API the +Microsoft.PowerShell.Core snap-in is added to every session by default. +Modules are loaded automatically on first-use. -NOTE: Remote sessions, including sessions that are started by using -the New-PSSession cmdlet, are older-style sessions in which the built-in +NOTE: Remote sessions, including sessions that are started by using the +`New-PSSession` cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. -The following modules (or snap-ins) are installed with Windows PowerShell. +The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics @@ -509,13 +505,13 @@ The following modules (or snap-ins) are installed with Windows PowerShell. ## Logging Module Events -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets -and functions in Windows PowerShell modules and snap-ins by setting the -LogPipelineExecutionDetails property of modules and snap-ins to $True. -You can also use a Group Policy setting, Turn on Module Logging, -to enable module logging in all Windows PowerShell sessions. -For more information, see [about_EventLogs](about_EventLogs.md) -and [about_Group_Policy_Settings](about_Group_Policy_Settings.md). +Beginning in PowerShell 3.0, you can record execution events for the cmdlets +and functions in PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to \$True. You can +also use a Group Policy setting, Turn on Module Logging, to enable module +logging in all PowerShell sessions. For more information, see +[about_EventLogs](about_EventLogs.md) and +[about_Group_Policy_Settings](about_Group_Policy_Settings.md). ## See Also diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Jobs.md b/reference/6/Microsoft.PowerShell.Core/About/about_Jobs.md index 2791902df4b1..c90d48ee71a1 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Jobs.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,49 +7,41 @@ title: about_Jobs --- # About Jobs -## about_Jobs +## SHORT DESCRIPTION - -# SHORT DESCRIPTION - -Provides information about how Windows PowerShell background jobs run a +Provides information about how PowerShell background jobs run a command or expression in the background without interacting with the current session. -# LONG DESCRIPTION +## LONG DESCRIPTION -This topic explains how to run background jobs in Windows PowerShell on a +This topic explains how to run background jobs in PowerShell on a local computer. For information about running background jobs on remote -computers, see about_Remote_Jobs. +computers, see [about_Remote_Jobs](about_Remote_Jobs.md). When you start a background job, the command prompt returns immediately, even if the job takes an extended time to complete. You can continue to work in the session without interruption while the job runs. -# THE JOB CMDLETS - - -Start-Job Starts a background job on a local computer. - -Get-Job Gets the background jobs that were started in the current -session. - -Receive-Job Gets the results of background jobs. - -Stop-Job Stops a background job. - -Wait-Job Suppresses the command prompt until one or all jobs are -complete. - -Remove-Job Deletes a background job. - -Invoke-Command The AsJob parameter runs any command as a background job on a -remote computer. You can also use Invoke-Command to run -any job command remotely, including a Start-Job command. - -# HOW TO START A JOB ON THE LOCAL COMPUTER - +## THE JOB CMDLETS + +|Cmdlet |Description | +|----------------|-------------------------------------------------------| +|`Start-Job` |Starts a background job on a local computer. | +|`Get-Job` |Gets the background jobs that were started in the | +| |current session. | +|`Receive-Job` |Gets the results of background jobs. | +|`Stop-Job` |Stops a background job. | +|`Wait-Job` |Suppresses the command prompt until one or all jobs are| +| |complete. | +|`Remove-Job` |Deletes a background job. | +|`Invoke-Command`|The AsJob parameter runs any command as a background | +| |job on a remote computer. You can also use | +| |`Invoke-Command` to run any job command remotely, | +| |including a Start-Job command. | + +## HOW TO START A JOB ON THE LOCAL COMPUTER To start a background job on the local computer, use the Start-Job cmdlet. @@ -57,251 +49,279 @@ cmdlet. To write a Start-Job command, enclose the command that the job runs in braces ( { } ). Use the ScriptBlock parameter to specify the command. -The following command starts a background job that runs a Get-Process +The following command starts a background job that runs a `Get-Process` command on the local computer. +```powershell Start-Job -ScriptBlock {Get-Process} +``` -The Start-Job command returns an object that represents the job. The job +The `Start-Job` command returns an object that represents the job. The job object contains useful information about the job, but it does not contain the job results. Save the job object in a variable, and then use it with the other Job cmdlets to manage the background job. The following command starts a job -object and saves the resulting job object in the $job variable. +object and saves the resulting job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-Process} +``` -You can also use the Get-Job cmdlet to get objects that represent the jobs -started in the current session. Get-Job returns the same job object that +You can also use the `Get-Job` cmdlet to get objects that represent the jobs +started in the current session. `Get-Job` returns the same job object that Start-Job returns. -# GETTING JOB OBJECTS - +## GETTING JOB OBJECTS To get object that represent the background jobs that were started in the -current session, use the Get-Job cmdlet. Without parameters, Get-Job +current session, use the `Get-Job` cmdlet. Without parameters, `Get-Job` returns all of the jobs that were started in the current session. For example, the following command gets the jobs in the current session. +```powershell PS C:> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Running True localhost Get-Process +``` You can also save the job object in a variable and use it to represent the job in a later command. The following command gets the job with ID 1 and -saves it in the $job variable. +saves it in the \$job variable. +```powershell $job = Get-Job -Id 1 +``` The job object contains the state of the job, which indicates whether the job has finished. A finished job has a state of "Complete" or "Failed". A job might also be blocked or running. +```powershell Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Complete True localhost Get-Process +``` -# GETTING THE RESULTS OF A JOB - +## GETTING THE RESULTS OF A JOB When you run a background job, the results do not appear immediately. Instead, the Start-Job cmdlet returns a job object that represents the job, but it does not contain the results. To get the results of a -background job, use the Receive-Job cmdlet. +background job, use the `Receive-Job` cmdlet. -The following command uses the Receive-Job cmdlet to get the results of -the job. It uses a job object saved in the $job variable to identify the +The following command uses the `Receive-Job` cmdlet to get the results of +the job. It uses a job object saved in the \$job variable to identify the job. +```powershell Receive-Job -Job $job +``` The Receive-Job cmdlet returns the results of the job. +``` Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -668 7 2672 6168 104 32.26 488 csrss + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 668 7 2672 6168 104 32.26 488 csrss # ... +``` +You can also save the results of a job in a variable. The following command +saves the results of the job in the \$job variable to the \$results variable. -You can also save the results of a job in a variable. The following -command saves the results of the job in the $job variable to the $results -variable. - +```powershell $results = Receive-Job -Job $job +``` And, you can save the results of the job in a file by using the redirection operator (>) or the Out-File cmdlet. The following command uses the -redirection operator to save the results of the job in the $job variable in +redirection operator to save the results of the job in the \$job variable in the Results.txt file. +```powershell Receive-Job -Job $job > results.txt +``` -# GETTING AND KEEPING PARTIAL JOB RESULTS - +## GETTING AND KEEPING PARTIAL JOB RESULTS The Receive-Job cmdlet gets the results of a background job. If the -job is complete, Receive-Job gets all job results. If the job is still +job is complete, `Receive-Job` gets all job results. If the job is still running, Receive-Job gets the results that have been generated thus far. -You can run Receive-Job commands again to get the remaining results. +You can run `Receive-Job` commands again to get the remaining results. -When Receive-Job returns results, by default, it deletes those results from -the cache where job results are stored. If you run another Receive-Job +When `Receive-Job` returns results, by default, it deletes those results from +the cache where job results are stored. If you run another `Receive-Job` command, you get only the results that are not yet received. -The following commands show the results of Receive-Job commands run +The following commands show the results of `Receive-Job` commands run before the job is complete. +```powershell C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -To prevent Receive-Job from deleting the job results that it has -returned, use the Keep parameter. As a result, Receive-Job returns all + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +To prevent `Receive-Job` from deleting the job results that it has +returned, use the **Keep** parameter. As a result, `Receive-Job` returns all of the results that have been generated until that time. The following commands show the effect of using the Keep parameter on a job that is not yet complete. +```powershell C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec C:\PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -103 4 11328 9692 56 1176 audiodg -804 14 12228 14108 100 101.74 1740 CcmExec -68 3 2632 664 29 0.36 1388 ccmsetup -749 22 21468 19940 203 122.13 3644 communicator -905 7 2980 2628 34 197.97 424 csrss -1121 25 28408 32940 174 430.14 3048 explorer - -# WAITING FOR THE RESULTS - - -If you run a command that takes a long time to complete, you can use -the properties of the job object to determine when the job is complete. -The following command uses the Get-Job object to get all of the background -jobs in the current session. - + 103 4 11328 9692 56 1176 audiodg + 804 14 12228 14108 100 101.74 1740 CcmExec + 68 3 2632 664 29 0.36 1388 ccmsetup + 749 22 21468 19940 203 122.13 3644 communicator + 905 7 2980 2628 34 197.97 424 csrss + 1121 25 28408 32940 174 430.14 3048 explorer +``` + +## WAITING FOR THE RESULTS + +If you run a command that takes a long time to complete, you can use the +properties of the job object to determine when the job is complete. The +following command uses the `Get-Job` object to get all of the background jobs +in the current session. + +```powershell Get-Job +``` The results appear in a table. The status of the job appears in the State column. -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Complete True localhost Get-Process -2 Job2 BackgroundJob Running True localhost Get-EventLog -Log Syst... -3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Recurse - -In this case, the State property reveals that Job 2 is still running. If -you were to use the Receive-Job cmdlet to get the job results now, the -results would be incomplete. You can use the Receive-Job cmdlet -repeatedly to get all of the results. By default, each time you use it, -you get only the results that were not already received, but you can use -the Keep parameter of the Receive-Job cmdlet to retain the results, even -though they were already received. +``` +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Complete True localhost Get-Process +2 Job2 BackgroundJob Running True localhost Get-EventLog -Log ... +3 Job3 BackgroundJob Complete True localhost dir -Path C:\* -Re... +``` + +In this case, the State property reveals that Job 2 is still running. If you +were to use the `Receive-Job` cmdlet to get the job results now, the results +would be incomplete. You can use the `Receive-Job` cmdlet repeatedly to get +all of the results. By default, each time you use it, you get only the results +that were not already received, but you can use the Keep parameter of the +Receive-Job cmdlet to retain the results, even though they were already +received. You can write the partial results to a file and then append newer results as they arrive or you can wait and check the state of the job later. -You can use the Wait parameter of the Receive-Job cmdlet, which +You can use the Wait parameter of the `Receive-Job` cmdlet, which does not return the command prompt until the job is complete and all results are available. -You can also use the Wait-Job cmdlet to wait for any or all of the results -of the job. Wait-Job lets you wait for a particular job, for all jobs, or +You can also use the `Wait-Job` cmdlet to wait for any or all of the results +of the job. `Wait-Job` lets you wait for a particular job, for all jobs, or for any of the jobs to be completed. -The following command uses the Wait-Job cmdlet to wait for a job with -# ID 10. - +The following command uses the Wait-Job cmdlet to wait for a job with ID 10. +```powershell Wait-Job -ID 10 +``` -As a result, the Windows PowerShell prompt is suppressed until the job -is completed. +As a result, the PowerShell prompt is suppressed until the job is completed. You can also wait for a predetermined period of time. This command uses the Timeout parameter to limit the wait to 120 seconds. When the time expires, the command prompt returns, but the job continues to run in the background. +```powershell Wait-Job -ID 10 -Timeout 120 +``` -# STOPPING A JOB +## STOPPING A JOB - -To stop a background job, use the Stop-Job cmdlet. The following command +To stop a background job, use the `Stop-Job` cmdlet. The following command starts a job to get every entry in the System event log. It saves the job -object in the $job variable. +object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {Get-EventLog -Log System} +``` The following command stops the job. It uses a pipeline operator (|) to -send the job in the $job variable to Stop-Job. +send the job in the \$job variable to `Stop-Job`. +```powershell $job | Stop-Job +``` -# DELETING A JOB - +## DELETING A JOB -To delete a background job, use the Remove-Job cmdlet. The following -command deletes the job in the $job variable. +To delete a background job, use the `Remove-Job` cmdlet. The following +command deletes the job in the \$job variable. +```powershell Remove-Job -Job $job +``` -# INVESTIGATING A FAILED JOB - +## INVESTIGATING A FAILED JOB To find out why a job failed, use the Reason subproperty of the job object. The following command starts a job without the required credentials. It -saves the job object in the $job variable. +saves the job object in the \$job variable. +```powershell $job = Start-Job -ScriptBlock {New-Item -Path HKLM:\Software\MyCompany} -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:\S... +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Failed False localhost New-Item -Path HKLM:... +``` The following command uses the Reason property to find the error that caused the job to fail. +```powershell $job.ChildJobs[0].JobStateInfo.Reason +``` In this case, the job failed because the remote computer required explicit credentials to run the command. The value of the Reason property is: -Connecting to remote server failed with the following error -message : Access is denied. +Connecting to remote server failed with the following error message : Access +is denied. -# SEE ALSO +## SEE ALSO [about_Remote_Jobs](about_Remote_Jobs.md) @@ -311,17 +331,16 @@ message : Access is denied. [about_PSSessions](about_PSSessions.md) -Start-Job - -Get-Job +[Start-Job](../Start-Job.md) -Receive-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Receive-Job](../Receive-Job.md) -Wait-Job +[Stop-Job](../Stop-Job.md) -Remove-Job +[Wait-Job](../Wait-Job.md) -Invoke-Command +[Remove-Job](../Remove-Job.md) +[Invoke-Command](../../Microsoft.PowerShell.Core/Invoke-Command.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Methods.md b/reference/6/Microsoft.PowerShell.Core/About/about_Methods.md index 47e1298d7137..a32eb5d38a92 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Methods.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Methods.md @@ -7,188 +7,202 @@ title: about_Methods --- # About methods -## about_methods - ## SHORT DESCRIPTION -Describes how to use methods to perform actions on objects in Windows PowerShell. +Describes how to use methods to perform actions on objects in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses objects to represent the items in data stores or the state of the computer. For example, FileInfo objects represent the files in file system drives and ProcessInfo objects represent the processes on the computer. -Objects have properties, which store data about the object, and methods that let you change the object. +PowerShell uses objects to represent the items in data stores or the state of +the computer. For example, FileInfo objects represent the files in file system +drives and ProcessInfo objects represent the processes on the computer. -A "method" is a set of instructions that specify an action you can perform on the object. For example, the FileInfo object includes the CopyTo method that copies the file that the FileInfo object represents. +Objects have properties, which store data about the object, and methods that +let you change the object. -To get the methods of any object, use the Get-Member cmdlet. Use its MemberType property with a value of "Method". The following command gets the methods of process objects. +A "method" is a set of instructions that specify an action you can perform on +the object. For example, the `FileInfo` object includes the `CopyTo` method that +copies the file that the `FileInfo` object represents. +To get the methods of any object, use the `Get-Member` cmdlet. Use its +**MemberType** property with a value of "Method". The following command gets +the methods of process objects. -``` +```powershell PS C:\> Get-Process | Get-Member -MemberType Method ``` +```output +TypeName: System.Diagnostics.Process - +Name MemberType Definition +---- ---------- ---------- +BeginErrorReadLine Method System.Void BeginErrorReadLine() +BeginOutputReadLine Method System.Void BeginOutputReadLine() +... +Kill Method System.Void Kill() +Refresh Method System.Void Refresh() +Start Method bool Start() +ToString Method string ToString() +WaitForExit Method bool WaitForExit(int milliseconds), ... +WaitForInputIdle Method bool WaitForInputIdle(int millisecon... ``` -TypeName: System.Diagnostics.Process - -Name MemberType Definition ----- ---------- ---------- -BeginErrorReadLine Method System.Void BeginErrorReadLine() -BeginOutputReadLine Method System.Void BeginOutputReadLine() -... -Kill Method System.Void Kill() -Refresh Method System.Void Refresh() -Start Method bool Start() -ToString Method string ToString() -WaitForExit Method bool WaitForExit(int milliseconds), System.Void WaitForExit() -WaitForInputIdle Method bool WaitForInputIdle(int milliseconds), bool WaitForInputIdle() -``` - - -To perform or "invoke" a method of an object, type a dot (.), the method name, and a set of parentheses "()". If the method has arguments, place the argument values inside the parentheses. The parentheses are required for every method call, even when there are no arguments. -For example, the following command invokes the Kill method of processes to end the Notepad process on the computer. As a result, the instance of Notepad closes. (The Get-Process command is enclosed in parentheses to insure that it runs before the Kill method is invoked. +To perform or "invoke" a method of an object, type a dot (.), the method name, +and a set of parentheses "()". If the method has arguments, place the argument +values inside the parentheses. The parentheses are required for every method +call, even when there are no arguments. +For example, the following command invokes the Kill method of processes to end +the Notepad process on the computer. As a result, the instance of Notepad +closes. (The `Get-Process` command is enclosed in parentheses to insure that +it runs before the Kill method is invoked. -``` +```powershell (Get-Process Notepad).Kill() ``` +Another very useful process is the Split method of strings. The split method +takes a delimiter character argument that tells the method where to split the +string. -Another very useful process is the Split method of strings. The split method takes a delimiter character argument that tells the method where to split the string. - - -``` -PS C:\> $a = "Try-Catch-Finally" -PS C:\> $a.Split("-") -Try -Catch +```powershell +PS C:\> $a = "Try-Catch-Finally" +PS C:\> $a.Split("-") +Try +Catch Finally ``` +As shown in the previous examples, you can invoke a method on an object that +you get by using a command or an object in a variable. -As shown in the previous examples, you can invoke a method on an object that you get by using a command or an object in a variable. - -Starting in Windows PowerShell 4.0, method invocation by using dynamic method names is supported. - +Starting in PowerShell 4.0, method invocation by using dynamic method names is +supported. ### LEARNING ABOUT METHODS -To find definitions of the methods of an object, go to help topic for the object type in MSDN and look for its methods page. For example, the following page describes the methods of process objects (System.Diagnostics.Process). - - -``` -http://msdn.microsoft.com/library/system.diagnostics.process_methods -``` +To find definitions of the methods of an object, go to help topic for the +object type in MSDN and look for its methods page. For example, the following +page describes the methods of process objects +[System.Diagnostics.Process](http://msdn.microsoft.com/library/system.diagnostics.process_methods). -To determine the arguments of a method, review the method definition, which is like the syntax diagram of a Windows PowerShell cmdlet. +To determine the arguments of a method, review the method definition, which is +like the syntax diagram of a PowerShell cmdlet. -A method definition might have one or more method signatures, which are like the parameter sets of Windows PowerShell cmdlets. The signatures show all of the valid formats of commands to invoke the method. - -For example, the CopyTo method of the FileInfo class contains the following two method signatures: - - -``` -1. CopyTo(String destFileName) -2. CopyTo(String destFileName, Boolean overwrite) -``` +A method definition might have one or more method signatures, which are like +the parameter sets of PowerShell cmdlets. The signatures show all of the valid +formats of commands to invoke the method. +For example, the `CopyTo` method of the `FileInfo` class contains the following +two method signatures: -The first method signature takes the destination file name (and a path). The following example use The first CopyTo method to copy the Final.txt file to the C:\Bin directory. + CopyTo(String destFileName) + CopyTo(String destFileName, Boolean overwrite) +The first method signature takes the destination file name (and a path). The +following example use The first `CopyTo` method to copy the Final.txt file to +the C:\\Bin directory. -``` +```powershell (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt") ``` +The second method signature take a destination file name and a Boolean value +that determines whether the destination file should be overwritten, if it +already exists. -The second method signature take a destination file name and a Boolean value that determines whether the destination file should be overwritten, if it already exists. - -The following example use The second CopyTo method to copy the Final.txt file to the C:\Bin directory, and to overwrite existing files. - +The following example use The second `CopyTo` method to copy the Final.txt file +to the C:\\Bin directory, and to overwrite existing files. ``` (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` - - ### METHODS OF SCALAR OBJECTS AND COLLECTIONS -The methods of one ("scalar") object of a particular type are often different from the methods of a collection of objects of the same type. -For example, every process has a Kill method, but a collection of processes does not have a Kill method. +The methods of one ("scalar") object of a particular type are often different +from the methods of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing methods of scalar objects and collections. +For example, every process has a `Kill` method, but a collection of processes +does not have a Kill method. -Beginning in Windows PowerShell 4.0, collection filtering by using a method syntax is supported. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing methods of scalar objects and collections. -If you submit a collection, but request a method that exists only on single ("scalar") objects, Windows invokes the method on every object in the collection. +Beginning in PowerShell 4.0, collection filtering by using a method syntax is +supported. -If the method exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you submit a collection, but request a method that exists only on single +("scalar") objects, PowerShell invokes the method on every object in the +collection. -This feature also works on properties of scalar objects and collections. For more information, see about_Properties. +If the method exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on properties of scalar objects and collections. For +more information, see [about_Properties](about_Properties.md). ### EXAMPLES -The following example runs the Kill method of individual process objects on a collection of process objects. This example works only on Windows PowerShell 3.0 and later versions of Windows PowerShell. -The first command starts three instances of the Notepad process. The second command uses the Get-Process command to get all three instance of the Notepad process and save them in the $p variable. +The following example runs the Kill method of individual process objects on a +collection of process objects. This example works only on PowerShell 3.0 and +later versions of PowerShell. +The first command starts three instances of the Notepad process. The second +command uses the `Get-Process` command to get all three instance of the Notepad +process and save them in the \$p variable. -``` -PS C:\> Notepad; Notepad; Notepad +```powershell +PS C:\> Notepad; Notepad; Notepad PS C:\> $p = Get-Process Notepad ``` +The third command uses the Count property of all collections to verify that +there are three processes in the \$p variable. -The third command uses the Count property of all collections to verify that there are three processes in the $p variable. - - -``` -PS C:\> $p.Count +```powershell +PS C:\> $p.Count 3 ``` +The fourth command runs the Kill method on all three processes in the \$p +variable. -The fourth command runs the Kill method on all three processes in the $p variable. - -This command works even though a collection of processes does not have a Kill method. - +This command works even though a collection of processes does not have a `Kill` +method. ``` PS C:\> $p.Kill() ``` +The fifth command uses the Get-Process command to confirm that the `Kill` +command worked. -The fifth command uses the Get-Process command to confirm that the Kill command worked. - - +```powershell +PS C:\> Get-Process Notepad +Get-Process : Cannot find a process with the name "notepad". Verify the proc +ess name and call the cmdlet again. +At line:1 char:12 ++ get-process <<<< notepad + + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process] +, ProcessCommandException + + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShel +l.Commands.GetProcessCommand ``` -PS C:\> Get-Process Notepad -Get-Process : Cannot find a process with the name "notepad". Verify the process name and call the cmdlet again. -At line:1 char:12 -+ get-process <<<< notepad - + CategoryInfo : ObjectNotFound: (notepad:String) [Get-Process], ProcessCommandException - + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.Commands.GetProcessCommand -``` - -To perform the same task on Windows PowerShell 2.0, use the Foreach-Object cmdlet to run the method on each object in the collection. +To perform the same task on PowerShell 2.0, use the `Foreach-Object` cmdlet to +run the method on each object in the collection. - -``` +```powershell PS C:\> $p | Foreach-Object {$_.Kill()} ``` - - ## SEE ALSO [about_Objects](about_Objects.md) [about_Properties](about_Properties.md) -Get-Member - +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md index 6d1f8847f78e..931280614067 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-29 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,51 +10,53 @@ title: about_Modules ## Short Description -Explains how to install, import, and use Windows PowerShell modules. +Explains how to install, import, and use PowerShell modules. ## Long Description -A module is a package that contains Windows PowerShell commands, such as -cmdlets, providers, functions, workflows, variables, and aliases. +A module is a package that contains PowerShell commands, such as cmdlets, +providers, functions, workflows, variables, and aliases. -People who write commands can use modules to organize their commands and -share them with others. People who receive modules can add the commands -in the modules to their Windows PowerShell sessions and use them just like -the built-in commands. +People who write commands can use modules to organize their commands and share +them with others. People who receive modules can add the commands in the +modules to their PowerShell sessions and use them just like the built-in +commands. -This topic explains how to use Windows PowerShell modules. -For information about how to write Windows PowerShell modules, see -[Writing a Windows PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) in the MSDN library. +This topic explains how to use PowerShell modules. For information about how +to write PowerShell modules, see [Writing a PowerShell Module](https://go.microsoft.com/fwlink/?LinkId=144916) +in the MSDN library. ## What Is a Module? -A module is a package of commands. All cmdlets and providers in your -session are added by a module or a snap-in. +A module is a package of commands. All cmdlets and providers in your session +are added by a module or a snap-in. ## Module Auto-Loading -Beginning in Windows PowerShell 3.0, Windows PowerShell imports -modules automatically the first time that you run any command in -an installed module. You can now use the commands in a module -without any set-up or profile configuration, so there's no need to -manage modules after you install them on your computer. +Beginning in PowerShell 3.0, PowerShell imports modules automatically the +first time that you run any command in an installed module. You can now use +the commands in a module without any set-up or profile configuration, so +there's no need to manage modules after you install them on your computer. -The commands in a module are also easier to find. The `Get-Command` cmdlet -now gets all commands in all installed modules, even if they are not yet -in the session, so you can find a command and use it without importing. +The commands in a module are also easier to find. The `Get-Command` cmdlet now +gets all commands in all installed modules, even if they are not yet in the +session, so you can find a command and use it without importing. Any of the following commands will import a module into your session. ### Run the Command + ```powershell Get-Mailbox -Identity Chris ``` ### Get the Command + ```powershell Get-Command Get-Mailbox ``` ### Get Help for the Command + ```powershell Get-Help Get-Mailbox ``` @@ -66,7 +68,7 @@ Only modules that are stored in the location specified by the PSModulePath environment variable are automatically imported. Modules in other locations must be imported by running the `Import-Module` cmdlet. -Also, commands that use Windows PowerShell providers do not automatically +Also, commands that use PowerShell providers do not automatically import a module. For example, if you use a command that requires the WSMan: drive, such as the `Get-PSSessionConfiguration` cmdlet, you might need to run the `Import-Module` cmdlet to import the Microsoft.WSMan.Management @@ -90,43 +92,40 @@ other useful information about managing modules. ## How to Install a Module -If you receive a module as a folder with files in it, you need -to install it on your computer before you can use it in Windows -PowerShell. +If you receive a module as a folder with files in it, you need to install it +on your computer before you can use it in PowerShell. -Most modules are installed for you. Windows PowerShell comes with -several preinstalled modules, sometimes called the "core" modules. -On Windows-based computers, if features that are included with the -operating system have cmdlets to manage them, those modules are preinstalled. -When you install a Windows feature, by using, for example, the Add Roles -and Features Wizard in Server Manager, or the Turn Windows features on or off -dialog box in Control Panel, any Windows PowerShell modules that are part -of the feature are installed. Many other modules come in an installer or -Setup program that installs the module. +Most modules are installed for you. PowerShell comes with several preinstalled +modules, sometimes called the "core" modules. On Windows-based computers, if +features that are included with the operating system have cmdlets to manage +them, those modules are preinstalled. When you install a Windows feature, by +using, for example, the Add Roles and Features Wizard in Server Manager, or +the Turn Windows features on or off dialog box in Control Panel, any +PowerShell modules that are part of the feature are installed. Many other +modules come in an installer or Setup program that installs the module. -To install a module folder: -1. Create a Modules directory for the current user if one does not exist. -To create a Modules directory, type: +Create a Modules directory for the current user if one does not exist. To +create a Modules directory, type: ```powershell New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules ``` -2. Copy the entire module folder into the Modules directory. -You can use any method to copy the folder, including Windows -Explorer and Cmd.exe, as well as Windows PowerShell. -In Windows PowerShell use the `Copy-Item` cmdlet. For example, to copy the -MyModule folder from C:\ps-test\MyModule to the Modules directory, type: +Copy the entire module folder into the Modules directory. You can use any +method to copy the folder, including Windows Explorer and Cmd.exe, as well as +PowerShell. In PowerShell use the `Copy-Item` cmdlet. For example, to copy the +MyModule folder from C:\\ps-test\\MyModule to the Modules directory, type: ```powershell -Copy-Item -Path C:\ps-test\MyModule -Destination $HOME\Documents\WindowsPowerShell\Modules +Copy-Item -Path C:\ps-test\MyModule -Destination ` + $HOME\Documents\WindowsPowerShell\Modules ``` You can install a module in any location, but installing your modules in a -default module location makes them easier to manage. For more information about -the default module locations, see the "Module and DSC Resource Locations, -and PSModulePath" section. +default module location makes them easier to manage. For more information +about the default module locations, see the "Module and DSC Resource +Locations, and PSModulePath" section. ## How to Find Installed Modules @@ -138,19 +137,20 @@ Get-Module -ListAvailable ``` To find the modules that have already been imported into your session, -at the Windows PowerShell prompt, type: +at the PowerShell prompt, type: ```powershell Get-Module ``` -For more information about the `Get-Module` cmdlet, see [Get-Module](../Get-Module.md). +For more information about the `Get-Module` cmdlet, see +[Get-Module](../Get-Module.md). ## How to Find the Commands in a Module -Use the `Get-Command` cmdlet to find all available commands. -You can use the parameters of the `Get-Command` cmdlet to filter commands -such as by module, name, and noun. +Use the `Get-Command` cmdlet to find all available commands. You can use the +parameters of the `Get-Command` cmdlet to filter commands such as by module, +name, and noun. To find all commands in a module, type: @@ -164,18 +164,17 @@ For example, to find the commands in the BitsTransfer module, type: Get-Command -Module BitsTransfer ``` -For more information about the `Get-Command` cmdlet, see [Get-Command](../Get-Command.md). +For more information about the `Get-Command` cmdlet, see +[Get-Command](../Get-Command.md). ## How to Get Help for the Commands in a Module -If the module contains Help files for the commands that it exports, -the `Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` -command format that you would use to get help for any command in Windows -PowerShell. +If the module contains Help files for the commands that it exports, the +`Get-Help` cmdlet will display the Help topics. Use the same `Get-Help` +command format that you would use to get help for any command in PowerShell. -Beginning in Windows PowerShell 3.0, you can download Help files for -a module and download updates to the Help files so they are never -obsolete. +Beginning in PowerShell 3.0, you can download Help files for a module and +download updates to the Help files so they are never obsolete. To get help for a commands in a module, type: @@ -195,20 +194,22 @@ To download and install the help files for the commands in a module, type: Update-Help -Module ``` -For more information, see [Get-Help](../Get-Help.md) and [Update-Help](../Update-Help.md). +For more information, see [Get-Help](../Get-Help.md) and +[Update-Help](../Update-Help.md). ## How to Import a Module -You might have to import a module or import a module file. Importing is required -when a module is not installed in the locations specified by the PSModulePath -environment variable ($env:PSModulePath), or the module consists of file, such -as a .dll or .psm1 file, instead of typical module that is delivered as a folder. +You might have to import a module or import a module file. Importing is +required when a module is not installed in the locations specified by the +PSModulePath environment variable ($env:PSModulePath), or the module consists +of file, such as a .dll or .psm1 file, instead of typical module that is +delivered as a folder. -You might also choose to import a module so that you can use the parameters of the -`Import-Module` command, such as the Prefix parameter, which adds a distinctive prefix -to the noun names of all imported commands, or the **NoClobber** parameter, which prevents -the module from adding commands that would hide or replace existing commands in the -session. +You might also choose to import a module so that you can use the parameters of +the `Import-Module` command, such as the Prefix parameter, which adds a +distinctive prefix to the noun names of all imported commands, or the +**NoClobber** parameter, which prevents the module from adding commands that +would hide or replace existing commands in the session. To import modules, use the `Import-Module` cmdlet. @@ -254,8 +255,8 @@ For more information about adding modules to your session, see The `Import-Module` command imports modules into your current Windows PowerShell session. This command affects only the current session. -To import a module into every Windows PowerShell session that you -start, add the `Import-Module` command to your Windows PowerShell +To import a module into every PowerShell session that you +start, add the `Import-Module` command to your PowerShell profile. For more information about profiles, see [about_Profiles](about_Profiles.md). @@ -285,46 +286,42 @@ a module does not uninstall the module. For more information about the ## Module and DSC Resource Locations, and PSModulePath -The following are default locations for Windows PowerShell modules. -Starting in Windows PowerShell 4.0, with the introduction of DSC, a -new default module and DSC resource folder was introduced. For more -information about DSC, see about_DesiredStateConfiguration. +The following are default locations for PowerShell modules. Starting in +PowerShell 4.0, with the introduction of DSC, a new default module and DSC +resource folder was introduced. For more information about DSC, see +about_DesiredStateConfiguration. -System: $pshome\Modules -(%windir%\System32\WindowsPowerShell\v1.0\Modules) -System modules are those that ship with Windows and Windows PowerShell. +- System: $pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) + System modules are those that ship with Windows and PowerShell. -Starting in Windows Powershell 4.0, when Windows PowerShell -Desired State Configuration (DSC) was introduced, DSC resources that are -included with Windows PowerShell are also stored in $pshome\Modules, -in the $pshome\Modules\PSDesiredStateConfiguration\DSCResources -folder. + Starting in PowerShell 4.0, when PowerShell Desired State Configuration + (DSC) was introduced, DSC resources that are included with PowerShell are + also stored in \$pshome\\Modules, in the + \$pshome\\Modules\\PSDesiredStateConfiguration\\DSCResources folder. -Current user: $home\Documents\WindowsPowerShell\Modules -(%UserProfile%\Documents\WindowsPowerShell\Modules) +- Current user: \$home\\Documents\\WindowsPowerShell\\Modules + (%UserProfile%\Documents\WindowsPowerShell\Modules) -or + or -$home\My Documents\WindowsPowerShell\Modules -(%UserProfile%\My Documents\WindowsPowerShell\Modules) -This is the location for user-added modules prior to Windows PowerShell 4.0. + \$home\\My Documents\\WindowsPowerShell\\Modules + (%UserProfile%\My Documents\WindowsPowerShell\Modules) + This is the location for user-added modules prior to PowerShell 4.0. -In Windows PowerShell 4.0 and later releases of Windows PowerShell, -user-added modules and DSC resources are stored in -C:\Program Files\WindowsPowerShell\Modules. Modules and DSC resources -in this location are accessible by all users of the computer. -This change was required because the DSC engine runs as local +In PowerShell 4.0 and later releases of PowerShell, user-added modules and DSC +resources are stored in C:\\Program Files\\WindowsPowerShell\\Modules. Modules +and DSC resources in this location are accessible by all users of the +computer. This change was required because the DSC engine runs as local system, and could not access user-specific paths, such as -$home\Documents\WindowsPowerShell\Modules. +\$home\\Documents\\WindowsPowerShell\\Modules. -Starting in Windows PowerShell 5.0, with the addition of the -PowerShellGet module, and the [PowerShell Gallery](https://www.powershellgallery.com) -of community- and Microsoft-created resources, -the `Install-Module` command installs modules and DSC resources to -C:\Program Files\WindowsPowerShell\Modules by default. +Starting in PowerShell 5.0, with the addition of the PowerShellGet module, and +the [PowerShell Gallery](https://www.powershellgallery.com) of community- and +Microsoft-created resources, the `Install-Module` command installs modules and +DSC resources to C:\\Program Files\\WindowsPowerShell\\Modules by default. -Note: To add or change files in the %Windir%\System32 directory, -start Windows PowerShell with the "Run as administrator" option. +Note: To add or change files in the %Windir%\\System32 directory, start +PowerShell with the "Run as administrator" option. You can change the default module locations on your system by changing the value of the PSModulePath environment variable ($Env:PSModulePath). The @@ -356,7 +353,7 @@ When you add a path to PSModulePath, `Get-Module` and `Import-Module` commands include modules in that path. The value that you set affects only the current session. To make the -change persistent, add the command to your Windows PowerShell profile +change persistent, add the command to your PowerShell profile or use System in Control Panel to change the value of the PSModulePath environment variable in the registry. @@ -369,70 +366,72 @@ For more information about the PSModulePath variable, see ## Modules and Name Conflicts -Name conflicts occur when more than one command in the session -has the same name. Importing a module causes a name conflict when -commands in the module have the same names as commands or items -in the session. +Name conflicts occur when more than one command in the session has the same +name. Importing a module causes a name conflict when commands in the module +have the same names as commands or items in the session. Name conflicts can result in commands being hidden or replaced. ### Hidden -A command is hidden when it is not the command that runs -when you type the command name, but you can run it -by using another method, such as by qualifying the command -name with the name of the module or snap-in in which it + +A command is hidden when it is not the command that runs when you type the +command name, but you can run it by using another method, such as by +qualifying the command name with the name of the module or snap-in in which it originated. ### Replaced -A command is replaced when you cannot run it because -it has been overwritten by a command with the same name. Even -when you remove the module that caused the conflict, you cannot -run a replaced command unless you restart the session. + +A command is replaced when you cannot run it because it has been overwritten +by a command with the same name. Even when you remove the module that caused +the conflict, you cannot run a replaced command unless you restart the +session. `Import-Module` might add commands that hide and replace commands in the current session. Also, commands in your session can hide commands that the module added. -To detect name conflicts, use the **All** parameter of the `Get-Command` cmdlet. -Beginning in Windows PowerShell 3.0, `Get-Command` gets only that commands -that run when you type the command name. The **All** parameter gets all commands -with the specific name in the session. +To detect name conflicts, use the **All** parameter of the `Get-Command` +cmdlet. Beginning in PowerShell 3.0, `Get-Command` gets only that commands +that run when you type the command name. The **All** parameter gets all +commands with the specific name in the session. To prevent name conflicts, use the **NoClobber** or **Prefix** parameters of -the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the names -of imported commands so that they are unique in the session. The **NoClobber** -parameter does not import any commands that would hide or replace existing -commands in the session. - -You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** parameters -of `Import-Module` to select only the commands that you want to import, -and you can exclude commands that cause name conflicts in your session. +the `Import-Module` cmdlet. The **Prefix** parameter adds a prefix to the +names of imported commands so that they are unique in the session. The +**NoClobber** parameter does not import any commands that would hide or +replace existing commands in the session. + +You can also use the **Alias**, **Cmdlet**, **Function**, and **Variable** +parameters of `Import-Module` to select only the commands that you want to +import, and you can exclude commands that cause name conflicts in your +session. Module authors can prevent name conflicts by using the DefaultCommandPrefix -property of the module manifest to add a default prefix to all command -names. The value of the Prefix parameter takes precedence over the value -of DefaultCommandPrefix. +property of the module manifest to add a default prefix to all command names. +The value of the Prefix parameter takes precedence over the value of +DefaultCommandPrefix. -Even if a command is hidden, you can run it by qualifying the command -name with the name of the module or snap-in in which it originated. +Even if a command is hidden, you can run it by qualifying the command name +with the name of the module or snap-in in which it originated. -The Windows PowerShell command precedence rules determine which command -runs when the session includes commands with the same name. +The PowerShell command precedence rules determine which command runs when the +session includes commands with the same name. For example, when a session includes a function and a cmdlet with the same -name, Windows PowerShell runs the function by default. When the session -includes commands of the same type with the same name, such as two cmdlets -with the same name, by default, it runs the most recently added command. +name, PowerShell runs the function by default. When the session includes +commands of the same type with the same name, such as two cmdlets with the +same name, by default, it runs the most recently added command. For more information, including an explanation of the precedence rules and -instructions for running hidden commands, see [about_Command_Precedence](about_Command_Precedence.md). +instructions for running hidden commands, see +[about_Command_Precedence](about_Command_Precedence.md). ## Modules and Snap-ins -You can add commands to your session from modules and snap-ins. Modules -can add all types of commands, including cmdlets, providers, and functions, -and items, such as variables, aliases, and Windows PowerShell drives. -Snap-ins can add only cmdlets and providers. +You can add commands to your session from modules and snap-ins. Modules can +add all types of commands, including cmdlets, providers, and functions, and +items, such as variables, aliases, and PowerShell drives. Snap-ins can add +only cmdlets and providers. Before removing a module or snap-in from your session, use the following commands to determine which commands will be removed. @@ -441,55 +440,52 @@ To find the source of a cmdlet in your session, use the following command format: ```powershell -Get-Command | Format-List -Property verb, noun, pssnapin, module +Get-Command | Format-List -Property verb,noun,pssnapin,module ``` For example, to find the source of the `Get-Date` cmdlet, type: ```powershell -Get-Command Get-Date | Format-List -Property verb, noun, pssnapin, module +Get-Command Get-Date | Format-List -Property verb,noun,pssnapin,module ``` -For more information about Windows PowerShell snap-ins, see [about_PSSnapins](about_PSSnapins.md). +For more information about PowerShell snap-ins, see +[about_PSSnapins](about_PSSnapins.md). ## Module-related Warnings and Errors -The commands that a module exports should follow the Windows PowerShell -command naming rules. If the module that you import exports cmdlets or -functions that have unapproved verbs in their names, the `Import-Module` -cmdlet displays the following warning message. +The commands that a module exports should follow the PowerShell command naming +rules. If the module that you import exports cmdlets or functions that have +unapproved verbs in their names, the `Import-Module` cmdlet displays the +following warning message. -WARNING: Some imported command names include unapproved verbs -which might make them less discoverable. Use the Verbose parameter -for more detail or type `Get-Verb` to see the list of approved verbs. +WARNING: Some imported command names include unapproved verbs which might make +them less discoverable. Use the Verbose parameter for more detail or type +`Get-Verb` to see the list of approved verbs. This message is only a warning. The complete module is still imported, -including the non-conforming commands. Although the message is displayed -to module users, the naming problem should be fixed by the module author. +including the non-conforming commands. Although the message is displayed to +module users, the naming problem should be fixed by the module author. -To suppress the warning message, use the **DisableNameChecking** parameter -of the `Import-Module` cmdlet. +To suppress the warning message, use the **DisableNameChecking** parameter of +the `Import-Module` cmdlet. ## Built-in Modules and Snap-ins -In Windows PowerShell 2.0 and in older-style host programs in Windows -PowerShell 3.0 and later, the core commands that are installed with -Windows PowerShell are packaged in snap-ins that are added automatically -to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that -implement the InitialSessionState.CreateDefault2 initial session state API -- -the core commands are packaged in modules. The default is -Microsoft.PowerShell.Core, which is always a snap-in. +In PowerShell 2.0 and in older-style host programs in PowerShell 3.0 and +later, the core commands that are installed with PowerShell are packaged in +snap-ins that are added automatically to every PowerShell session. -The Microsoft.PowerShell.Core snap-in is added to every session by -default. Modules are loaded automatically on first-use. +Beginning in PowerShell 3.0, for host programs that implement the +`InitialSessionState.CreateDefault2` initial session state API the +Microsoft.PowerShell.Core snap-in is added to every session by default. +Modules are loaded automatically on first-use. -NOTE: Remote sessions, including sessions that are started by using -the New-PSSession cmdlet, are older-style sessions in which the built-in +NOTE: Remote sessions, including sessions that are started by using the +`New-PSSession` cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. -The following modules (or snap-ins) are installed with Windows PowerShell. +The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics @@ -509,13 +505,13 @@ The following modules (or snap-ins) are installed with Windows PowerShell. ## Logging Module Events -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets -and functions in Windows PowerShell modules and snap-ins by setting the -LogPipelineExecutionDetails property of modules and snap-ins to $True. -You can also use a Group Policy setting, Turn on Module Logging, -to enable module logging in all Windows PowerShell sessions. -For more information, see [about_EventLogs](about_EventLogs.md) -and [about_Group_Policy_Settings](about_Group_Policy_Settings.md). +Beginning in PowerShell 3.0, you can record execution events for the cmdlets +and functions in PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to \$True. You can +also use a Group Policy setting, Turn on Module Logging, to enable module +logging in all PowerShell sessions. For more information, see +[about_EventLogs](about_EventLogs.md) and +[about_Group_Policy_Settings](about_Group_Policy_Settings.md). ## See Also From 6223e8d5786dd35825566987d7a0cc7fcf61ae34 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 29 Nov 2017 12:31:02 -0800 Subject: [PATCH 3/5] fixing broken links --- .../About/about_Group_Policy_Settings.md | 2 +- .../3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md | 4 ++-- .../About/about_Group_Policy_Settings.md | 2 +- .../4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md | 4 ++-- .../About/about_Group_Policy_Settings.md | 2 +- .../5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md | 4 ++-- .../About/about_Group_Policy_Settings.md | 2 +- .../5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md | 4 ++-- .../About/about_Group_Policy_Settings.md | 2 +- .../6/Microsoft.PowerShell.Core/About/about_Job_Details.md | 4 ++-- 10 files changed, 15 insertions(+), 15 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index ff4eed688151..8e1b9ca540f9 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -170,4 +170,4 @@ about_GroupPolicy [Update-Help](../Update-Help.md) -[Save-Help](../../Save-Help.md) +[Save-Help](../Save-Help.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 61ddaa58384e..74644935b7db 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) [Invoke-Command](../Invoke-Command.md) @@ -383,4 +383,4 @@ Id Name JobTriggers Command Enabled [Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) -[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) +[Get-ScheduledJob](../../PSScheduledJob/Get-ScheduledJob.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index ff4eed688151..8e1b9ca540f9 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -170,4 +170,4 @@ about_GroupPolicy [Update-Help](../Update-Help.md) -[Save-Help](../../Save-Help.md) +[Save-Help](../Save-Help.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 61ddaa58384e..74644935b7db 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) [Invoke-Command](../Invoke-Command.md) @@ -383,4 +383,4 @@ Id Name JobTriggers Command Enabled [Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) -[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) +[Get-ScheduledJob](../../PSScheduledJob/Get-ScheduledJob.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index ff4eed688151..8e1b9ca540f9 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -170,4 +170,4 @@ about_GroupPolicy [Update-Help](../Update-Help.md) -[Save-Help](../../Save-Help.md) +[Save-Help](../Save-Help.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 61ddaa58384e..74644935b7db 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) [Invoke-Command](../Invoke-Command.md) @@ -383,4 +383,4 @@ Id Name JobTriggers Command Enabled [Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) -[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) +[Get-ScheduledJob](../../PSScheduledJob/Get-ScheduledJob.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index ff4eed688151..8e1b9ca540f9 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -170,4 +170,4 @@ about_GroupPolicy [Update-Help](../Update-Help.md) -[Save-Help](../../Save-Help.md) +[Save-Help](../Save-Help.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md index 61ddaa58384e..74644935b7db 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) [Invoke-Command](../Invoke-Command.md) @@ -383,4 +383,4 @@ Id Name JobTriggers Command Enabled [Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) -[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) +[Get-ScheduledJob](../../PSScheduledJob/Get-ScheduledJob.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index ff4eed688151..8e1b9ca540f9 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -170,4 +170,4 @@ about_GroupPolicy [Update-Help](../Update-Help.md) -[Save-Help](../../Save-Help.md) +[Save-Help](../Save-Help.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md index 61ddaa58384e..74644935b7db 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](https://docs.microsoft.com/en-us/powershell/module/psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) [Invoke-Command](../Invoke-Command.md) @@ -383,4 +383,4 @@ Id Name JobTriggers Command Enabled [Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) -[Get-ScheduleJob](../../PSScheduledJob/Get-ScheduleJob.md) +[Get-ScheduledJob](../../PSScheduledJob/Get-ScheduledJob.md) From 11cc2f685e581d184e34594a71cbf7e5a9411168 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 29 Nov 2017 13:16:27 -0800 Subject: [PATCH 4/5] fixing more broken links --- .../About/about_Job_Details.md | 6 +++--- .../About/about_Job_Details.md | 6 +++--- .../About/about_Job_Details.md | 6 +++--- .../About/about_Job_Details.md | 6 +++--- .../About/about_Job_Details.md | 10 +++------- 5 files changed, 15 insertions(+), 19 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 74644935b7db..15e2f333b2a9 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs.md) [Invoke-Command](../Invoke-Command.md) @@ -371,9 +371,9 @@ Id Name JobTriggers Command Enabled [Remove-Job](../Remove-Job.md) -[Suspend-Job](../Remove-Job.md) +[Suspend-Job](../Suspend-Job.md) -[Resume-Job](../Resume-Job) +[Resume-Job](../Resume-Job.md) [New-PSSession](../New-PSSession.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 74644935b7db..15e2f333b2a9 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs.md) [Invoke-Command](../Invoke-Command.md) @@ -371,9 +371,9 @@ Id Name JobTriggers Command Enabled [Remove-Job](../Remove-Job.md) -[Suspend-Job](../Remove-Job.md) +[Suspend-Job](../Suspend-Job.md) -[Resume-Job](../Resume-Job) +[Resume-Job](../Resume-Job.md) [New-PSSession](../New-PSSession.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 74644935b7db..15e2f333b2a9 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs.md) [Invoke-Command](../Invoke-Command.md) @@ -371,9 +371,9 @@ Id Name JobTriggers Command Enabled [Remove-Job](../Remove-Job.md) -[Suspend-Job](../Remove-Job.md) +[Suspend-Job](../Suspend-Job.md) -[Resume-Job](../Resume-Job) +[Resume-Job](../Resume-Job.md) [New-PSSession](../New-PSSession.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md index 74644935b7db..15e2f333b2a9 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs.md) [Invoke-Command](../Invoke-Command.md) @@ -371,9 +371,9 @@ Id Name JobTriggers Command Enabled [Remove-Job](../Remove-Job.md) -[Suspend-Job](../Remove-Job.md) +[Suspend-Job](../Suspend-Job.md) -[Resume-Job](../Resume-Job) +[Resume-Job](../Resume-Job.md) [New-PSSession](../New-PSSession.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md index 74644935b7db..a755c5767f02 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,7 +357,7 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs) +[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs.md) [Invoke-Command](../Invoke-Command.md) @@ -371,16 +371,12 @@ Id Name JobTriggers Command Enabled [Remove-Job](../Remove-Job.md) -[Suspend-Job](../Remove-Job.md) +[Suspend-Job](../Suspend-Job.md) -[Resume-Job](../Resume-Job) +[Resume-Job](../Resume-Job.md) [New-PSSession](../New-PSSession.md) [Enter-PSSession](../Enter-PSSession.md) [Exit-PSSession](../Exit-PSSession.md) - -[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) - -[Get-ScheduledJob](../../PSScheduledJob/Get-ScheduledJob.md) From 00b241e23284a6922bc8e326d116cfb395d4ce77 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 29 Nov 2017 13:55:46 -0800 Subject: [PATCH 5/5] one more time with the links --- .../6/Microsoft.PowerShell.Core/About/about_Job_Details.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md index a755c5767f02..aec82776c721 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -357,8 +357,6 @@ Id Name JobTriggers Command Enabled [about_Remote](about_Remote.md) -[about_Scheduled_Jobs](../../psscheduledjob/about/about_scheduled_jobs.md) - [Invoke-Command](../Invoke-Command.md) [Start-Job](../Start-Job.md) @@ -371,10 +369,6 @@ Id Name JobTriggers Command Enabled [Remove-Job](../Remove-Job.md) -[Suspend-Job](../Suspend-Job.md) - -[Resume-Job](../Resume-Job.md) - [New-PSSession](../New-PSSession.md) [Enter-PSSession](../Enter-PSSession.md)