diff --git a/contributing/STYLE.md b/contributing/STYLE.md index b2f43ddd55be..cef7671966eb 100644 --- a/contributing/STYLE.md +++ b/contributing/STYLE.md @@ -24,7 +24,8 @@ Basic formatting guidelines: - Limit lines to 80 characters - Code blocks should be limited to 76 characters -- Within a paragraph, the following characters must be escaped using a leading `\` character: $,\`,\< +- Within a paragraph, the following characters must be escaped using a leading `\` character: + $, \`, \< - Tables need fit withing 76 characters - Manually wrap contents of cells across multiple lines - Use opening and closing `|` characters on each line @@ -59,13 +60,13 @@ Remove extra spaces at the end of lines. ## Titles/Headings -Only use [ATX headings][atx] (as opposed to = or \- style headers). +Only use [ATX headings][atx] (# style, as opposed to = or \- style headers). * Titles/headings should be surrounded by blank lines * Only the first letter of a title and any proper nouns in that title should be capitalized * Only one H1 per document -When editing reference content, the H2s are prescribed by platyPS and must not be added or removed. +When editing reference content, the H2s are prescribed by [platyPS][platyPS] and must not be added or removed. Adding or removing H2 causes a build break. ## Formatting syntax elements @@ -85,7 +86,7 @@ Adding or removing H2 causes a build break. ## Formatting code blocks -* All PowerShell syntax blocks should use ```powershell code fence marker. +* All PowerShell syntax blocks should use \`\`\`powershell … \`\`\` code fence markers. * Do **NOT** start PowerShell commands with the PowerShell prompt ("`PS C:\>`"). @@ -168,4 +169,5 @@ There are special rules for linking to reference topics from conceptual topics. [about-example]: https://github.com/PowerShell/PowerShell-Docs/blob/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md [links]: https://help.github.com/articles/relative-links-in-readmes/ [gfm-spec]: https://github.github.com/gfm/ -[semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ \ No newline at end of file +[semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ +[platyPS]: https://github.com/PowerShell/platyPS \ No newline at end of file diff --git a/dsc/bootstrapDsc.md b/dsc/bootstrapDsc.md index 10e0d686b78f..e4ec966f0256 100644 --- a/dsc/bootstrapDsc.md +++ b/dsc/bootstrapDsc.md @@ -82,7 +82,7 @@ Configuration SampleIISInstall Rename and move that file into the proper location on the VHD as `Pending.mof` by using the [Move-Item](https://technet.microsoft.comlibrary/hh849852.aspx) cmdlet. For example: ```powershell - Move-Item -Path C:\DSCTest\SampleIISInstall\localhost.mof -Destination E:\Windows\Sytem32\Configuration\Pending.mof + Move-Item -Path C:\DSCTest\SampleIISInstall\localhost.mof -Destination E:\Windows\System32\Configuration\Pending.mof ``` 6. Dismount the VHD by calling the [Dismount-VHD](https://technet.microsoft.com/library/hh848562.aspx) cmdlet. For example: diff --git a/gallery/psget/module/PreReleaseModule.md b/gallery/psget/module/PreReleaseModule.md new file mode 100644 index 000000000000..cf4f0ca1d800 --- /dev/null +++ b/gallery/psget/module/PreReleaseModule.md @@ -0,0 +1,200 @@ +--- +ms.date: 2017-09-26 +contributor: keithb +ms.topic: reference +keywords: gallery,powershell,cmdlet,psget +title: PrereleaseModule +--- + +# Prerelease Module Versions +Starting with version 1.6.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. Prior to this feature, prerelease items were limited to having a version beginning with 0. The goal of these features is to provide greater support for [SemVer v1.0.0](http://semver.org/spec/v1.0.0.html) versioning convention without breaking backwards compatibility with PowerShell versions 3 and above, or existing versions of PowerShellGet. This topic focuses on the module-specific features. The equivalent features for scripts are in the [Prerelease Versions of Scripts](../script/PrereleaseScript.md) topic. Using these features, publishers can identify a module or script as version 2.5.0-alpha, and later release a production-ready version 2.5.0 that supersedes the prerelease version. + +At a high level, the prerelease module features include: + +* Adding a Prerelease string to the PSData section of the module manifest identifies the module as a prerelease version. +When the module is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease items. +* Acquiring prerelease items requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Module, Install-Module, Update-Module, and Save-Module. +If the flag is not specified, prerelease items will not be shown. +* Module versions displayed by Find-Module, Get-InstalledModule, and in the PowerShell Gallery will be displayed as a single string with the Prerelease string appended, as in 2.5.0-alpha. + +Details for the features are included below. + +These changes do not affect the module version support that is built into PowerShell, and are compatible with PowerShell 3.0, 4.0, and 5. + +## Identifying a module version as a prerelease + +PowerShellGet support for prerelease versions requires the use of two fields within the Module Manifest: + +* The ModuleVersion included in the module manifest must be a 3-part version if a prerelease version is used, and must comply with existing PowerShell versioning. The version format would be A.B.C, where A, B, and C are all integers. +* The Prerelease string is specified in the module manifest, in the PSData section of PrivateData. +Detailed requirements on the Prerelease string are below. + +An example section of a module manifest that defines a module as a prerelease would look like the following: +```powershell +@{ + ModuleVersion = '2.5.0' + #--- + PrivateData = @{ + PSData = @{ + Prerelease = 'alpha' + } + } +} +``` + +The detailed requirements for Prerelease string are: + +* Prerelease string may only be specified when the ModuleVersion is 3 segments for Major.Minor.Build. This aligns with SemVer v1.0.0. +* A hyphen is the delimiter between the Build number and the Prerelease string. A hyphen may be included in the Prerelease string as the first character, only. +* The Prerelease string may contain only ASCII alphanumerics [0-9A-Za-z-]. It is a best practice to begin the Prerelease string with an alpha character, as it will be easier to identify that this is a prerelease version when scanning a list of items. +* Only SemVer v1.0.0 prerelease strings are supported at this time. Prerelease string __must not__ contain either period or + [.+], which are allowed in SemVer 2.0. +* Examples of supported Prerelease string are: -alpha, -alpha1, -BETA, -update20171020 + +__Prerelease versioning impact on sort order and installation folders__ + +Sort order changes when using a prerelease version, which is important when publishing to the PowerShell Gallery, and when installing modules using PowerShellGet commands. +If the Prerelease string is specified for two modules, the sort order is based on the string portion following the hyphen. So, version 2.5.0-alpha is less than 2.5.0-beta, which is less than 2.5.0-gamma. +If two modules have the same ModuleVersion, and only one has a Prerelease string, the module without the Prerelease string is assumed to be the production-ready version and will be sorted as a greater version than the prerelease version (which includes the Prerelease string). +As an example, when comparing releases 2.5.0 and 2.5.0-beta, the 2.5.0 version will be considered the greater of the two. + +When publishing to the PowerShell Gallery, by default the version of the module being published must have a greater version than any previously-published version that is in the PowerShell Gallery. + +## Finding and acquiring prerelease items using PowerShellGet commands + +Dealing with prerelease items using PowerShellGet Find-Module, Install-Module, Update-Module, and Save-Module commands requires adding the -AllowPrerelease flag. +If -AllowPrerelease is specified, prerelease items will be included if they are present. +If -AllowPrerelease flag is not specified, prerelease items will not be shown. + +The only exceptions to this in the PowerShellGet module commands are Get-InstalledModule, and some cases with Uninstall-Module. + +* Get-InstalledModule always will automatically show the prerelease information in the version string for modules. +* Uninstall-Module will by default uninstall the most recent version of a module, if __no version__ is specified. That behavior has not changed. However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required. + +## Examples +```powershell +# Assume the PowerShell Gallery has TestPackage module versions 1.8.0 and 1.9.0-alpha. If -AllowPrerelease is not specified, only version 1.8.0 will be returned. +C:\windows\system32> find-module TestPackage + +Version Name Repository Description +------- ---- ---------- ----------- +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... + +C:\windows\system32> find-module TestPackage -AllowPrerelease + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe... + +# To install a prerelease, always specify -AllowPrerelease. Specifying a prerelease version string is not sufficient. + +C:\windows\system32> Install-module TestPackage -RequiredVersion 1.9.0-alpha +PackageManagement\Find-Package : No match was found for the specified search criteria and module name 'TestPackage'. +Try Get-PSRepository to see all available registered module repositories. +At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.6.0\PSModule.psm1:1455 char:3 ++ PackageManagement\Find-Package @PSBoundParameters | Microsoft ... ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : ObjectNotFound: (Microsoft.Power...ets.FindPackage:FindPackage) [Find-Package], Exceptio + n + + FullyQualifiedErrorId : NoMatchFoundForCriteria,Microsoft.PowerShell.PackageManagement.Cmdlets.FindPackage + +# The previous command failed because -AllowPrerelease was not specified. +# Adding -AllowPrerelease will result in success. + +C:\windows\system32> Install-module TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease +C:\windows\system32> Get-InstalledModule TestPackage + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe... + +``` + +Side-by-side installation of versions of a module that differ only due to the prerelease specified is not supported. +When installing a module using PowerShellGet, different versions of the same module are installed side-by-side by creating a folder name using the ModuleVersion. +The ModuleVersion, without the prerelease string, is used for the folder name. +If a user installs MyModule version 2.5.0-alpha, it will be installed to the MyModule\2.5.0 folder. +If the user then installs 2.5.0-beta, the 2.5.0-beta version will __over-write__ the contents of the folder MyModule\2.5.0. +One advantage to this approach is that there is no need to un-install the prerelease version after installing the production-ready version. +The example below shows what to expect: + + +``` powershell +C:\windows\system32> Get-InstalledModule TestPackage -AllVersions + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe... +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... +1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe... + +C:\windows\system32> find-module TestPackage -AllowPrerelease + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-beta TestPackage PSGallery Package used to validate changes to the PowerShe... + +C:\windows\system32> Update-Module TestPackage -AllowPrerelease +C:\windows\system32> Get-InstalledModule TestPackage -AllVersions + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-beta TestPackage PSGallery Package used to validate changes to the PowerShe... +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... +1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe... + +``` + +Uninstall-Module will remove the latest version of a module when -RequiredVersion is not supplied. +If -RequiredVersion is specified, and is a prerelease, -AllowPrerelease must be added to the command. + +``` powershell +C:\windows\system32> Get-InstalledModule TestPackage -AllVersions + +Version Name Repository Description +------- ---- ---------- ----------- +2.0.0-alpha1 TestPackage PSGallery Package used to validate changes to the PowerShe... +1.9.0-beta TestPackage PSGallery Package used to validate changes to the PowerShe... +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... +1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe... + +C:\windows\system32> Uninstall-Module TestPackage -RequiredVersion 1.9.0-beta +Uninstall-Module : The '-AllowPrerelease' parameter must be specified when using the Prerelease string in +MinimumVersion, MaximumVersion, or RequiredVersion. +At line:1 char:1 ++ Unnstall-Module TestPackage -RequiredVersion 1.9.0-beta ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Uninstall-Module], ArgumentException + + FullyQualifiedErrorId : AllowPrereleaseRequiredToUsePrereleaseStringInVersion,Uninnstall-Module + + + +C:\windows\system32> Uninstall-Module TestPackage -RequiredVersion 1.9.0-beta -AllowPrerelease +C:\windows\system32> Get-InstalledModule TestPackage -AllVersions + +Version Name Repository Description +------- ---- ---------- ----------- +2.0.0-alpha1 TestPackage PSGallery Package used to validate changes to the PowerShe... +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... +1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe... + +C:\windows\system32> Uninstall-Module TestPackage +C:\windows\system32> Get-InstalledModule TestPackage -AllVersions + +Version Name Repository Description +------- ---- ---------- ----------- +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... +1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe... + + +``` + + + +## More details +### [Prerelease Script Versions](../script/PrereleaseScript.md) +### [Find-Module](./psget_find-module.md) +### [Install-Module](./psget_install-module.md) +### [Save-Module](./psget_save-module.md) +### [Update-Module](./psget_update-module.md) +### [Get-InstalledModule](./psget_get-installedmodule.md) +### [UnInstall-Module](./psget_uninstall-module.md) diff --git a/gallery/psget/module/psget_find-module.md b/gallery/psget/module/psget_find-module.md index 4149e0c1ec55..3e940ab6a236 100644 --- a/gallery/psget/module/psget_find-module.md +++ b/gallery/psget/module/psget_find-module.md @@ -63,6 +63,9 @@ Find-Module -Name PSReadline -MinimumVersion 1.0.0.12 -MaximumVersion 1.0.0.13 # Find a module with exact version Find-Module -Name AzureRM -RequiredVersion 1.3.2 +# Find a module with a specific prerelease version +Find-Module -Name AzureRM -RequiredVersion 1.3.2-alpha -AllowPrerelease + # Find a module from the specified repository Find-Module -Name Contoso -Repository MyLocalRepo diff --git a/gallery/psget/module/psget_install-module.md b/gallery/psget/module/psget_install-module.md index 75024aea7748..fd159d37f604 100644 --- a/gallery/psget/module/psget_install-module.md +++ b/gallery/psget/module/psget_install-module.md @@ -77,6 +77,12 @@ Install-Module -Name ContosoServer -MinimumVersion 1.0 # Install a specific version of a module Install-Module -Name ContosoServer -RequiredVersion 1.1.3 +# Install a specific prerelease version of a module +Install-Module -Name ContosoServer -RequiredVersion 1.1.3-alpha -AllowPrerelease + +# Install the latest version of a module by name, including prelrelease versions if one exists +Install-Module -Name ContosoServer -AllowPrerelease + # Install the latest version of a module to $home\Documents\WindowsPowerShell\Modules. Install-Module -Name ContosoServer -Scope CurrentUser diff --git a/gallery/psget/module/psget_save-module.md b/gallery/psget/module/psget_save-module.md index fbc1a66d995b..56a980cb9781 100644 --- a/gallery/psget/module/psget_save-module.md +++ b/gallery/psget/module/psget_save-module.md @@ -50,5 +50,14 @@ Find-Command -Name "Get-NestedRequiredModule4" -Repository "INT" | Save-Module - # Save the role capability modules by piping the Find-RoleCapability output to Save-Module cmdlet. Find-RoleCapability -Name Maintenance,MyJeaRole | Save-Module -Path C:\MyModulesPath + +# Save a specific prerelease version of a module to C:\MySavedModuleLocation +Save-Module -Name ContosoServer -RequiredVersion 1.1.3-alpha -Path C:\MySavedModuleLocation -AllowPrerelease + +# Install the latest version of a module by name, including prelrelease versions if one exists +Install-Module -Name ContosoServer -Path C:\MySavedModuleLocation -AllowPrerelease + + + ``` diff --git a/gallery/psget/module/psget_update-module.md b/gallery/psget/module/psget_update-module.md index 940fc06ee9fe..7e5fb685b7d7 100644 --- a/gallery/psget/module/psget_update-module.md +++ b/gallery/psget/module/psget_update-module.md @@ -39,38 +39,38 @@ Get-Command -Name Update-Module -Module PowerShellGet -Syntax ## Example commands ```powershell -PS C:\\windows\\system32> Update-Module -Name ContosoServer -RequiredVersion 1.5 -PS C:\\windows\\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase +PS C:\windows\system32> Update-Module -Name ContosoServer -RequiredVersion 1.5 +PS C:\windows\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase Name : ContosoServer Version : 2.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.0 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.0 Name : ContosoServer Version : 1.5 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.5 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.5 Name : ContosoServer Version : 1.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.0 -PS C:\\windows\\system32> Get-InstalledModule +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.0 +PS C:\windows\system32> Get-InstalledModule Version Name Repository Description ------- ---- ---------- ----------- 1.0 ContosoServer MSPSGallery ContosoServer module 1.5 ContosoServer MSPSGallery ContosoServer module 2.0 ContosoServer MSPSGallery ContosoServer module -PS C:\\windows\\system32> Update-Module -Name ContosoServer -PS C:\\windows\\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase +PS C:\windows\system32> Update-Module -Name ContosoServer +PS C:\windows\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase Name : ContosoServer Version : 2.8.1 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.8.1 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.8.1 Name : ContosoServer Version : 2.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.0 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.0 Name : ContosoServer Version : 1.5 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.5 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.5 Name : ContosoServer Version : 1.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.0 -PS C:\\windows\\system32> Get-InstalledModule +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.0 +PS C:\windows\system32> Get-InstalledModule Version Name Repository Description ------- ---- ---------- ----------- 1.0 ContosoServer MSPSGallery ContosoServer module @@ -79,8 +79,36 @@ Version Name Repository Description 2.8.1 ContosoServer MSPSGallery ContosoServer module ``` +### Update the module with a prerelease version, requires -AllowPrerelease flag +```powershell +PS C:\windows\system32> Get-InstalledModule +Version Name Repository Description +------- ---- ---------- ----------- +1.0 ContosoServer MSPSGallery ContosoServer module +1.5 ContosoServer MSPSGallery ContosoServer module +2.0 ContosoServer MSPSGallery ContosoServer module +2.8.1 ContosoServer MSPSGallery ContosoServer module + +PS C:\windows\system32> Find-Module ContosoServer -AllowPrerelease + +Version Name Repository Description +------- ---- ---------- ----------- +3.0.0-alpha ConstosoServer MSPSGallery The PowerShell Contoso Server deployment tools... + +PS C:\windows\system32> Update-Module -Name ContosoServer -AllowPrerelease +PS C:\windows\system32> Get-InstalledModule +Version Name Repository Description +------- ---- ---------- ----------- +1.0 ContosoServer MSPSGallery ContosoServer module +1.5 ContosoServer MSPSGallery ContosoServer module +2.0 ContosoServer MSPSGallery ContosoServer module +2.8.1 ContosoServer MSPSGallery ContosoServer module +3.0.0-alpha ContosoServer MSPSGallery ContosoServer module -### Update the TestDepWithNestedRequiredModules1 module with dependencies. +``` + + +### Update the TestDepWithNestedRequiredModules1 module with dependencies. ```powershell Find-Module -Name TestDepWithNestedRequiredModules1 -Repository LocalRepo -AllVersions @@ -104,5 +132,8 @@ Version    Name                                2.5        RequiredModule3                     LocalRepo   RequiredModule3 module 1.0        TestDepWithNestedRequiredModules1   LocalRepo   TestDepWithNestedRequiredModules1 module 2.0        TestDepWithNestedRequiredModules1   LocalRepo   TestDepWithNestedRequiredModules1 module + + + ``` diff --git a/gallery/psget/script/PreReleaseScript.md b/gallery/psget/script/PreReleaseScript.md new file mode 100644 index 000000000000..b9563f39fdd1 --- /dev/null +++ b/gallery/psget/script/PreReleaseScript.md @@ -0,0 +1,157 @@ +--- +ms.date: 2017-10-17 +contributor: keithb +ms.topic: reference +keywords: gallery,powershell,cmdlet,psget +title: PrereleaseScript +--- + +# Prerelease Versions of Scripts + +Starting with version 1.6.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. Prior to this feature, prerelease items were limited to having a version beginning with 0. The goal of these features is to provide greater support for [SemVer v1.0.0](http://semver.org/spec/v1.0.0.html) versioning convention without breaking backwards compatibility with PowerShell versions 3 and above, or existing versions of PowerShellGet. +This topic focuses on the script-specific features. The equivalent features for modules are in the [Prerelease Module Versions](../module/PrereleaseModule.md) topic. Using these features, publishers can identify a script as version 2.5.0-alpha, and later release a production-ready version 2.5.0 that supersedes the prerelease version. + +At a high level, the prerelease script features include: + +* Adding a PrereleaseString suffix to the version string in the script manifest. +When the scripts is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease items. +* Acquiring prerelease items requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Script, Install-Script, Update-Script, and Save-Script. +If the flag is not specified, prerelease items will not be shown. +* Script versions displayed by Find-Script, Get-InstalledScript, and in the PowerShell Gallery will be displayed with the PrereleaseString, as in 2.5.0-alpha. + +Details for the features are included below. + + +## Identifying a script version as a prerelease + +PowerShellGet support for prerelease versions is easier for scripts than modules. +Script versioning is only supported by PowerShellGet, so there are no compatibility issues caused by adding the prerelease string. +To identify a script in the PowerShell Gallery as a prerelease, add a prerelease suffix to a properly-formatted version string in the script metadata. + +An example section of a script manifest with a prerelease version would look like the following: +```powershell +<#PSScriptInfo + +.VERSION 3.2.1-alpha12 + +.GUID + +... + +#> + +``` + +To use a prerelease suffix, the version string must meet the following requirements: + +* A prerelease suffix may only be specified when the Version is 3 segments for Major.Minor.Build. This aligns with SemVer v1.0.0 +* The prerelease suffix is a string which begins with a hyphen, and may contain ASCII alphanumerics [0-9A-Za-z-] +* Only SemVer v1.0.0 prerelease strings are supported at this time, so the prerelease suffix __must not__ contain either period or + [.+], which are allowed in SemVer 2.0 +* Examples of supported PrereleaseString strings are: -alpha, -alpha1, -BETA, -update20171020 + +__Prerelease versioning impact on sort order and installation folders__ + +Sort order changes when using a prerelease version, which is important when publishing to the PowerShell Gallery, and when installing scripts using PowerShellGet commands. +If two scripts versions with the version number exist, the sort order is based on the string portion following the hyphen. So, version 2.5.0-alpha is less than 2.5.0-beta, which is less than 2.5.0-gamma. +If two scripts have the same version number, and only one has a PrereleaseString, the script __without__ the prerelease suffix is assumed to be the production-ready version and will be sorted as a greater version than the prerelease version. +As an example, when comparing releases 2.5.0 and 2.5.0-beta, the 2.5.0 version will be considered the greater of the two. + +When publishing to the PowerShell Gallery, by default the version of the script being published must have a greater version than any previously-published version that is in the PowerShell Gallery. +A publisher may update version 2.5.0-alpha with 2.5.0-beta, or with 2.5.0 (with no prerelease suffix). + +## Finding and acquiring prerelease items using PowerShellGet commands + +Dealing with prerelease items using PowerShellGet Find-Script, Install-Script, Update-Script, and Save-Script commands requires adding the -AllowPrerelease flag. +If -AllowPrerelease is specified, prerelease items will be included if they are present. +If -AllowPrerelease flag is not specified, prerelease items will not be shown. + +The only exceptions to this in the PowerShellGet script commands are Get-InstalledScript, and some cases with Uninstall-Script. + +* Get-InstalledScript always will automatically show the prerelease information in the version string if it is present. +* Uninstall-Script will by default uninstall the most recent version of a script, if __no version__ is specified. That behavior has not changed. However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required. + +## Examples +```powershell +# Assume the PowerShell Gallery has TestPackage versions 1.8.0 and 1.9.0-alpha. If -AllowPrerelease is not specified, only version 1.8.0 will be returned. +C:\windows\system32> Find-Script TestPackage + +Version Name Repository Description +------- ---- ---------- ----------- +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... + +C:\windows\system32> Find-Script TestPackage -AllowPrerelease + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to PowerShe... + +# To install a prerelease, you must specify -AllowPrerelease. Specifying a prerelease version string is not sufficient. + +C:\windows\system32> Install-Script TestPackage -RequiredVersion 1.9.0-alpha +PackageManagement\Find-Package : No match was found for the specified search criteria and script name 'TestPackage'. +Try Get-PSRepository to see all available registered script repositories. +At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.6.0\PSModule.psm1:1455 char:3 ++ PackageManagement\Find-Package @PSBoundParameters | Microsoft ... ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : ObjectNotFound: (Microsoft.Power...ets.FindPackage:FindPackage) [Find-Package], Exceptio + n + + FullyQualifiedErrorId : NoMatchFoundForCriteria,Microsoft.PowerShell.PackageManagement.Cmdlets.FindPackage + +# The previous command failed because -AllowPrerelease was not specified. +# Adding -AllowPrerelease will result in success. + +C:\windows\system32> Install-Script TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease +C:\windows\system32> Get-InstalledScript TestPackage + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to PowerShe... + +# Note that Get-InstalledScript shows the prerelease version. +# If -RequiredVersion is not specified, all installed scripts will be displayed by Get-InstalledScript +``` + +Uninstall-Script will remove the current version of a script when -RequiredVersion is not supplied. +If -RequiredVersion is specified, and is a prerelease, -AllowPrerelease must be added to the command. + +``` powershell +C:\windows\system32> Get-InstalledScript TestPackage + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to PowerShe... + +C:\windows\system32> Uninstall-Script TestPackage -RequiredVersion 1.9.0-alpha +Uninstall-Script: The '-AllowPrerelease' parameter must be specified when using the Prerelease string in +MinimumVersion, MaximumVersion, or RequiredVersion. +At line:1 char:1 ++ Unnstall-Script TestPackage -RequiredVersion 1.9.0-beta ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Uninstall-Script], ArgumentException + + FullyQualifiedErrorId : AllowPrereleaseRequiredToUsePrereleaseStringInVersion,Uninnstall-script + + +C:\windows\system32> Uninstall-Script TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease +# Since script versions are not installed side-by-side, the above could be simply "Uninstall-Script TestPackage" + +C:\windows\system32> Get-Installedscript TestPackage +PackageManagement\Get-Package : No match was found for the specified search criteria and script names 'testpackage'. +At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.5.0.0\PSModule.psm1:4088 char:9 ++ PackageManagement\Get-Package @PSBoundParameters | Microsoft. ... ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : ObjectNotFound: (Microsoft.Power...lets.GetPackage:GetPackage) [Get-Package], Exception + + FullyQualifiedErrorId : NoMatchFound,Microsoft.PowerShell.PackageManagement.Cmdlets.GetPackage + + +``` + + + +## More details +### [Prerelease Module Versions](../module/PrereleaseModule.md) +### [Find-script](./psget_find-script.md) +### [Install-script](./psget_install-script.md) +### [Save-script](./psget_save-script.md) +### [Update-script](./psget_update-script.md) +### [Get-Installedscript](./psget_get-installedscript.md) +### [UnInstall-script](./psget_uninstall-script.md) diff --git a/gallery/psget/script/psget_find-script.md b/gallery/psget/script/psget_find-script.md index a44466e472dc..ffb040210dfa 100644 --- a/gallery/psget/script/psget_find-script.md +++ b/gallery/psget/script/psget_find-script.md @@ -70,6 +70,9 @@ Find-Script -Name Connect-O365 -MinimumVersion 1.1 -MaximumVersion 1.6.2 # Find a script with exact version Find-Script -Name Connect-O365 -RequiredVersion 1.5.7 +# Find a script with a specific pre-release version +Find-Script -Name Connect-O365 -RequiredVersion 1.3.2-alpha -AllowPrerelease + # Find a script from the specified repository Find-Script -Name Fabrikam-ServerScript -Repository MyLocalRepo diff --git a/gallery/psget/script/psget_install-script.md b/gallery/psget/script/psget_install-script.md index 8f1c5e26ce6e..89f0a11e1f12 100644 --- a/gallery/psget/script/psget_install-script.md +++ b/gallery/psget/script/psget_install-script.md @@ -10,38 +10,30 @@ title: Install-Script Installs the PowerShell script files from online repositories to the local computer. - ## Description -The Install-Script cmdlet acquires a script payload from a repository, verifies that the payload is a valid PowerShell script, and copies the script file to a specified installation location. - -The default repositories Install-Script operates against are configurable through the Register-PSRepository, Set-PSRepository, Unregister-PSRepository, and Get-PSRepository cmdlets. When operating against multiple repositories, Install-Script installs the first script that matches the specified search criteria (Name, MinimumVersion, or MaximumVersion) from the first repository without any error. - - -Install-Script cmdlet downloads one or more modules from an online gallery, validates and installs them on the local computer to the specified installation scope. +The Install-Script cmdlet finds and downloads one or more scripts from an online gallery, validates and installs them on the local computer to the specified installation scope. -The Install-Script cmdlet gets one or more modules that meet specified criteria from an online gallery, verifies that search results are valid modules, and copies module folders to the installation location. +When no scope is defined, or when the value of the Scope parameter is AllUsers, the script is installed to %systemdrive%:\Program Files\WindowsPowerShell\scripts. When the value of Scope is CurrentUser, the script is installed to $home\Documents\WindowsPowerShell\scripts. -When no scope is defined, or when the value of the Scope parameter is AllUsers, the module is installed to %systemdrive%:\Program Files\WindowsPowerShell\Modules. When the value of Scope is CurrentUser, the module is installed to $home\Documents\WindowsPowerShell\Modules. +You can filter your results based on minimum and exact versions of specified scripts. -You can filter your results based on minimum and exact versions of specified modules. - -- No Side-by-side version support for PowerShell Script files -- Script dependency installation support -- **Untrusted prompt:** User acceptance is required for installing the modules from an untrusted repository. -- -Force reinstalls the installed module +Some important notes: +- Scripts are installed single files. As a result, only one copy of a script is installed, and multiple versions of scripts cannot be installed side-by-side on a system. +- Scripts may define dependencies on external modules, which will be installed when Install-Script is run. +- **Untrusted prompt:** User acceptance is required for installing the scripts from an untrusted repository. - RequiredVersion installs the specified version in SxS with existing versions on PowerShell version 5.0 or newer. -Wildcards are not supported in -Name on Install-Module, Save-Module, Uninstall-Module, Install-Script, Save-Script, and Uninstall-Script cmdlets. +Wildcards are not supported in -Name on Install-Script, Save-Script, and Uninstall-Script cmdlets. ### Scope -Specifies the installation scope of the module. The acceptable values for this parameter are: AllUsers and CurrentUser. +Specifies the installation scope of the script. The acceptable values for this parameter are: AllUsers and CurrentUser. The default installation scope is AllUsers. -The AllUsers scope lets modules be installed in a location that is accessible to all users of the computer, that is, "$env:SystemDrive\Program Files\WindowsPowerShell\Modules". +The AllUsers scope lets scripts be installed in a location that is accessible to all users of the computer, that is, "$env:SystemDrive\Program Files\WindowsPowerShell\scripts". -The CurrentUser scope lets modules be installed only to "$home\Documents\WindowsPowerShell\Modules", so that the module is available only to the current user. +The CurrentUser scope lets scripts be installed only to "$home\Documents\WindowsPowerShell\scripts", so that the script is available only to the current user. Specifies the installation scope of the script. Valid values are: AllUsers and CurrentUser. The default is CurrentUser. @@ -62,17 +54,15 @@ The AllUsers scope specifies to install a script to %systemdrive%:\ProgramFiles\ This cmdlet runs on Windows PowerShell 3.0 or later releases of Windows PowerShell, on Windows 7 or Windows 2008 R2 and later releases of Windows. -If an installed module cannot be imported (that is, if it does not have a .psm1, .psd1, or .dll of the same name within the folder), installation fails unless you add the Force parameter to your command. - -If a version of the module on the computer matches the value specified for the Name parameter, and you have not added the MinimumVersion or RequiredVersion parameter, Install-Script silently continues without installing that module. If the MinimumVersion or RequiredVersion parameters are specified, and the existing module does not match the values in that parameter, then an error occurs. To be more specific: if the version of the currently-installed module is either lower than the value of the MinimumVersion parameter, or not equal to the value of the RequiredVersion parameter, an error occurs. If the version of the installed module is greater than the value of the MinimumVersion parameter, or equal to the value of the RequiredVersion parameter, Install-Script silently continues without installing that module. +If a version of the script on the computer matches the value specified for the Name parameter, and you have not added the MinimumVersion or RequiredVersion parameter, Install-Script silently continues without installing that script. If the MinimumVersion or RequiredVersion parameters are specified, and the existing script does not match the values in that parameter, then an error occurs. To be more specific: if the version of the currently-installed script is either lower than the value of the MinimumVersion parameter, or not equal to the value of the RequiredVersion parameter, an error occurs. If the version of the installed script is greater than the value of the MinimumVersion parameter, or equal to the value of the RequiredVersion parameter, Install-Script silently continues without installing that script. -Install-Script returns an error if no module exists in the online gallery that matches the specified name. +Install-Script returns an error if no script exists in the online gallery that matches the specified name. -To install multiple modules, specify an array of the module names, separated by commas. You cannot add MinimumVersion or RequiredVersion if you specify multiple module names. +To install multiple scripts, specify an array of the script names, separated by commas. You cannot add MinimumVersion or RequiredVersion if you specify multiple script names. -By default, modules are installed to the Program Files folder, to prevent confusion when you are installing Windows PowerShell Desired State Configuration (DSC) resources.You can pipe multiple PSGetItemInfo objects to Install-Script; this is another way of specifying multiple modules to install in a single command. +By default, scripts are installed to the Program Files folder. You can pipe multiple PSGetItemInfo objects to Install-Script; this is another way of specifying multiple scripts to install in a single command. -To help prevent running modules that contain malicious code, installed modules are not automatically imported by installation. As a security best practice, evaluate module code before running any cmdlets or functions in a module for the first time. +To help prevent running scripts that contain malicious code, installed scripts are not automatically imported by installation. As a security best practice, evaluate script code before running any cmdlets or functions in a script for the first time. ## Cmdlet syntax @@ -293,42 +283,46 @@ ExternalScript Required-Script2.ps1 C:\\Users\\manikb\\Documents\\WindowsPowerSh ```powershell -# Install a module by name -Install-Script -Name MyDscModule +# Install a script by name +Install-Script -Name MyDscscript -# Install multiple modules +# Install multiple scripts Install-Script ContosoClient,ContosoServer -# Install a module using its minimum version +# Install a script using its minimum version Install-Script -Name ContosoServer -MinimumVersion 1.0 -# Install a specific version of a module +# Install a specific version of a script Install-Script -Name ContosoServer -RequiredVersion 1.1.3 -# Install the latest version of a module to $home\Documents\WindowsPowerShell\Modules. +# Install a specific prerelease version of a script +Install-Script -Name ContosoServer -RequiredVersion 1.1.3-alpha -AllowPrerelease + +# Install the latest version of a script to $home\Documents\WindowsPowerShell\scripts. Install-Script -Name ContosoServer -Scope CurrentUser -# if a module is already available under $env:PSModulePath, below command fails with 'ModuleAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' +# if a script is already available under $env:PSModulePath, below command fails with 'scriptAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' Install-Script ContosoServer -RequiredVersion 1.5 -# if a module is already available under $env:PSModulePath, below command fails with 'ModuleAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' +# if a script is already available under $env:PSModulePath, below command fails with 'scriptAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' Install-Script ContosoServer -MinimumVersion 2.5 -# Install multiple modules from multiple registered repositories +# Install multiple scripts from multiple registered repositories Install-Script ContosoClient,ContosoServer -Repository PSGallery, PrivatePSGallery -# Install a module with -WhatIf +# Install a script with -WhatIf Install-Script ContosoClient -WhatIf -# Install a module with -Confirm. A prompt will be displayed to confirm the installation. +# Install a script with -Confirm. A prompt will be displayed to confirm the installation. Install-Script ContosoClient -WhatIf -# -Force option reinstalls the installed module +# -Force option reinstalls the installed script Install-Script ContosoClient -Force -# Install a module with dependencies -Install-Script -Name +# Install a script with dependencies +Install-Script -Name ContosoClient +# Install a script # Install a script from the registered repository with ScriptSourceLocation Install-Script Connect-AzureVM @@ -471,158 +465,25 @@ The scripts install location 'C:\Program Files\WindowsPowerShell\Scripts' is req ```powershell -# Find a module and install it +# Find a script and install it Find-Script -Name "MyDSC*" | Install-Script -# Find a module and install it to the CurrentUser scope +# Find a script and install it to the CurrentUser scope Find-Script -Name "MyDSC*" | Install-Script -Scope CurrentUser # Find commands by name and install them # The first command finds the specified commands in the INT repository, and then uses the pipeline operator to pass them to Install-Script to install them. -# The second command uses Get-InstalledModule to verify the modules from the prior command are installed. +# The second command uses Get-Installedscript to verify the scripts from the prior command are installed. Find-Command -Repository "INT" -Name Get-ContosoClient,Get-ContosoServer | Install-Script -Get-InstalledModule - -# This command finds the resource named MyResource and passes it to the Install-Script cmdlet by using the pipeline operator. The Install-Script cmdlet installs the module for the resource. -# If you pipe multiple resources to the Install-Script cmdlet from the same module, Install-Script attempts to install the module only once. -Find-DscResource -Name "MyResource" | Install-Script -Get-InstalledModule +Get-Installedscript # Find multiple role capabilities and install them Find-RoleCapability -Name MyJeaRole, Maintenance | Install-Script -Get-InstalledModule - -``` - -## Side-by-Side Version Support on PowerShell 5.0 or newer - -PowerShellGet supports the side-by-side (SxS) module version support in Install-Script, Update-Script, and Publish-Script cmdlets that run in Windows PowerShell 5.0 or newer. - -### Install-Script examples - -```powershell -# Install a version of the module -Install-Script -Name PSScriptAnalyzer -RequiredVersion 1.1.0 -Repository PSGallery -Get-Script -ListAvailable -Name PSScriptAnalyzer | Format-List Name,Version,ModuleBase - -Name : PSScriptAnalyzer -Version : 1.1.0 -ModuleBase : C:\Program Files\WindowsPowerShell\Modules\PSScriptAnalyzer\1.1.0 - -# Install another version of the module in Side-by-Side with already installed version. -Install-Script -Name PSScriptAnalyzer -RequiredVersion 1.1.1 -Repository PSGallery -Get-Script -ListAvailable -Name PSScriptAnalyzer | Format-List Name,Version,ModuleBase - -Name : PSScriptAnalyzer -Version : 1.1.1 -ModuleBase : C:\Program Files\WindowsPowerShell\Modules\PSScriptAnalyzer\1.1.1 -Name : PSScriptAnalyzer -Version : 1.1.0 -ModuleBase : C:\Program Files\WindowsPowerShell\Modules\PSScriptAnalyzer\1.1.0 - -# Get all versions of an installed module -Get-InstalledModule -Name PSScriptAnalyzer -AllVersions -Version Name Repository Description -------- ---- ---------- ----------- -1.1.0 PSScriptAnalyzer PSGallery PSScriptAnalyzer provides script analysis... -1.1.1 PSScriptAnalyzer PSGallery PSScriptAnalyzer provides script analysis... - +Get-Installedscript ``` -## Install module with its dependencies - -```powershell - -# Find a module -Find-Module -Name TypePx -Repository PSGallery - -Version Name Repository Description -------- ---- ---------- ----------- -2.0.1.20 TypePx PSGallery The TypePx module adds properties and methods to the m... - -# Find a module and its dependencies -Find-Module -Name TypePx -Repository PSGallery -IncludeDependencies - -Version Name Repository Description -------- ---- ---------- ----------- -2.0.1.20 TypePx PSGallery The TypePx module adds properties and methods to the m... -1.0.5.18 SnippetPx PSGallery The SnippetPx module enhances the snippet experience i... - -# Discover the dependencies list without adding -IncludeDependencies -$result = Find-Module -Name TypePx -Repository PSGallery -$result.Dependencies - -Name Value ----- ----- -Name SnippetPx -CanonicalId powershellget:SnippetPx/#https://www.powershellgallery.com/api/v2/ - - -# Now install the module along with its dependencies -Install-Script -Name TypePx -Repository PSGallery -Verbose - -VERBOSE: Repository details, Name = 'PSGallery', Location = 'https://www.powershellgallery.com/api/v2/'; IsTrusted = -'False'; IsRegistered = 'True'. -VERBOSE: Using the provider 'PowerShellGet' for searching packages. -VERBOSE: Using the specified source names : 'PSGallery'. -VERBOSE: Getting the provider object for the PackageManagement Provider 'NuGet'. -VERBOSE: The specified Location is 'https://www.powershellgallery.com/api/v2/' and PackageManagementProvider is -'NuGet'. -VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id='TypePx'' for ''. -VERBOSE: Total package yield:'1' for the specified package 'TypePx'. -VERBOSE: Performing the operation "Install-Script" on target "Version '2.0.1.20' of module 'TypePx'". - -Untrusted repository -You are installing the modules from an untrusted repository. If you trust this repository, change its -InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from -'PSGallery'? -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): Y -VERBOSE: The installation scope is specified to be 'AllUsers'. -VERBOSE: The specified module will be installed in 'C:\Program Files\WindowsPowerShell\Modules'. -VERBOSE: The specified Location is 'NuGet' and PackageManagementProvider is 'NuGet'. -VERBOSE: Downloading module 'TypePx' with version '2.0.1.20' from the repository -'https://www.powershellgallery.com/api/v2/'. -VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id='TypePx'' for ''. -VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id='SnippetPx'' for ''. -VERBOSE: InstallPackage' - name='SnippetPx', -version='1.0.5.18',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: DownloadPackage' - name='SnippetPx', -version='1.0.5.18',destination='C:\Users\manikb\AppData\Local\Temp\1027042896\SnippetPx\SnippetPx.nupkg', -uri='https://www.powershellgallery.com/api/v2/package/SnippetPx/1.0.5.18' -VERBOSE: Downloading 'https://www.powershellgallery.com/api/v2/package/SnippetPx/1.0.5.18'. -VERBOSE: Completed downloading 'https://www.powershellgallery.com/api/v2/package/SnippetPx/1.0.5.18'. -VERBOSE: Completed downloading 'SnippetPx'. -VERBOSE: Hash for package 'SnippetPx' does not match hash provided from the server. -VERBOSE: InstallPackageLocal' - name='SnippetPx', -version='1.0.5.18',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: InstallPackage' - name='TypePx', -version='2.0.1.20',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: DownloadPackage' - name='TypePx', -version='2.0.1.20',destination='C:\Users\manikb\AppData\Local\Temp\1027042896\TypePx\TypePx.nupkg', -uri='https://www.powershellgallery.com/api/v2/package/TypePx/2.0.1.20' -VERBOSE: Downloading 'https://www.powershellgallery.com/api/v2/package/TypePx/2.0.1.20'. -VERBOSE: Completed downloading 'https://www.powershellgallery.com/api/v2/package/TypePx/2.0.1.20'. -VERBOSE: Completed downloading 'TypePx'. -VERBOSE: Hash for package 'TypePx' does not match hash provided from the server. -VERBOSE: InstallPackageLocal' - name='TypePx', -version='2.0.1.20',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: Installing the dependency module 'SnippetPx' with version '1.0.5.18' for the module 'TypePx'. -VERBOSE: Module 'SnippetPx' was installed successfully to path 'C:\Program -Files\WindowsPowerShell\Modules\SnippetPx\1.0.5.18'. -VERBOSE: Module 'TypePx' was installed successfully to path 'C:\Program -Files\WindowsPowerShell\Modules\TypePx\2.0.1.20'. - - -# Get the installed modules -Get-InstalledModule - -Version Name Repository Description -------- ---- ---------- ----------- -1.0.5.18 SnippetPx PSGallery The SnippetPx module enhances the snippet experience i... -2.0.1.20 TypePx PSGallery The TypePx module adds properties and methods to the m... -``` ## Error scenarios @@ -642,79 +503,6 @@ Install-Script ContosoClient,ContosoServer -MinimumVersion 2.0 ``` -## Installing a script with dependent scripts and modules - -```powershell -# Installing a script with dependent scripts and modules -Find-Script -Repository GalleryINT -Name Script-WithDependencies2 -IncludeDependencies -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.0 Script-WithDependencies2 Script GalleryINT Description for the Script-WithDependencies2 script -2.5 RequiredModule1 Module GalleryINT RequiredModule1 module -2.5 RequiredModule2 Module GalleryINT RequiredModule2 module -2.5 RequiredModule3 Module GalleryINT RequiredModule3 module -2.0 RequiredModule4 Module GalleryINT RequiredModule4 module -1.5 RequiredModule5 Module GalleryINT RequiredModule5 module -2.5 Required-Script1 Script GalleryINT Description for the Required-Script1 script -2.5 Required-Script2 Script GalleryINT Description for the Required-Script2 script -2.5 Required-Script3 Script GalleryINT Description for the Required-Script3 script - -Get-InstalledScript -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.0 Required-Script3 Script GalleryINT Description for the Required-Script3 script -1.0 Demo-Script Script LocalRepo1 Script file description goes here -2.5 Required-Script2 Script GalleryINT Description for the Required-Script2 script -Get-InstalledModule -Install-Script -Repository GalleryINT -Name Script-WithDependencies2 -Scope CurrentUser -Get-InstalledScript -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.0 Required-Script3 Script GalleryINT Description for the Required-Script3 script -1.0 Demo-Script Script LocalRepo1 Script file description goes here -2.5 Required-Script1 Script GalleryINT Description for the Required-Script1 script -2.5 Required-Script2 Script GalleryINT Description for the Required-Script2 script -2.0 Script-WithDependencies2 Script GalleryINT Description for the Script-WithDependencies2 script -Get-InstalledModule -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.5 RequiredModule1 Module GalleryINT RequiredModule1 module -2.5 RequiredModule2 Module GalleryINT RequiredModule2 module -2.5 RequiredModule3 Module GalleryINT RequiredModule3 module -2.0 RequiredModule4 Module GalleryINT RequiredModule4 module -1.5 RequiredModule5 Module GalleryINT RequiredModule5 module - -# Contents of Script-WithDependencies2 file. -<#PSScriptInfo -.VERSION 2.0 -.GUID 90082fa1-0b84-49fb-a00e-0a624fbb6584 -.AUTHOR manikb -.COMPANYNAME Microsoft Corporation -.COPYRIGHT (c) 2015 Microsoft Corporation. All rights reserved. -.TAGS Tag1 Tag2 Tag-Script-WithDependencies2-2.0 -.LICENSEURI http://script-withdependencies2.com/license -.PROJECTURI http://script-withdependencies2.com/ -.ICONURI http://script-withdependencies2.com/icon -.EXTERNALMODULEDEPENDENCIES -.REQUIREDSCRIPTS Required-Script1,Required-Script2,Required-Script3 -.EXTERNALSCRIPTDEPENDENCIES -.RELEASENOTES -Script-WithDependencies2 release notes -#> -#Requires -Module RequiredModule1 -#Requires -Module @{ModuleName = 'RequiredModule2'; ModuleVersion = '2.0'} -#Requires -Module @{RequiredVersion = '2.5'; ModuleName = 'RequiredModule3'} -#Requires -Module @{ModuleVersion = '1.1'; ModuleName = 'RequiredModule4'; MaximumVersion = '2.0'} -#Requires -Module @{MaximumVersion = '1.5'; ModuleName = 'RequiredModule5'} -<# -.DESCRIPTION -Description for the Script-WithDependencies2 script -#> -Param() -Function Test-FunctionFromScript\_Script-WithDependencies2 { Get-Date } -Workflow Test-WorkflowFromScript\_Script-WithDependencies2 { Get-Date } -``` - ## Install-Script and Get-InstalledScript cmdlets Install-Script cmdlet lets you to install a specific script file along with its dependencies to the specified scope. By default, scripts are installed to the AllUsers scope. Get-InstalledScript cmdlet lets you to get the list of script files which were installed using Install-Script cmdlet. diff --git a/gallery/psget/script/psget_save-script.md b/gallery/psget/script/psget_save-script.md index 6668e1ef1cca..9eae7d135cac 100644 --- a/gallery/psget/script/psget_save-script.md +++ b/gallery/psget/script/psget_save-script.md @@ -1,6 +1,6 @@ --- -ms.date: 2017-06-12 -contributor: manikb +ms.date: 2017-10-17 +contributor: keithb ms.topic: reference keywords: gallery,powershell,cmdlet,psget title: Save-Script @@ -47,3 +47,10 @@ Version Name Author Description 1.5 Fabrikam-ClientScript manikb Description for the Fabrikam-ClientScript script ``` +### Example 3: Save a prerelease version of a script from a repository +This command saves the latest version of the script Fabrikam-ClientScript from GalleryINT repository to the local folder C:\ScriptSharingDemo + +```powershell +Save-Script -Name Fabrikam-ClientScript -Path C:\ScriptSharingDemo -AllowPrerelease +``` + diff --git a/gallery/psget/script/psget_uninstall-script.md b/gallery/psget/script/psget_uninstall-script.md index e130fa7c29fc..ef2620329855 100644 --- a/gallery/psget/script/psget_uninstall-script.md +++ b/gallery/psget/script/psget_uninstall-script.md @@ -62,5 +62,11 @@ At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : ObjectNotFound: (Microsoft.Power...lets.GetPackage:GetPackage) [Get-Package], Exception + FullyQualifiedErrorId : NoMatchFound,Microsoft.PowerShell.PackageManagement.Cmdlets.GetPackage + +# Uninstall a specified prerelease version of a script +Uninstall-Script Required-Script1 -RequiredVersion 2.5.0-alpha -AllowPrerelease -Verbose +VERBOSE: Performing the operation "Uninstall-Script" on target "Version '2.5.0-alpha' of script 'Required-Script1'". +VERBOSE: Successfully uninstalled the script 'Required-Script1' from script base 'C:\Users\manikb\Documents\WindowsPowerShell\Scripts'. + ``` diff --git a/gallery/psget/script/psget_update-script.md b/gallery/psget/script/psget_update-script.md index 2f91cfe891dd..963ac527b9cd 100644 --- a/gallery/psget/script/psget_update-script.md +++ b/gallery/psget/script/psget_update-script.md @@ -38,6 +38,13 @@ Version Name Type Repository Description ------- ---- ---- ---------- ----------- 1.5 Fabrikam-Script Script GalleryINT Description for the Fabrikam-Script script +# Update a specific script to the required prerelease version +Update-Script -Name Fabrikam-Script -RequiredVersion 1.5.0-alpha -AllowPrerelease +Get-InstalledScript -Name Fabrikam-Script +Version Name Type Repository Description +------- ---- ---- ---------- ----------- +1.5.0-alpha Fabrikam-Script Script GalleryINT Description for the Fabrikam-Script script + # Update all installed scripts Install-Script -Name Fabrikam-ServerScript -RequiredVersion 1.0 -Repository GalleryINT -Scope CurrentUser Get-InstalledScript diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md index 7a62b5bef11e..0f745ac3aa94 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,232 +7,246 @@ title: about_Object_Creation --- # About Object Creation -## about_Object_Creation - ## SHORT DESCRIPTION -Explains how to create objects in Windows PowerShell®. +Explains how to create objects in PowerShell. ## LONG DESCRIPTION -You can create objects in Windows PowerShell and use the objects that you create in commands and scripts. - -There are several ways to create objects: - -New-Object: -The New-Object cmdlet creates an instance of a .NET Framework object or COM object. +You can create objects in PowerShell and use the objects that you create in +commands and scripts. -Hash tables: +There are several ways to create objects: -Beginning in Windows PowerShell 3.0, you can create objects from hash tables of property names and property values. +- `New-Object`: This cmdlet creates an instance of a .NET Framework object or + COM object. -Import-Csv: +- Hash tables: Beginning in PowerShell 3.0, you can create objects + from hash tables of property names and property values. -The Import-Csv cmdlet creates custom objects (PSCustomObject) from the items in a CSV file. Each row is an object instance and each column is an object property. +- `Import-Csv`: This cmdlet creates custom objects (PSCustomObject) from the + items in a CSV file. Each row is an object instance and each column is an + object property. This topic will demonstrate and discuss each of these methods. - ## NEW-OBJECT -The New-Object cmdlet provides a robust and consistent way to create new objects. The cmdlet works with almost all types and in all supported versions of Windows PowerShell. -To create a new object, specify either the type of a .NET Framework class or a ProgID of a COM object. +The `New-Object` cmdlet provides a robust and consistent way to create new +objects. The cmdlet works with almost all types and in all supported versions +of PowerShell. -For example, the following command creates a Version object. +To create a new object, specify either the type of a .NET Framework class or a +ProgID of a COM object. +For example, the following command creates a Version object. -``` -PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 +```powershell +PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 PS C:\> $v ``` - - -``` -Major Minor Build Revision ------ ----- ----- -------- +```Output +Major Minor Build Revision +----- ----- ----- -------- 2 0 0 1 ``` +```powershell +PS C:\> $v | Get-Member - -``` -PS C:\> $v | Get-Member - TypeName: System.Version ``` - For more information, see the help topic for the New-Object cmdlet. - ### CREATE 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: ``` -[]@{=;=} +[]@{ + = + = +} ``` - -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. ### CREATE CUSTOM OBJECTS FROM HASH TABLES -Custom objects are very useful and they are very easy to create by using the hash table method. To create a custom object, use the PSCustomObject class, a class designed specifically for this purpose. - -Custom objects are an excellent way to return customized output from a function or script; far more useful than returning formatted output that cannot be reformatted or piped to other commands. - -The commands in the Test-Object function set some variable values and then use those values to create a custom object. (You can see this object in use in the example section of the Update-Help cmdlet help topic.) - -``` -function Test-Object -{ $ModuleName = "PSScheduledJob" - $HelpCulture = "en-us" - $HelpVersion = "3.1.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} - - $ModuleName = "PSWorkflow" - $HelpCulture = "en-us" - $HelpVersion = "3.0.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} +Custom objects are very useful and they are very easy to create by using the +hash table method. To create a custom object, use the PSCustomObject class, a +class designed specifically for this purpose. + +Custom objects are an excellent way to return customized output from a +function or script; far more useful than returning formatted output that +cannot be reformatted or piped to other commands. + +The commands in the `Test-Object function` set some variable values and then +use those values to create a custom object. You can see this object in use in +the example section of the `Update-Help` cmdlet help topic. + +```powershell +function Test-Object { + $ModuleName = "PSScheduledJob" + $HelpCulture = "en-us" + $HelpVersion = "3.1.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } + $ModuleName = "PSWorkflow" + $HelpCulture = "en-us" + $HelpVersion = "3.0.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } } ``` +The output of this function is a collection of custom objects formatted as a +table by default. -The output of this function is a collection of custom objects formatted as a table by default. - +```powershell +PS C:\> Test-Object -``` -PS C:\> Test-Object - -ModuleName UICulture Version ---------- --------- ------- -PSScheduledJob en-us 3.1.0.0 +ModuleName UICulture Version +--------- --------- ------- +PSScheduledJob en-us 3.1.0.0 PSWorkflow en-us 3.0.0.0 ``` +Users can manage the properties of the custom objects just as they do with +standard objects. -Users can manage the properties of the custom objects just as they do with standard objects. - - -``` -PS C:\> (Test-Object).ModuleName - PSScheduledJob +```powershell +PS C:\> (Test-Object).ModuleName + PSScheduledJob PSWorkflow ``` - - #### CREATE NON-CUSTOM OBJECTS FROM HASH TABLES -You can also use hash tables to create objects for non-custom classes. When you create an object for a non-custom class, the full namespace name is required unless class is in the System namespace. Use only the properties of the class. -For example, the following command creates a session option object. +You can also use hash tables to create objects for non-custom classes. When +you create an object for a non-custom class, the full namespace name is +required unless class is in the System namespace. Use only the properties of +the class. +For example, the following command creates a session option object. +```powershell +[System.Management.Automation.Remoting.PSSessionOption]@{ + IdleTimeout=43200000 + SkipCnCheck=$True +} ``` -[System.Management.Automation.Remoting.PSSessionOption]@{IdleTimeout=43200000; SkipCnCheck=$True} -``` - -The requirements of the hash table feature, especially the null constructor requirement, eliminate many existing classes. However, most Windows PowerShell option classes are designed to work with this feature, as well as other very useful classes, such as the ScheduledJobTrigger class. +The requirements of the hash table feature, especially the null constructor +requirement, eliminate many existing classes. However, most PowerShell option +classes are designed to work with this feature, as well as other very useful +classes, such as the ScheduledJobTrigger class. +```powershell +[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{ + Frequency="Daily" + At="15:00" +} -``` -[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{Frequency="Daily";At="15:00"} - -Id Frequency Time DaysOfWeek Enabled --- --------- ---- ---------- ------- -0 Daily 6/6/2012 3:00:00 PM True +Id Frequency Time DaysOfWeek Enabled +-- --------- ---- ---------- ------- +0 Daily 6/6/2012 3:00:00 PM True ``` +You can also use the hash table feature when setting parameter values. For +example, the value of the **SessionOption** parameter of the New-PSSession +cmdlet and the value of the JobTrigger parameter of `Register-ScheduledJob` +can be a hash table. -You can also use the hash table feature when setting parameter values. For example, the value of the SessionOption parameter of the New-PSSession cmdlet and the value of the JobTrigger parameter of Register-ScheduledJob can be a hash table. - - -``` -New-PSSession -ComputerName Server01 -SessionOption @{IdleTimeout=43200000; SkipCnCheck=$True} -Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{Frequency="Daily";At="15:00"} +```powershell +New-PSSession -ComputerName Server01 -SessionOption @{ + IdleTimeout=43200000 + SkipCnCheck=$True +} +Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{ + Frequency="Daily" + At="15:00" +} ``` - - ### IMPORT-CSV -You can create custom objects from the items in a CSV file. When you use the Import-Csv cmdlet to import the CSV file, the cmdlet creates a custom object (PSCustomObject) for each item in the file. The column names are the object properties. -For example, if you import a CSV file of computer asset data, Import-CSV creates a collection of custom objects from the input. +You can create custom objects from the items in a CSV file. When you use the +`Import-Csv` cmdlet to import the CSV file, the cmdlet creates a custom object +(PSCustomObject) for each item in the file. The column names are the object +properties. +For example, if you import a CSV file of computer asset data, `Import-CSV` +creates a collection of custom objects from the input. ``` -#In Servers.csv -AssetID, Name, OS, Department -003, Server01, Windows Server 2012, IT -103, Server33, Windows 7, Marketing +#In Servers.csv +AssetID, Name, OS, Department +003, Server01, Windows Server 2012, IT +103, Server33, Windows 7, Marketing 212, Server35, Windows 8, Finance ``` +```powershell +PS C:\> $a = Import-Csv Servers.csv +PS C:\> $a - -``` -PS C:\> $a = Import-Csv Servers.csv -PS C:\> $a - -AssetID Name OS Department -------- ---- -- ---------- -003 Server01 Windows Server 2012 IT -103 Server33 Windows 7 Marketing +AssetID Name OS Department +------- ---- -- ---------- +003 Server01 Windows Server 2012 IT +103 Server33 Windows 7 Marketing 212 Server35 Windows 8 Finance ``` - Use the Get-Member cmdlet to confirm the object type. - -``` +```powershell PS C:\> $a | Get-Member ``` +```Output +TypeName: System.Management.Automation.PSCustomObject - -``` -TypeName: System.Management.Automation.PSCustomObject - -Name MemberType Definition ----- ---------- ---------- -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -AssetID NoteProperty System.String AssetID=003 -Department NoteProperty System.String Department=IT -Name NoteProperty System.String Name=Server01 +Name MemberType Definition +---- ---------- ---------- +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +AssetID NoteProperty System.String AssetID=003 +Department NoteProperty System.String Department=IT +Name NoteProperty System.String Name=Server01 OS NoteProperty System.String OS=Windows Server 2012 ``` - You can use the custom objects just as you would standard objects. - -``` +```powershell PS C:\> $a | where {$_.OS -eq "Windows 8"} ``` - - -``` -AssetID Name OS Department -------- ---- -- ---------- +```output +AssetID Name OS Department +------- ---- -- ---------- 212 Server35 Windows 8 Finance ``` - For more information, see the help topic for the Import-Csv cmdlet. - ## SEE ALSO [about_Objects](about_Objects.md) @@ -243,9 +257,8 @@ For more information, see the help topic for the Import-Csv cmdlet. [about_Pipelines](about_Pipelines.md) -Get-Member - -Import-Csv +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -New-Object +[Import-Csv](../../Microsoft.PowerShell.Utility/Import-Csv.md) +[New-Object](../../Microsoft.PowerShell.Utility/New-Object.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Objects.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Objects.md index 88ab499af532..58308cabd6d7 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Objects.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Objects.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -58,20 +58,13 @@ directory objects are passed down the pipeline to the second command. The second command `where { $_.PsIsContainer -eq $false }` uses the PsIsContainer property of all file system objects to select only -files, which have a value of False ($false) in their PsIsContainer +files, which have a value of False (\$false) in their PsIsContainer property. Folders, which are containers and, thus, have a value of -True ($true) in their PsIsContainer property, are not selected. +True (\$true) in their PsIsContainer property, are not selected. The second command passes only the file objects to the third command `Format-List`, which displays the file objects in a list. -## For More Information - -Now that you understand a bit about objects, see the [about_Methods](about_Methods.md) -help topic to learn how to find and use object methods, the -[about_Properties](about_Properties.md) topic to learn how to find and use object properties, -and the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) topic, to learn how to find an object type. - ## See Also [about_Methods](about_Methods.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 6e83191b889c..01d129ccc4bb 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,84 +10,85 @@ title: about_Operator_Precedence ## SHORT DESCRIPTION -Lists the Windows PowerShell operators in precedence order. +Lists the PowerShell operators in precedence order. -[This topic was contributed by Kirk Munro, a Windows PowerShell MVP +[This topic was contributed by Kirk Munro, a PowerShell MVP from Ottawa, Ontario] ## LONG DESCRIPTION -Windows PowerShell operators let you construct simple, but powerful -expressions. This topic lists the operators in precedence order. -Precedence order is the order in which Windows PowerShell evaluates -the operators when multiple operators appear in the same expression. - -When operators have equal precedence, Windows PowerShell evaluates -them from left to right. The exceptions are the assignment operators, -the cast operators, and the negation operators (!, -not, -bnot), -which are evaluated from right to left. - -You can use enclosures, such as parentheses, to override the -standard precedence order and force Windows PowerShell to evaluate -the enclosed part of an expression before an unenclosed part. - -In the following list, operators are listed in the order that they -are evaluated. Operators on the same line, or in the same group, have -equal precedence. - -The Operator column lists the operators. The Reference column lists -the Windows PowerShell Help topic in which the operator is described. -To display the topic, type `get-help `. - -|OPERATOR|REFERENCE| -|--------|---------| -|`$() @()`|[about_Operators](#index-operator)| -|`.` (dereference) `::` (static)|[about_Operators](about_Operators.md)| -|`[0]` (index operator)|[about_Operators](about_Operators.md)| +PowerShell operators let you construct simple, but powerful +expressions. This topic lists the operators in precedence order. Precedence +order is the order in which PowerShell evaluates the operators when +multiple operators appear in the same expression. + +When operators have equal precedence, PowerShell evaluates them from +left to right. The exceptions are the assignment operators, the cast +operators, and the negation operators (!, -not, -bnot), which are evaluated +from right to left. + +You can use enclosures, such as parentheses, to override the standard +precedence order and force PowerShell to evaluate the enclosed part of +an expression before an unenclosed part. + +In the following list, operators are listed in the order that they are +evaluated. Operators on the same line, or in the same group, have equal +precedence. + +The Operator column lists the operators. The Reference column lists the +PowerShell Help topic in which the operator is described. To display +the topic, type `get-help `. + +|OPERATOR |REFERENCE| +|------------------------|---------| +|`$() @()` |[about_Operators](#index-operator)| +|`.` (dereference) |[about_Operators](about_Operators.md)| +|`::` (static) |[about_Operators](about_Operators.md)| +|`[0]` (index operator) |[about_Operators](about_Operators.md)| |`[int]` (cast operators)|[about_Operators](about_Operators.md)| -|`-split` (unary)
`-join` (unary)|[about_Split](about_Split.md)
[about_Join](about_Join.md)| -|`,` (comma operator)|[about_Operators](about_Operators.md)| -|`++ --`|[about_Assignment_Operators](about_Assignment_Operators.md)| -|`-not`
`! -bNot`|[about_Logical_Operators](about_logical_operators.md)
[about_Comparison_Operators](about_Comparison_Operators.md)| -|`..` (range operator)|[about_Operators](about_Operators.md)| -|`-f` (format operator)|[about_Operators](about_Operators.md)| -|`* / %`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`+ -`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| - - -The following group of operators have equal precedence. Their -case-sensitive and explicitly case-insensitive variants have -the same precedence. - -|OPERATOR|REFERENCE| -|--------|---------| -|`-split` (unary)|[about_Split](about_Split.md)| -|`-join` (unary)|[about_Join](about_Join.md)| -|`-is -isnot -as`|[about_Type_Operators](about_Type_Operators.md)| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`,` (comma operator) |[about_Operators](about_Operators.md)| +|`++ --` |[about_Assignment_Operators](about_Assignment_Operators.md)| +|`-not` |[about_Logical_Operators](about_logical_operators.md)| +|`! -bNot` |[about_Comparison_Operators](about_Comparison_Operators.md)| +|`..` (range operator) |[about_Operators](about_Operators.md)| +|`-f` (format operator) |[about_Operators](about_Operators.md)| +|`* / % + -` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| + +The following group of operators have equal precedence. Their case-sensitive +and explicitly case-insensitive variants have the same precedence. + +|OPERATOR |REFERENCE| +|-------------------------|---------| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`-is -isnot -as` |[about_Type_Operators](about_Type_Operators.md)| |`-eq -ne -gt -gt -lt -le`|[about_Comparison_Operators](about_Comparison_Operators.md)| -|`-like -notlike`|[about_comparison_operators](about_comparison_operators.md)| -|`-match -notmatch`|[about_comparison_operators](about_comparison_operators.md)| -|`-in -notIn`|[about_comparison_operators](about_comparison_operators.md)| -|`-contains -notContains`|[about_comparison_operators](about_comparison_operators.md)| -|`-replace`|[about_comparison_operators](about_comparison_operators.md)| +|`-like -notlike` |[about_comparison_operators](about_comparison_operators.md)| +|`-match -notmatch` |[about_comparison_operators](about_comparison_operators.md)| +|`-in -notIn` |[about_comparison_operators](about_comparison_operators.md)| +|`-contains -notContains` |[about_comparison_operators](about_comparison_operators.md)| +|`-replace` |[about_comparison_operators](about_comparison_operators.md)| The list resumes here with the following operators in precedence order: -|OPERATOR|REFERENCE| -|--------|---------| -|`-band -bor -bxor`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor`|[about_comparison_operators](about_comparison_operators.md)| -|`.` (dot-source)
`&` (call)|[about_Scopes](about_Scopes.md)
[about_Operators](about_Operators.md)| +|OPERATOR |REFERENCE| +|--------------------------|---------| +|`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| +|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`.` (dot-source) |[about_Scopes](about_Scopes.md)| +|`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| -|`> >> 2> 2>> 2>&1`|[about_Redirection](about_Redirection.md)| -|`= += -= *= /= %=`|[about_Assignment_Operators](about_Assignment_Operators.md)| +|`> >> 2> 2>> 2>&1` |[about_Redirection](about_Redirection.md)| +|`= += -= *= /= %=` |[about_Assignment_Operators](about_Assignment_Operators.md)| # EXAMPLES -The following two commands show the arithmetic operators and -the effect of using parentheses to force Windows PowerShell to -evaluate the enclosed part of the expression first. +The following two commands show the arithmetic operators and the effect of +using parentheses to force PowerShell to evaluate the enclosed part of +the expression first. ```powershell C:\PS> 2 + 3 * 4 @@ -97,8 +98,8 @@ C:\PS> (2 + 3) * 4 20 ``` -The following example gets the read-only text files from the local -directory and saves them in the `$read_only` variable. +The following example gets the read-only text files from the local directory +and saves them in the `$read_only` variable. ```powershell $read_only = get-childitem *.txt | where-object {$_.isReadOnly} @@ -109,37 +110,37 @@ It is equivalent to the following example. $read_only = ( get-childitem *.txt | where-object {$_.isReadOnly} ) ``` -Because the pipeline operator (|) has a higher precedence than the -assignment operator (=), the files that the Get-ChildItem cmdlet -gets are sent to the Where-Object cmdlet for filtering before they -are assigned to the $read_only variable. +Because the pipeline operator (|) has a higher precedence than the assignment +operator (=), the files that the Get-ChildItem cmdlet gets are sent to the +Where-Object cmdlet for filtering before they are assigned to the $read_only +variable. -The following example demonstrates that the index operator takes -precedence over the cast operator. +The following example demonstrates that the index operator takes precedence +over the cast operator. -The first expression creates an array of three strings. Then, it -uses the index operator with a value of 0 to select the first object -in the array, which is the first string. Finally, it casts the -selected object as a string. In this case, the cast has no effect. +The first expression creates an array of three strings. Then, it uses the +index operator with a value of 0 to select the first object in the array, +which is the first string. Finally, it casts the selected object as a string. +In this case, the cast has no effect. ```powershell C:\PS> [string]@('Windows','PowerShell','2.0')[0] Windows ``` -The second expression uses parentheses to force the cast operation -to occur before the index selection. As a result, the entire array -is cast as a (single) string. Then, the index operator selects -the first item in the string array, which is the first character. +The second expression uses parentheses to force the cast operation to occur +before the index selection. As a result, the entire array is cast as a +(single) string. Then, the index operator selects the first item in the string +array, which is the first character. ```powershell C:\PS> ([string]@('Windows','PowerShell','2.0'))[0] W ``` -In the following example, because the -gt (greater-than) operator -has a higher precedence than the -and (logical AND) operator, the -result of the expression is FALSE. +In the following example, because the -gt (greater-than) operator has a higher +precedence than the -and (logical AND) operator, the result of the expression +is FALSE. ```powershell C:\PS> 2 -gt 4 -and 1 @@ -160,11 +161,11 @@ C:\PS> 2 -gt (4 -and 1) True ``` -However, this example demonstrates an important principle of managing -operator precedence. When an expression is difficult for people to -interpret, use parentheses to force the evaluation order, even when it -forces the default operator precedence. The parentheses make your -intentions clear to people who are reading and maintaining your scripts. +However, this example demonstrates an important principle of managing operator +precedence. When an expression is difficult for people to interpret, use +parentheses to force the evaluation order, even when it forces the default +operator precedence. The parentheses make your intentions clear to people who +are reading and maintaining your scripts. ## SEE ALSO @@ -185,4 +186,3 @@ intentions clear to people who are reading and maintaining your scripts. [about_Split](about_Split.md) [about_Type_Operators](about_Type_Operators.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 46c3c136e573..e9c4ebaefa98 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,449 +7,409 @@ title: about_Parameters_Default_Values --- # About Parameters Default Values -## about_Parameters_Default_Values - ## SHORT DESCRIPTION -Describes how to set custom default values for the parameters of cmdlets and advanced functions. +Describes how to set custom default values for the parameters of cmdlets and +advanced functions. ## LONG DESCRIPTION -The $PSDefaultParameterValues preference variable lets you specify custom default values for any cmdlet or advanced function. Cmdlets and functions use the custom default value unless you specify another value in the command. -The authors of cmdlets and advanced functions set standard default values for their parameters. Typically, the standard default values are useful, but they might not be appropriate for all environments. +The \$PSDefaultParameterValues preference variable lets you specify custom +default values for any cmdlet or advanced function. Cmdlets and functions use +the custom default value unless you specify another value in the command. + +The authors of cmdlets and advanced functions set standard default values for +their parameters. Typically, the standard default values are useful, but they +might not be appropriate for all environments. -This feature is especially useful when you must specify the same alternate parameter value nearly every time you use the command or when a particular parameter value is difficult to remember, such as an e-mail server name or project GUID. +This feature is especially useful when you must specify the same alternate +parameter value nearly every time you use the command or when a particular +parameter value is difficult to remember, such as an e-mail server name or +project GUID. -If the desired default value varies predictably, you can specify a script block that provides different default values for a parameter under different conditions. +If the desired default value varies predictably, you can specify a script +block that provides different default values for a parameter under different +conditions. -$PSDefaultParameterValues was introduced in Windows PowerShell® 3.0. +\$PSDefaultParameterValues was introduced in PowerShell 3.0. +## SYNTAX -### SYNTAX The syntax of the $PSDefaultParameterValues preference variable is as follows: +```powershell +$PSDefaultParameterValues=@{":"=""} + +$PSDefaultParameterValues=@{":"={}} -``` -$PSDefaultParameterValues=@{":"=""} - -$PSDefaultParameterValues=@{":"={}} - $PSDefaultParameterValues["Disabled"]=$true | $false ``` - Wildcard characters are permitted in the CmdletName and ParameterName values. -The value of $PSDefaultParameterValues is a System.Management.Automation.DefaultParameterDictionary, a type of hash table that validates the format of keys. Enter a hash table where the key consists of the cmdlet name and parameter name separated by a colon (:) and the value is the custom default value. - -To set, change, add, or remove entries from $PSDefaultParameterValues, use the methods that you would use to edit a standard hash table. +The value of \$PSDefaultParameterValues is a +System.Management.Automation.DefaultParameterDictionary, a type of hash table +that validates the format of keys. Enter a hash table where the key consists +of the cmdlet name and parameter name separated by a colon (:) and the value +is the custom default value. -The must be the name of a cmdlet or the name of an advanced function that uses the CmdletBinding attribute. You cannot use $PSDefaultParameterValues to specify default values for scripts or simple functions. +To set, change, add, or remove entries from \$PSDefaultParameterValues, use the +methods that you would use to edit a standard hash table. -The default value can be an object or a script block. If the value is a script block, Windows PowerShell evaluates the script block and uses the result as the parameter value. When the specified parameter takes a script block value, enclose the script block value in a second set of braces, such as: +The \ must be the name of a cmdlet or the name of an advanced +function that uses the CmdletBinding attribute. You cannot use +$PSDefaultParameterValues to specify default values for scripts or simple +functions. +The default value can be an object or a script block. If the value is a script +block, PowerShell evaluates the script block and uses the result as the +parameter value. When the specified parameter takes a script block value, +enclose the script block value in a second set of braces, such as: -``` +```powershell $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } ``` +For information about hash tables, see +[about_Hash_Tables](about_Hash_Tables.md). For information about script +blocks, see [about_Script_Blocks](about_Script_Blocks.md). For information +about preference variables, see +[about_Preference_Variables](about_Preference_Variables.md). -For information about hash tables, see about_Hash_Tables. For information about script blocks, see about_Script_Blocks. For information about preference variables, see about_Preference_Variables. - +## EXAMPLES -### EXAMPLES -The following command sets a custom default value for the SmtpServer parameter of the Send-MailMessage cmdlet. +The following command sets a custom default value for the SmtpServer parameter +of the Send-MailMessage cmdlet. - -``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"} +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" +} ``` +To set default values for multiple parameters, use a semi-colon (;) to +separate each Name\=Value pair. The following command adds a custom default +value for the LogName parameter of the `Get-WinEvent` cmdlet. -To set default values for multiple parameters, use a semi-colon (;) to separate each Name\=Value pair. The following command adds a custom default value for the LogName parameter of the Get-WinEvent cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5"; + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" +} ``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"} -``` - -You can use wildcard characters in the name of the cmdlet and parameter. The following command sets the Verbose common parameter to $true in all commands. Use $true and $false to set values for switch parameters, such as Verbose. +You can use wildcard characters in the name of the cmdlet and parameter. The +following command sets the Verbose common parameter to \$true in all commands. +Use \$true and \$false to set values for switch parameters, such as +**Verbose**. - -``` +```powershell $PSDefaultParameterValues = @{"*:Verbose"=$true} ``` +If a parameter takes multiple values (an array), you can set multiple values +as the default value. The following command sets the default value of the +**ComputerName** parameter of the Invoke-Command cmdlet to "Server01" and +"Server02". -If a parameter takes multiple values (an array), you can set multiple values as the default value. The following command sets the default value of the ComputerName parameter of the Invoke-Command cmdlet to "Server01" and "Server02". - - -``` -$PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"} -``` - - -You can use a script block to specify different default values for a parameter under different conditions. Windows PowerShell evaluates the script block and uses the result as the default parameter value. - -The following command sets the default value of the Autosize parameter of the Format-Table cmdlet to $true when the host program is the Windows PowerShell console. - - -``` -$PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}}} -``` - - -If a parameter takes a script block value, enclose the script block in an extra set of braces. When Windows PowerShell evaluates the outer script block, the result is the inner script block, which is set as the default parameter value. - -The following command sets the default value of the ScriptBlock parameter of Invoke-Command. Because the script block is enclosed in a second set of braces, the enclosed script block is passed to the Invoke-Command cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Invoke-Command:ComputerName"="Server01","Server02" +} ``` -$PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}} -``` - - - -### HOW TO SET $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. - -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues +You can use a script block to specify different default values for a parameter +under different conditions. PowerShell evaluates the script block and uses the +result as the default parameter value. -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. +The following command sets the default value of the Autosize parameter of the +Format-Table cmdlet to \$true when the host program is the PowerShell console. - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +$PSDefaultParameterValues=@{ + "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}} +} ``` +If a parameter takes a script block value, enclose the script block in an +extra set of braces. When PowerShell evaluates the outer script block, the +result is the inner script block, which is set as the default parameter value. +The following command sets the default value of the ScriptBlock parameter of +`Invoke-Command`. Because the script block is enclosed in a second set of +braces, the enclosed script block is passed to the `Invoke-Command` cmdlet. -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational -Get*:Verbose True +```powershell +$PSDefaultParameterValues=@{ + "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} +} ``` +### HOW TO SET \$PSDefaultParameterValues -To get the value of a key, use the following command syntax: +\$PSDefaultParameterValues is a preference variable, so it exists only in the +session in which it is set. It has no default value. +To set \$PSDefaultParameterValues, type the variable name and one or more +key-value pairs at the command line. -``` -$PSDefaultParameterValues[""] -``` +If you type another \$PSDefaultParameterValues command, its value replaces the +original value. The original is not retained. +To save \$PSDefaultParameterValues for future sessions, add a +\$PSDefaultParameterValues command to your PowerShell profile. For more +information, see [about_Profiles](about_Profiles.md). -For example: +### HOW TO GET \$PSDefaultParameterValues +To get the value of \$PSDefaultParameterValues, at the command prompt, type: +```powershell +$PSDefaultParameterValues ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] -Server01AB234x5 -``` - - - -### HOW TO ADD VALUES TO $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. +For example, the first command sets the value of \$PSDefaultParameterValues. +The second command gets the value of \$PSDefaultParameterValues. -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues - -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. - - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +PS C:\> $PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + "Get-*:Verbose"=$true +} ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To get the value of a \ key, use the following +command syntax: -To get the value of a key, use the following command syntax: - - -``` +```powershell $PSDefaultParameterValues[""] ``` - For example: - -``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] Server01AB234x5 ``` +### HOW TO ADD VALUES TO PSDefaultParameterValues +To add or remove values from \$PSDefaultParameterValues, use the methods that +you would use for a standard hash table. -### HOW TO ADD VALUES TO $PSDefaultParameterValues -To add or remove values from $PSDefaultParameterValues, use the methods that you would use for a standard hash table. - -For example, to add a value to $PSDefaultParameterValues without affecting the existing values, use the Add method of hash tables. +For example, to add a value to \$PSDefaultParameterValues without affecting the +existing values, use the Add method of hash tables. The syntax of the Add method is as follows: - ``` .Add(Key, Value) ``` +where the Key is ":" and the value is the parameter +value. -where the Key is ":" and the value is the parameter value. - -Use the following command format to call the Add method on $PSDefaultParameterValues. Be sure to use a comma (,) to separate the key from the value, instead of the equal sign (\=). - +Use the following command format to call the Add method on +\$PSDefaultParameterValues. Be sure to use a comma (,) to separate the key +from the value, instead of the equal sign (\=). +```powershell +$PSDefaultParameterValues.Add( + ":", "" +) ``` -$PSDefaultParameterValues.Add(":", "") -``` - -For example, the following command adds "PowerShell" as the default value of the Name parameter of the Get-Process cmdlet. +For example, the following command adds "PowerShell" as the default value of +the Name parameter of the Get-Process cmdlet. - -``` +```powershell $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO REMOVE VALUES FROM \$PSDefaultParameterValues - -### HOW TO REMOVE VALUES FROM $PSDefaultParameterValues -To remove a value from $PSDefaultParameterValues, use the Remove method of hash tables. +To remove a value from \$PSDefaultParameterValues, use the Remove method of +hash tables. The syntax of the Remove method is as follows: - -``` +```powershell .Remove(Key) ``` +Use the following command format to call the Remove method on +\$PSDefaultParameterValues. -Use the following command format to call the Remove method on $PSDefaultParameterValues. - - -``` +```powershell $PSDefaultParameterValues.Remove(":") ``` +For example, the following command removes the Name parameter of the +`Get-Process` cmdlet and its values. -For example, the following command removes the Name parameter of the Get-Process cmdlet and its values. - - -``` +```powershell $PSDefaultParameterValues.Remove("Get-Process:Name") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO CHANGE VALUES IN \$PSDefaultParameterValues +To change a value in $PSDefaultParameterValues, use the following command +format. -### HOW TO CHANGE VALUES IN $PSDefaultParameterValues -To change a value in $PSDefaultParameterValues, use the following command format. - - -``` +```powershell $PSDefaultParameterValues["CmdletName:ParameterName"]="" ``` - The following example shows the effect of this command. +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - +```powershell +$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" -``` - +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO DISABLE AND RE-ENABLE \$PSDefaultParameterValues +You can temporarily disable and then re-enable \$PSDefaultParameterValues. This +is very useful if you're running scripts that might assume different default +parameter values. -### HOW TO DISABLE AND RE-ENABLE $PSDefaultParameterValues -You can temporarily disable and then re-enable $PSDefaultParameterValues. This is very useful if you're running scripts that might assume different default parameter values. - -To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of $True. +To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of +\$True. For example, - -``` +```powershell $PSDefaultParameterValues.Add("Disabled", $true) ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$true ``` +The other values in \$PSDefaultParameterValues are preserved, but not +effective. -The other values in $PSDefaultParameterValues are preserved, but not effective. - +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Disabled True -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Disabled True +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To re-enable \$PSDefaultParameterValues, remove the Disabled key or change the +value of the Disabled key to \$False. -To re-enable $PSDefaultParameterValues, remove the Disabled key or change the value of the Disabled key to $False. - - -``` +```powershell $PSDefaultParameterValues.Remove("Disabled") ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$false ``` - -The previous value of $PSDefaultParameterValues is effective again. - +The previous value of \$PSDefaultParameterValues is effective again. ## KEYWORDS + about_PSDefaultParameterValues about_Parameters_DefaultValues about_DefaultValues - ## SEE ALSO [about_Hash_Tables](about_Hash_Tables.md) @@ -459,4 +419,3 @@ about_DefaultValues [about_Profiles](about_Profiles.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 886b4ed1dfc9..906dc159fb8a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-05 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -248,7 +248,7 @@ debug message is not displayed and processing continues. The final command uses the Debug parameter to override the preference for a single command. ```powershell -PS> $debugpreference # Get the current value of \$DebugPreference +PS> $debugpreference # Get the current value of $DebugPreference SilentlyContinue PS> write-debug "Hello, World" @@ -301,7 +301,7 @@ uses the Debug parameter with a value of \$false to suppress the message for a single command. ```powershell -PS> \$debugpreference = "Inquire" +PS> $debugpreference = "Inquire" PS> write-debug "Hello, World" DEBUG: Hello, World @@ -375,7 +375,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value of the preference. -PS> \$ErrorActionPreference = "SilentlyContinue" +PS> $ErrorActionPreference = "SilentlyContinue" PS> # Generate an error message. PS> write-error "Hello, World" @@ -393,14 +393,14 @@ a non-existent file, nofile.txt. The example also uses the ErrorAction common parameter to override the preference. ```powershell -PS> \$erroractionpreference +PS> $erroractionpreference SilentlyContinue # Display the value of the preference. PS> get-childitem -path nofile.txt PS> # Error message is suppressed. PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> get-childitem -path nofile.txt Get-ChildItem : Cannot find path 'C:\nofile.txt' because it does not exist. @@ -412,7 +412,7 @@ PS> get-childitem -path nofile.txt -erroraction SilentlyContinue PS> # Error message is suppressed. PS> # Change the value to Inquire. -PS> \$ErrorActionPreference = "Inquire" +PS> $ErrorActionPreference = "Inquire" PS> get-childitem -path nofile.txt Confirm @@ -425,7 +425,7 @@ At line:1 char:4 + get-childitem <<<< nofile.txt PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> Get-Childitem nofile.txt -erroraction "Inquire" PS> # Use the ErrorAction parameter to override the preference value. @@ -462,7 +462,7 @@ NormalView. In this case, the Get-ChildItem command is used to find a non-existent file. ```powershell -PS> \$ErrorView # Verify the value. +PS> $ErrorView # Verify the value. NormalView PS> get-childitem nofile.txt # Find a non-existent file. @@ -475,7 +475,7 @@ This example shows how the same error appears when the value of \$ErrorView is CategoryView. ```powershell -PS> \$ErrorView = "CategoryView" # Change the value to +PS> $ErrorView = "CategoryView" # Change the value to CategoryView PS> get-childitem nofile.txt @@ -493,7 +493,7 @@ error in the error array (element 0) and formats all of the properties of the error object in a list. ```powershell -PS> \$error[0] | format-list -property * -force +PS> $error[0] | format-list -property * -force Exception : System.Management.Automation.ItemNotFoundException: Cannot find path 'C:\nofile.txt' because it does not exist. @@ -546,10 +546,10 @@ In the resulting display, the list in the Group column is now limited by the line length. In the final command in the example, use the Wrap parameter of Format-Table to display all of the processes in each Status group. -PS> \$formatenumerationlimit # Find the current value +```powershell +PS> $formatenumerationlimit # Find the current value 4 -```powershell PS> # List all services grouped by status PS> get-service | group-object -property status @@ -560,7 +560,7 @@ Count Name Group PS> # The list is truncated after 4 items. PS> # Increase the limit to 1000. -PS> \$formatenumerationlimit = 1000 +PS> $formatenumerationlimit = 1000 PS> get-service | group-object -property status Count Name Group @@ -650,20 +650,20 @@ The Log*Event preference variables are as follows: To enable a Log*Event, type the variable with a value of \$true, for example: ```powershell -\$LogCommandLifeCycleEvent +$LogCommandLifeCycleEvent ``` - or - ```powershell -\$LogCommandLifeCycleEvent = \$true +$LogCommandLifeCycleEvent = $true ``` To disable an event type, type the variable with a value of \$false, for example: ```powershell -\$LogCommandLifeCycleEvent = \$false +$LogCommandLifeCycleEvent = $false ``` The events that you enable are effective only for the current PowerShell @@ -719,26 +719,26 @@ To count the errors on your system, use the Count property of the \$Error array. Type: ```powershell -\$Error.count +$Error.count ``` To display a specific error, use array notation to display the error. For example, to see the most recent error, type: ```powershell -\$Error[0] +$Error[0] ``` To display the oldest retained error, type: ```powershell -\$Error[(\$Error.Count -1] +$Error[($Error.Count -1] ``` To display the properties of the ErrorRecord object, type: ```powershell -\$Error[0] | format-list -property * -force +$Error[0] | format-list -property * -force ``` In this command, the Force parameter overrides the special formatting of @@ -748,11 +748,11 @@ To delete all errors from the error history, use the Clear method of the error array. ```powershell -PS> \$Error.count +PS> $Error.count 17 -PS> \$Error.clear() +PS> $Error.clear() PS> -PS> \$Error.count +PS> $Error.count 0 ``` @@ -844,9 +844,9 @@ is converted to a string. In this case, an array of integers is stored in a variable and then the variable is cast as a string. ```powershell -PS> \$array = 1,2,3 # Store an array of integers. +PS> $array = 1,2,3 # Store an array of integers. -PS> [string]\$array # Cast the array to a string. +PS> [string]$array # Cast the array to a string. 1 2 3 # Spaces separate the elements ``` @@ -854,9 +854,9 @@ To change the separator, add the \$OFS variable by assigning a value to it. To work correctly, the variable must be named \$OFS. ```powershell -PS> \$OFS = "+" # Create \$OFS and assign a "+" +PS> $OFS = "+" # Create $OFS and assign a "+" -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1+2+3 # Plus signs separate the elements ``` @@ -865,10 +865,10 @@ To restore the default behavior, you can assign a space (" ") to the value of verifies that the separator is a space. ```powershell -PS> Remove-Variable OFS # Delete \$OFS +PS> Remove-Variable OFS # Delete $OFS PS> -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1 2 3 # Spaces separate the elements ``` @@ -897,7 +897,7 @@ The first command finds the value of \$OutputEncoding. Because the value is an encoding object, display only its EncodingName property. ```powershell -PS> \$OutputEncoding.EncodingName # Find the current value US-ASCII +PS> $OutputEncoding.EncodingName # Find the current value US-ASCII ``` In this example, a FINDSTR command is used to search for two Chinese @@ -918,9 +918,9 @@ locale selected for Windows. Because OutputEncoding is a static property of the console, use double-colons (::) in the command. ```powershell -PS> \$OutputEncoding = [console]::outputencoding +PS> $OutputEncoding = [console]::outputencoding PS> # Set the value equal to the OutputEncoding property of the console. -PS> \$OutputEncoding.EncodingName +PS> $OutputEncoding.EncodingName OEM United States ``` As a result of this change, the FINDSTR command finds the characters. @@ -1100,7 +1100,7 @@ values you prefer. Save the output in a variable called \$PSSessionOption. For example, ```powershell -\$PSSessionOption = New-PSSessionOption -NoCompression +$PSSessionOption = New-PSSessionOption -NoCompression ``` To use the \$PSSessionOption preference variable in every PowerShell session, @@ -1202,7 +1202,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$VerbosePreference = "Inquire" +PS> $VerbosePreference = "Inquire" PS> Write-Verbose "Verbose message test." VERBOSE: Verbose message test. Confirm @@ -1249,7 +1249,7 @@ value. This example shows the effect of the Continue value, which is the default. ```powershell -PS> \$WarningPreference # Find the current value. +PS> $WarningPreference # Find the current value. Continue PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1263,7 +1263,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value to SilentlyContinue. -PS> \$WarningPreference = "SilentlyContinue" +PS> $WarningPreference = "SilentlyContinue" PS> Write-Warning "This action can delete data." PS> # Write a warning message. @@ -1280,7 +1280,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$WarningPreference = "Inquire" +PS> $WarningPreference = "Inquire" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1299,7 +1299,7 @@ This example shows the effect of the Stop value. ```powershell PS> # Change the value to Stop. -PS> \$WarningPreference = "Stop" +PS> $WarningPreference = "Stop" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1360,7 +1360,7 @@ This example shows the effect of the 0 (not enabled) value, which is the default. ```powershell -PS> \$whatifpreference +PS> $whatifpreference 0 # Check the current value. PS> # Verify that the file exists. @@ -1400,8 +1400,8 @@ Remove-Item to delete a cmdlet, Remove-Item displays the path to the file that it would delete, but it does not delete the file. ```powershell -PS> \$whatifpreference = 1 -PS> \$whatifpreference +PS> $whatifpreference = 1 +PS> $whatifpreference 1 # Change the value. PS> # Try to delete a file. @@ -1417,8 +1417,8 @@ This example shows how to delete a file when the value of \$WhatIfPreference is 1. It uses the WhatIf parameter with a value of \$false. ```powershell -PS> # Use the WhatIf parameter with \$false. -PS> remove-item test.txt -whatif:\$false +PS> # Use the WhatIf parameter with $false. +PS> remove-item test.txt -whatif:$false ``` This example demonstrates that some cmdlets support WhatIf behavior and others @@ -1430,7 +1430,7 @@ a value of \$false. ```powershell PS> # Change the value to 1. -PS> \$whatifpreference = 1 +PS> $whatifpreference = 1 PS> get-process winword A Get-Process command completes. @@ -1443,8 +1443,8 @@ PS> # A Stop-Process command uses WhatIf. PS> stop-process -name winword What if: Performing operation "Stop-Process" on Target "WINWORD (2312)". -PS> stop-process -name winword -whatif:\$false -PS> # WhatIf:\$false overrides the preference. +PS> stop-process -name winword -whatif:$false +PS> # WhatIf:$false overrides the preference. PS> # Verify that the process is stopped. PS> get-process winword diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Prompts.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Prompts.md index 52e5fba3fc21..6f1820bea646 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Prompts.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Prompts.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,308 +7,284 @@ title: about_Prompts --- # About Prompts -## about_Prompts - ## SHORT DESCRIPTION -Describes the Prompt function and demonstrates how to create a custom Prompt function. +Describes the Prompt function and demonstrates how to create a custom Prompt +function. ## LONG DESCRIPTION -The Windows PowerShell® command prompt indicates that Windows PowerShell is ready to run a command: +The PowerShell command prompt indicates that PowerShell is ready to run a +command: ``` PS C:\> ``` +The PowerShell prompt is determined by the built-in Prompt function. You can +customize the prompt by creating your own Prompt function and saving it in +your PowerShell profile. -The Windows PowerShell prompt is determined by the built-in Prompt function. You can customize the prompt by creating your own Prompt function and saving it in your Windows PowerShell profile. - +## ABOUT THE PROMPT FUNCTION -### ABOUT THE PROMPT FUNCTION -The Prompt function determines the appearance of the Windows PowerShell prompt. Windows PowerShell comes with a built-in Prompt function, but you can override it by defining your own Prompt function. +The Prompt function determines the appearance of the PowerShell prompt. +PowerShell comes with a built-in Prompt function, but you can override it by +defining your own Prompt function. The Prompt function has the following syntax: - -``` +```powershell function Prompt { } ``` +The Prompt function must return an object. As a best practice, return a string +or an object that is formatted as a string. The maximum recommended length is +80 characters. -The Prompt function must return an object. As a best practice, return a string or an object that is formatted as a string. The maximum recommended length is 80 characters. - -For example, the following prompt function returns a "Hello, World" string followed by a caret (>). +For example, the following prompt function returns a "Hello, World" string +followed by a caret (>). - -``` -PS C:\> function prompt {"Hello, World > "} +```powershell +PS C:\> function prompt {"Hello, World > "} Hello, World > ``` - - ### GETTING THE PROMPT FUNCTION -To get the Prompt function, use the Get-Command cmdlet or use the Get-Item cmdlet in the Function drive. -Functions are commands. So, you can use the Get-Command cmdlet to get functions, including the Prompt function. +To get the Prompt function, use the `Get-Command` cmdlet or use the `Get-Item` +cmdlet in the Function drive. For example: +```powershell +PS C:\> Get-Command Prompt -``` -PS C:\> Get-Command Prompt - -CommandType Name ModuleName ------------ ---- ---------- +CommandType Name ModuleName +----------- ---- ---------- Function prompt ``` - -To get the script that sets the value of the prompt, use the dot method to get the ScriptBlock property of the Prompt function. +To get the script that sets the value of the prompt, use the dot method to get +the ScriptBlock property of the Prompt function. For example: +```powershell +PS C:\> (Get-Command Prompt).ScriptBlock -``` -PS C:\> (Get-Command Prompt).ScriptBlock - -"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -# .Link -# http://go.microsoft.com/fwlink/?LinkID=225750 +"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPr +omptLevel + 1)) " +# .Link +# http://go.microsoft.com/fwlink/?LinkID=225750 # .ExternalHelp System.Management.Automation.dll-help.xml ``` +Like all functions, the Prompt function is stored in the Function: drive. To +display the script that creates the current Prompt function, type: -Like all functions, the Prompt function is stored in the Function: drive. To display the script that creates the current Prompt function, type: - - -``` +```powershell (Get-Item function:prompt).ScriptBlock ``` - ### THE DEFAULT PROMPT -The default prompt appears only when the Prompt function generates an error or does not return an object. -The default Windows PowerShell prompt is: +The default prompt appears only when the Prompt function generates an error or +does not return an object. +The default PowerShell prompt is: ``` PS> ``` +For example, the following command sets the Prompt function to $null, which is +invalid. As a result, the default prompt appears. -For example, the following command sets the Prompt function to $null, which is invalid. As a result, the default prompt appears. - - -``` -PS C:\> function prompt {$null} +```powershell +PS C:\> function prompt {$null} PS> ``` - -Because Windows PowerShell comes with a built-in prompt, you usually do not see the default prompt. - +Because PowerShell comes with a built-in prompt, you usually do not see the +default prompt. ### BUILT-IN PROMPT -Windows PowerShell includes a built-in prompt function. - -In Windows PowerShell 3.0, the built-in prompt function is: - - -``` -function prompt -{ - "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -} -``` - -This simplified prompt starts with "PS" followed by the current location, and one ">" for each nested prompt level. +PowerShell includes a built-in prompt function. -In Windows PowerShell 2.0, the built-in prompt function is: - - -``` -function prompt -{ - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - else { '' }) + 'PS ' + $(Get-Location) ` - + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +```powershell +function prompt { + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + else { '' }) + 'PS ' + $(Get-Location) ` + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +The function uses the Test-Path cmdlet to determine whether the +\$PSDebugContext automatic variable is populated. If \$PSDebugContext is +populated, you are in debugging mode, and "[DBG]" is added to the prompt, as +follows: -The function uses the Test-Path cmdlet to determine whether the $PSDebugContext automatic variable is populated. If $PSDebugContext is populated, you are in debugging mode, and "[DBG]" is added to the prompt, as follows: - - -``` +```Output [DBG] PS C:\ps-test> ``` +If \$PSDebugContext is not populated, the function adds "PS" to the prompt. +And, the function uses the `Get-Location` cmdlet to get the current file +system directory location. Then, it adds a right angle bracket (>). -If $PSDebugContext is not populated, the function adds "PS" to the prompt. And, the function uses the Get-Location cmdlet to get the current file system directory location. Then, it adds a right angle bracket (>). - +For example: -``` -For example: - PS C:\ps-test> +```Output +PS C:\ps-test> ``` +If you are in a nested prompt, the function adds two angle brackets (>>) to +the prompt. (You are in a nested prompt if the value of the +\$NestedPromptLevel automatic variable is greater than 1.) -If you are in a nested prompt, the function adds two angle brackets (>>) to the prompt. (You are in a nested prompt if the value of the $NestedPromptLevel automatic variable is greater than 1.) +For example, when you are debugging in a nested prompt, the prompt resembles +the following prompt: -For example, when you are debugging in a nested prompt, the prompt resembles the following prompt: - - -``` +```Output [DBG] PS C:\ps-test>>> ``` - - ### CHANGES TO THE PROMPT -The Enter-PSSession cmdlet prepends the name of the remote computer to the current Prompt function. When you use the Enter-PSSession cmdlet to start a session with a remote computer, the command prompt changes to include the name of the remote computer. For example: +The Enter-PSSession cmdlet prepends the name of the remote computer to the +current Prompt function. When you use the Enter-PSSession cmdlet to start a +session with a remote computer, the command prompt changes to include the name +of the remote computer. For example: -``` -PS Hello, World> Enter-PSSession Server01 +```Output +PS Hello, World> Enter-PSSession Server01 [Server01]: PS Hello, World> ``` +Other PowerShell host applications and alternate shells might have their own +custom command prompts. -Other Windows PowerShell host applications and alternate shells might have their own custom command prompts. - -For more information about the $PSDebugContext and $NestedPromptLevel automatic variables, see about_Automatic_Variables. - +For more information about the \$PSDebugContext and $NestedPromptLevel +automatic variables, see [about_Automatic_Variables](about_Automatic_Variables.md). ### HOW TO CUSTOMIZE THE PROMPT -To customize the prompt, write a new Prompt function. The function is not protected, so you can overwrite it. -To write a prompt function, type the following: +To customize the prompt, write a new Prompt function. The function is not +protected, so you can overwrite it. +To write a prompt function, type the following: -``` +```powershell function prompt { } ``` - -Then, between the braces, enter the commands or the string that creates your prompt. +Then, between the braces, enter the commands or the string that creates your +prompt. For example, the following prompt includes your computer name: - -``` +```powershell function prompt {"PS [$env:COMPUTERNAME]> "} ``` - On the Server01 computer, the prompt resembles the following prompt: - -``` +```Output PS [Server01] > ``` - The following prompt function includes the current date and time: - -``` +```powershell function prompt {"$(get-date)> "} ``` - The prompt resembles the following prompt: - -``` +```Output 03/15/2012 17:49:47> ``` - You can also change the default Prompt function: -For example, the following modified Prompt function adds "[ADMIN]:" to the built-in Windows PowerShell prompt when Windows PowerShell is opened by using the "Run as administrator" option: - - -``` -function prompt -{ - $identity = [Security.Principal.WindowsIdentity]::GetCurrent() - $principal = [Security.Principal.WindowsPrincipal] $identity - - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - - elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) - { "[ADMIN]: " } - - else { '' }) + 'PS ' + $(Get-Location) + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +For example, the following modified Prompt function adds "[ADMIN]:" to the +built-in PowerShell prompt when PowerShell is opened by using the "Run as +administrator" option: + +```powershell +function prompt { + $identity = [Security.Principal.WindowsIdentity]::GetCurrent() + $principal = [Security.Principal.WindowsPrincipal] $identity + + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] + "Administrator")) { "[ADMIN]: " } + else { '' } + ) + 'PS ' + $(Get-Location) + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +When you start PowerShell by using the "Run as administrator" option, a prompt +that resembles the following prompt appears: -When you start Windows PowerShell by using the "Run as administrator" option, a prompt that resembles the following prompt appears: - - -``` +```Output [ADMIN]: PS C:\ps-test> ``` +The following Prompt function displays the history ID of the next command. To +view the command history, use the `Get-History` cmdlet. -The following Prompt function displays the history ID of the next command. To view the command history, use the Get-History cmdlet. - +```powershell +function prompt { + # The at sign creates an array in case only one history item exists. + $history = @(get-history) + if($history.Count -gt 0) + { + $lastItem = $history[$history.Count - 1] + $lastId = $lastItem.Id + } -``` -function prompt -{ - # The at sign creates an array in case only one history item exists. - $history = @(get-history) - if($history.Count -gt 0) - { - $lastItem = $history[$history.Count - 1] - $lastId = $lastItem.Id - } - - $nextCommand = $lastId + 1 - $currentDirectory = get-location - "PS: $nextCommand $currentDirectory >" + $nextCommand = $lastId + 1 + $currentDirectory = get-location + "PS: $nextCommand $currentDirectory >" } ``` +The following prompt uses the Write-Host and Get-Random cmdlets to create a +prompt that changes color randomly. Because `Write-Host` writes to the current +host application but does not return an object, this function includes a +Return statement. Without it, PowerShell uses the default prompt, "PS>". -The following prompt uses the Write-Host and Get-Random cmdlets to create a prompt that changes color randomly. Because Write-Host writes to the current host application but does not return an object, this function includes a Return statement. Without it, Windows PowerShell uses the default prompt, "PS>". - - -``` -function prompt -{ - $color = Get-Random -Min 1 -Max 16 - Write-Host ("PS " + $(Get-Location) +">") -NoNewLine -ForegroundColor $Color - return " " +```powershell +function prompt { + $color = Get-Random -Min 1 -Max 16 + Write-Host ("PS " + $(Get-Location) +">") -NoNewLine ` + -ForegroundColor $Color + return " " } ``` - - ### SAVING THE PROMPT FUNCTION -Like any function, the Prompt function exists only in the current session. To save the Prompt function for future sessions, add it to your Windows PowerShell profiles. For more information about profiles, see about_Profiles. +Like any function, the Prompt function exists only in the current session. To +save the Prompt function for future sessions, add it to your PowerShell +profiles. For more information about profiles, see about_Profiles. ## SEE ALSO -Get-Location +[Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) -Enter-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Get-History +[Get-History](../Get-History.md) -Get-Random +[Get-Random](../../Microsoft.PowerShell.Utility/Get-Random.md) -Write-Host +[Write-Host](../../Microsoft.PowerShell.Utility/Write-Host.md) [about_Profiles](about_Profiles.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md deleted file mode 100644 index af9999f5f30a..000000000000 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_packagemanagement ---- - -# About PackageManagement -## about_PackageManagement -# TOPIC - -about_PackageManagement - -# SHORT DESCRIPTION - -PackageManagement is an aggregator for software package managers. - -# LONG DESCRIPTION - -PackageManagement functionality was introduced in Windows PowerShell 5.0. - -PackageManagement is a unified interface for software package management systems; you -can run PackageManagement cmdlets to perform software discovery, installation, and -inventory (SDII) tasks. Regardless of the underlying installation technology, -you can run the common cmdlets in the PackageManagement module to search for, -install, or uninstall packages; add, remove, and query package repositories; and -run queries on a computer to determine which software packages are installed. - -PackageManagement supports a flexible plug-in model that enables support for other -software package management systems. - -The PackageManagement module is included with Windows PowerShell 5.0 and later releases -of Windows PowerShell, and works on three levels of package management -structure: package providers, package sources, and the packages themselves. - -Term Description ----------- ------------------------------ -Package manager Software package management system. In -PackageManagement terms, this is a package provider. -Package provider PackageManagement term for a package manager. Examples -can include Windows Installer, Chocolatey, -and others. -Package source A URL, local folder, or network shared folder that -you configure package providers to use as a -repository. -Package A piece of software that a package provider manages, -and that is stored in a specific package source. - -The PackageManagement module includes the following cmdlets. You can find the -Help for these cmdlets on TechNet starting on the following page: -http://technet.microsoft.com/library/dn890951(v=wps.640).aspx. - -Cmdlet Description ----------- ------------------------------ -Get-PackageProvider Returns a list of package providers that are -connected to PackageManagement. -Get-PackageSource Gets a list of package sources that are -registered for a package provider. -Register-PackageSource Adds a package source for a specified -package provider. -Set-PackageSource Sets properties on an existing package -source. -Unregister-PackageSource Removes a registered package source. -Get-Package Returns a list of installed software -packages. -Find-Package Finds software packages in available -package sources. -Install-Package Installs one or more software packages. -Save-Package Saves packages to the local computer -without installing them. -Uninstall-Package Uninstalls one or more software packages. - -PackageManagement Package Provider Bootstrapping and Dynamic Cmdlet Parameters - -By default, PackageManagement ships with a core bootstrap provider. You can install -additional package providers as you need them by bootstrapping the providers; -that is, responding to a prompt to install the provider automatically, from a -web service. You can specify a package provider with any PackageManagement cmdlet; -if the specified provider is not available, PackageManagement prompts you to bootstrap ---or automatically install--the provider. In the following examples, if the -Chocolatey provider is not already installed, PackageManagement bootstrapping installs -the provider. - -Find-Package -Provider Chocolatey - -If the Chocolatey provider is not already installed, when you run the -preceding command, you are prompted to install it. - -Install-Package -ForceBootstrap - -If the Chocolatey provider is not already installed, when you run the -preceding command, the provider is installed; but because the ForceBootstrap -parameter has been added to the command, you are not prompted to install it; -both the provider and the package are installed automatically. - -When you try to install a package, if you do not already have the supporting -provider installed, and you do not add the ForceBootstrap parameter to your -command, PackageManagement prompts you to install the provider. - -Specifying a package provider in your PackageManagement command can make -dynamic parameters available that are specific to that package provider. -When you run Get-Help for a specific PackageManagement cmdlet, a list of -parameter sets are returned, grouping dynamic parameters for available -package providers in separate parameter sets. - -More Information About the PackageManagement Project - -For more information about the PackageManagement open development project, -including how to create a PackageManagement package provider, see the -PackageManagement project on GitHub at https://oneget.org. - -# SEE ALSO - -Get-PackageProvider - -Get-PackageSource - -Register-PackageSource - -Set-PackageSource - -Unregister-PackageSource - -Get-Package - -Find-Package - -Install-Package - -Save-Package - -Uninstall-Package - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_pipelines.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_pipelines.md index ec7b65c085af..97cd9535c505 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_pipelines.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_pipelines.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,41 +7,39 @@ title: about_pipelines --- # About Pipelines -## about_Pipelines - - ### Short Description -Combining commands into pipelines in the Windows PowerShell +Combining commands into pipelines in the PowerShell ### Long Description -A pipeline is a series of commands connected by pipeline operators -(`|`)(ASCII 124). Each pipeline operator sends the results of the preceding -command to the next command. +A pipeline is a series of commands connected by pipeline operators (`|`) +(ASCII 124). Each pipeline operator sends the results of the preceding command +to the next command. -You can use pipelines to send the objects that are output by one command -to be used as input to another command for processing. And you can send the -output of that command to yet another command. The result is a very powerful -command chain or "pipeline" that is comprised of a series of simple commands. +You can use pipelines to send the objects that are output by one command to be +used as input to another command for processing. And you can send the output +of that command to yet another command. The result is a very powerful command +chain or "pipeline" that is comprised of a series of simple commands. For example, + ```powershell Command-1 | Command-2 | Command-3 ``` In this example, the objects that `Command-1` emits are sent to `Command-2`. -`Command-2` processes the objects and sends them to `Command-3`. `Command-3` processes -the objects and send them down the pipeline. Because there are no more commands in -the pipeline, the results are displayed at the console. +`Command-2` processes the objects and sends them to `Command-3`. `Command-3` +processes the objects and send them down the pipeline. Because there are no +more commands in the pipeline, the results are displayed at the console. -In a pipeline, the commands are processed from left to right in the order -that they appear. The processing is handled as a single operation and -output is displayed as it is generated. +In a pipeline, the commands are processed from left to right in the order that +they appear. The processing is handled as a single operation and output is +displayed as it is generated. -Here is a simple example. The following command gets the Notepad process -and then stops it. +Here is a simple example. The following command gets the Notepad process and +then stops it. For example, ```powershell @@ -49,77 +47,69 @@ Get-Process notepad | Stop-Process ``` The first command uses the `Get-Process` cmdlet to get an object representing -the Notepad process. It uses a pipeline operator (`|`) to send the process object -to the `Stop-Process` cmdlet, which stops the Notepad process. Notice that the -`Stop-Process` command does not have a Name or ID parameter to specify the process, -because the specified process is submitted through the pipeline. +the Notepad process. It uses a pipeline operator (`|`) to send the process +object to the `Stop-Process` cmdlet, which stops the Notepad process. Notice +that the `Stop-Process` command does not have a Name or ID parameter to +specify the process, because the specified process is submitted through the +pipeline. Here is a practical example. This command pipeline gets the text files in the -current directory, selects only the files that are more than 10,000 bytes long, -sorts them by length, and displays the name and length of each file in a table. +current directory, selects only the files that are more than 10,000 bytes +long, sorts them by length, and displays the name and length of each file in a +table. ```powershell Get-ChildItem -Path *.txt | Where-Object {$_.length -gt 10000} | Sort-Object -Property length | Format-Table -Property name, length ``` -This pipeline is comprised of four commands in the specified order. The command -is written horizontally, but we will show the process vertically in the following -graphic. +This pipeline is comprised of four commands in the specified order. The +command is written horizontally, but we will show the process vertically in +the following graphic. `Get-ChildItem` `-Path` *.txt - **|** - -| (FileInfo objects ) -| ( .txt ) - - **|** - - **V** +``` +| +| (FileInfo objects for *.txt) +| +V +``` `Where-Object` {$_.length `-gt` 10000} - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| +V +``` `Sort-Object` `-Property` Length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| +V +``` `Format-Table` `-Property` name, length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) -| (Formatted in a table ) - - **|** - - **V** - ``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| ( Formatted in a table ) +| +V +``` + +```output Name Length ---- ------ tmp1.txt 82920 @@ -129,13 +119,13 @@ tmp3.txt 114000 ### Using Pipelines +The PowerShell cmdlets were designed to be used in pipelines. For example, you +can usually pipe the results of a Get cmdlet to an action cmdlet (such as a +Set, Start, Stop, or Rename cmdlet) for the same noun. -The Windows PowerShell cmdlets were designed to be used in pipelines. For example, -you can usually pipe the results of a Get cmdlet to an action cmdlet (such as a Set, -Start, Stop, or Rename cmdlet) for the same noun. - -For example, you can pipe any service from the `Get-Service` cmdlet to the `Start-Service` -or `Stop-Service` cmdlets (although disabled services cannot be restarted in this way). +For example, you can pipe any service from the `Get-Service` cmdlet to the +`Start-Service` or `Stop-Service` cmdlets (although disabled services cannot +be restarted in this way). This command pipeline starts the WMI service on the computer: @@ -144,90 +134,98 @@ For example, Get-Service wmi | Start-Service ``` -The cmdlets that get and set objects of the Windows PowerShell providers, such as the +The cmdlets that get and set objects of the PowerShell providers, such as the Item and ItemProperty cmdlets, are also designed to be used in pipelines. -For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` command in the -Windows PowerShell registry provider to the `New-ItemProperty` cmdlet. This command adds -a new registry entry, NoOfEmployees, with a value of 8124, to the MyCompany registry key. +For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` +command in the PowerShell registry provider to the `New-ItemProperty` cmdlet. +This command adds a new registry entry, NoOfEmployees, with a value of 8124, +to the MyCompany registry key. For example, ```powershell -Get-Item -Path HKLM:\Software\MyCompany | New-ItemProperty -Name NoOfEmployees -Value 8124 +Get-Item -Path HKLM:\Software\MyCompany | + New-ItemProperty -Name NoOfEmployees -Value 8124 ``` -Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, `Sort-Object`, `Group-Object`, -and `Measure-Object` are used almost exclusively in pipelines. You can pipe any objects to -these cmdlets. +Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, +`Sort-Object`, `Group-Object`, and `Measure-Object` are used almost +exclusively in pipelines. You can pipe any objects to these cmdlets. -For example, you can pipe all of the processes on the computer to the `Sort-Object` command -and have them sorted by the number of handles in the process. +For example, you can pipe all of the processes on the computer to the +`Sort-Object` command and have them sorted by the number of handles in the +process. For example, + ```powershell Get-Process | Sort-Object -Property handles ``` -Also, you can pipe any objects to the formatting cmdlets, such as `Format-List` and -`Format-Table`, the Export cmdlets, such as `Export-Clixml` and `Export-CSV`, and the Out -cmdlets, such as `Out-Printer`. +Also, you can pipe any objects to the formatting cmdlets, such as +`Format-List` and `Format-Table`, the Export cmdlets, such as `Export-Clixml` +and `Export-CSV`, and the Out cmdlets, such as `Out-Printer`. -For example, you can pipe the Winlogon process to the `Format-List` cmdlet to display all -of the properties of the process in a list. +For example, you can pipe the Winlogon process to the `Format-List` cmdlet to +display all of the properties of the process in a list. For example, + ```powershell Get-Process winlogon | Format-List -Property * ``` -With a bit of practice, you'll find that combining simple commands into pipelines -saves time and typing, and makes your scripting more efficient. +With a bit of practice, you'll find that combining simple commands into +pipelines saves time and typing, and makes your scripting more efficient. ### How Pipelines Work +When you "pipe" objects, that is send the objects in the output of one command +to another command, PowerShell tries to associate the piped objects with one +of the parameters of the receiving cmdlet. -When you "pipe" objects, that is send the objects in the output of one command to another -command, Windows PowerShell tries to associate the piped objects with one of the parameters -of the receiving cmdlet. - -To do so, the Windows PowerShell "parameter binding" component, which associates input objects -with cmdlet parameters, tries to find a parameter that meets the following criteria: +To do so, the PowerShell "parameter binding" component, which associates input +objects with cmdlet parameters, tries to find a parameter that meets the +following criteria: - The parameter must accept input from a pipeline (not all do) -- The parameter must accept the type of object being sent or a type that the object -can be converted to. +- The parameter must accept the type of object being sent or a type that the + object can be converted to. - The parameter must not already be used in the command. -For example, the `Start-Service` cmdlet has many parameters, but only two of them, `-Name` and `-InputObject` -accept pipeline input. The `-Name` parameter takes strings and the `-InputObject` parameter takes -service objects. Therefore, you can pipe strings and service objects (and objects with properties -that can be converted to string and service objects) to `Start-Service`. +For example, the `Start-Service` cmdlet has many parameters, but only two of +them, `-Name` and `-InputObject` accept pipeline input. The `-Name` parameter +takes strings and the `-InputObject` parameter takes service objects. +Therefore, you can pipe strings and service objects (and objects with +properties that can be converted to string and service objects) to +`Start-Service`. -If the parameter binding component of Windows PowerShell cannot associate the piped objects -with a parameter of the receiving cmdlet, the command fails and Windows PowerShell prompts you -for the missing parameter values. +If the parameter binding component of PowerShell cannot associate the piped +objects with a parameter of the receiving cmdlet, the command fails and +PowerShell prompts you for the missing parameter values. -You cannot force the parameter binding component to associate the piped objects with a particular -parameter -- you cannot even suggest a parameter. Instead, the logic of the component manages -the piping as efficiently as possible. +You cannot force the parameter binding component to associate the piped +objects with a particular parameter. You cannot even suggest a parameter. +Instead, the logic of the component manages the piping as efficiently as +possible. ### One-At-A-Time Processing +Piping objects to a command is much like using a parameter of the command to +submit the objects. -Piping objects to a command is much like using a parameter of the command to submit the -objects. - -For example, piping objects representing the services on the computer to a `Format-Table` command, -such as: +For example, piping objects representing the services on the computer to a +`Format-Table` command, such as: ```powershell Get-Service | Format-Table -Property name, dependentservices ``` -is much like saving the service objects in a variable and using the InputObject parameter -of `Format-Table` to submit the service object. +is much like saving the service objects in a variable and using the +InputObject parameter of `Format-Table` to submit the service object. For example, + ```powershell $services = Get-Service Format-Table -InputObject $services -Property name, dependentservices @@ -236,51 +234,58 @@ Format-Table -InputObject $services -Property name, dependentservices or imbedding the command in the parameter value For example, + ```powershell -Format-Table -InputObject (Get-Service wmi) -Property name, dependentservices +Format-Table -InputObject (Get-Service wmi) -Property name,dependentservices ``` -However, there is an important difference. When you pipe multiple objects to a command, -Windows PowerShell sends the objects to the command one at a time. When you use a -command parameter, the objects are sent as a single array object. +However, there is an important difference. When you pipe multiple objects to a +command, PowerShell sends the objects to the command one at a time. When you +use a command parameter, the objects are sent as a single array object. + +This seemingly technical difference can have interesting, and sometimes +useful, consequences. -This seemingly technical difference can have interesting, and sometimes useful, consequences. +For example, if you pipe multiple process objects from the `Get-Process` +cmdlet to the `Get-Member` cmdlet, PowerShell sends each process object, one +at a time, to `Get-Member`. `Get-Member` displays the .NET class (type) of the +process objects, and their properties and methods. -For example, if you pipe multiple process objects from the `Get-Process` cmdlet to the -`Get-Member` cmdlet, Windows PowerShell sends each process object, one at a time, to `Get-Member`. -`Get-Member` displays the .NET class (type) of the process objects, and their properties and methods. -(`Get-Member` eliminates duplicates, so if the objects are all of the same type, it displays only -one object type.) +NOTE: `Get-Member` eliminates duplicates, so if the objects are all of the +same type, it displays only one object type. -In this case, `Get-Member` displays the properties and methods of each process object, that is, a -System.Diagnostics.Process object. +In this case, `Get-Member` displays the properties and methods of each process +object, that is, a System.Diagnostics.Process object. For example, + ```powershell Get-Process | Get-Member ``` -``` +```Output TypeName: System.Diagnostics.Process -Name MemberType Definition ----- ---------- ---------- -Handles AliasProperty Handles = Handlecount -Name AliasProperty Name = ProcessName -NPM AliasProperty NPM = NonpagedSystemMemorySize +Name MemberType Definition +---- ---------- ---------- +Handles AliasProperty Handles = Handlecount +Name AliasProperty Name = ProcessName +NPM AliasProperty NPM = NonpagedSystemMemorySize ... ``` -However, if you use the InputObject parameter of `Get-Member`, then `Get-Member` receives an -array of System.Diagnostics.Process objects as a single unit, and it displays the properties -of an array of objects. (Note the array symbol ([]) after the System.Object type name.) +However, if you use the InputObject parameter of `Get-Member`, then +`Get-Member` receives an array of System.Diagnostics.Process objects as a +single unit, and it displays the properties of an array of objects. (Note the +array symbol ([]) after the System.Object type name.) For example, + ```powershell Get-Member -InputObject (Get-Process) ``` -``` +```Output TypeName: System.Object[] Name MemberType Definition @@ -291,30 +296,32 @@ Clone Method System.Object Clone() ... ``` -This result might not be what you intended, but after you understand it, you can use it. For -example, an array of process objects has a Count property that you can use to count the number -of processes on the computer. +This result might not be what you intended, but after you understand it, you +can use it. For example, an array of process objects has a Count property that +you can use to count the number of processes on the computer. For example, + ```powershell (Get-Process).count ``` -This distinction can be important, so remember that when you pipe objects to a cmdlet, they -are delivered one at a time. +This distinction can be important, so remember that when you pipe objects to a +cmdlet, they are delivered one at a time. ### Accepts Pipeline Input -In order to receive objects in a pipeline, the receiving cmdlet must have a parameter -that accepts pipeline input. You can use a `Get-Help` command with the **Full** or **Parameter** -parameters to determine which, if any, of a cmdlet's parameters accepts pipeline input. +In order to receive objects in a pipeline, the receiving cmdlet must have a +parameter that accepts pipeline input. You can use a `Get-Help` command with +the **Full** or **Parameter** parameters to determine which, if any, of a +cmdlet's parameters accepts pipeline input. -In the `Get-Help` default display, the "Accept pipeline input?" item appears in a table -of parameter attributes. This table is displayed only when you use the **Full** or **Parameter** -parameters of the `Get-Help` cmdlet. +In the `Get-Help` default display, the "Accept pipeline input?" item appears +in a table of parameter attributes. This table is displayed only when you use +the **Full** or **Parameter** parameters of the `Get-Help` cmdlet. -For example, to determine which of the parameters of the `Start-Service` cmdlet accepts -pipeline input, type: +For example, to determine which of the parameters of the `Start-Service` +cmdlet accepts pipeline input, type: ```powershell Get-Help Start-Service -Full @@ -326,108 +333,115 @@ or Get-Help Start-Service -Parameter * ``` -For example, the help for the `Start-Service` cmdlet shows that the **InputObject** and **Name** -parameters accept pipeline input ("true"). All other parameters have a value of "false" -in the "Accept pipeline input?" row. +For example, the help for the `Start-Service` cmdlet shows that the +**InputObject** and **Name** parameters accept pipeline input ("true"). All +other parameters have a value of "false" in the "Accept pipeline input?" row. ``` -InputObject - Specifies ServiceController objects representing the services to be started. - Enter a variable that contains the objects, or type a command or expression - that gets the objects. +Specifies ServiceController objects representing the services to be started. +Enter a variable that contains the objects, or type a command or expression +that gets the objects. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByValue) +Accept wildcard characters? false -Name - Specifies the service names for the service to be started. +Specifies the service names for the service to be started. - The parameter name is optional. You can use Name or its alias, ServiceName, - or you can omit the parameter name. +The parameter name is optional. You can use Name or its alias, ServiceName, +or you can omit the parameter name. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByPropertyName, ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByPropertyName, ByValue) +Accept wildcard characters? false ``` This means that you can send objects (PsObjects) through the pipeline to the -`Where-Object` cmdlet and Windows PowerShell will associate the object with the +`Where-Object` cmdlet and PowerShell will associate the object with the **InputObject** and **Name** parameters. ### Methods Of Accepting Pipeline Input - Cmdlets parameters can accept pipeline input in one of two different ways: - ByValue: Parameters that accept input "by value" can accept piped objects -that have the same .NET type as their parameter value or objects that can be -converted to that type. - -For example, the Name parameter of `Start-Service` accepts pipeline input -by value. It can accept string objects or objects that can be converted to -strings. + that have the same .NET type as their parameter value or objects that can be + converted to that type. -- ByPropertyName: Parameters that accept input "by property name" can accept piped -objects only when a property of the object has the same name as the parameter. + For example, the Name parameter of `Start-Service` accepts pipeline input by + value. It can accept string objects or objects that can be converted to + strings. -For example, the Name parameter of `Start-Service` can accept objects that have -a Name property. +- ByPropertyName: Parameters that accept input "by property name" can accept + piped objects only when a property of the object has the same name as the + parameter. -(To list the properties of an object, pipe it to `Get-Member`.) + For example, the Name parameter of `Start-Service` can accept objects that + have a Name property. To list the properties of an object, pipe it to + `Get-Member`. -Some parameters can accept objects by value or by property name. These parameters are -designed to take input from the pipeline easily. +Some parameters can accept objects by value or by property name. These +parameters are designed to take input from the pipeline easily. ### Investigating Pipeline Errors - -If a command fails because of a pipeline error, you can investigate the failure and -rewrite the command. +If a command fails because of a pipeline error, you can investigate the +failure and rewrite the command. For example, the following command tries to move a registry entry from one -registry key to another by using the `Get-Item` cmdlet to get the destination path and -then piping the path to the `Move-ItemProperty` cmdlet. +registry key to another by using the `Get-Item` cmdlet to get the destination +path and then piping the path to the `Move-ItemProperty` cmdlet. -Specifically, the command uses the `Get-Item` cmdlet to get the destination path. It uses -a pipeline operator to send the result to the `Move-ItemProperty` cmdlet. The `Move-ItemProperty` -command specifies the current path and name of the registry entry to be moved. +Specifically, the command uses the `Get-Item` cmdlet to get the destination +path. It uses a pipeline operator to send the result to the +`Move-ItemProperty` cmdlet. The `Move-ItemProperty` command specifies the +current path and name of the registry entry to be moved. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product ``` -``` -The command fails and Windows PowerShell displays the following error +The command fails and PowerShell displays the following error message: -Move-ItemProperty : The input object cannot be bound to any parameters for the -command either because the command does not take pipeline input or the input -and its properties do not match any of the parameters that take pipeline input. +```output +Move-ItemProperty : The input object cannot be bound to any parameters for +the command either because the command does not take pipeline input or the +input and its properties do not match any of the parameters that take +pipeline input. At line:1 char:23 -+ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name product ++ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name p ``` -To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding component of -Windows PowerShell. The following command traces the Parameter Binding component while the -command is processing. It uses the `-PSHost` parameter to display the results at the console -and the `-filepath` command to send them to the debug.txt file for later reference. +To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding +component of PowerShell. The following command traces the Parameter Binding +component while the command is processing. It uses the `-PSHost` parameter to +display the results at the console and the `-filepath` command to send them to +the debug.txt file for later reference. For example, + ```powershell -Trace-Command -Name parameterbinding -Expression {Get-Item -Path HKLM:\software\mycompany\sales | -Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} -PSHost -FilePath debug.txt +Trace-Command -Name parameterbinding -Expression { + Get-Item -Path HKLM:\software\mycompany\sales | + Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} ` + -PSHost -FilePath debug.txt ``` -The results of the trace are lengthy, but they show the values being bound to the `Get-Item` cmdlet -and then the named values being bound to the `Move-ItemProperty` cmdlet. +The results of the trace are lengthy, but they show the values being bound to +the `Get-Item` cmdlet and then the named values being bound to the +`Move-ItemProperty` cmdlet. +``` ... BIND NAMED cmd line args [`Move-ItemProperty`] @@ -442,31 +456,35 @@ BIND arg [product] to parameter [Name] BIND POSITIONAL cmd line args [`Move-ItemProperty`] ... +``` -Finally, it shows that the attempt to bind the path to the Destination parameter -of `Move-ItemProperty` failed. +Finally, it shows that the attempt to bind the path to the **Destination** +parameter of `Move-ItemProperty` failed. +``` ... BIND PIPELINE object to parameters: [`Move-ItemProperty`] PIPELINE object TYPE = [Microsoft.Win32.RegistryKey] RESTORING pipeline parameter's original values -Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION -Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION +Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO CO +ERCION +Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COE +RCION ... +``` - -To investigate the failure, use the `Get-Help` cmdlet to view the attributes of the -**Destination** parameter. The following command gets detailed information about the -**Destination** parameter. +To investigate the failure, use the `Get-Help` cmdlet to view the attributes +of the **Destination** parameter. The following command gets detailed +information about the **Destination** parameter. ```powershell Get-Help Move-ItemProperty -Parameter Destination ``` -The results show that **Destination** takes pipeline input only "by property name". -That is, the piped object must have a property named Destination. +The results show that **Destination** takes pipeline input only "by property +name". That is, the piped object must have a property named Destination. ``` -Destination @@ -479,11 +497,12 @@ That is, the piped object must have a property named Destination. Accept wildcard characters? false ``` -To see the properties of the object being piped to the `Move-ItemProperty` cmdlet, -pipe it to the `Get-Member` cmdlet. The following command pipes the results of the -first part of the command to the `Get-Member` cmdlet. +To see the properties of the object being piped to the `Move-ItemProperty` +cmdlet, pipe it to the `Get-Member` cmdlet. The following command pipes the +results of the first part of the command to the `Get-Member` cmdlet. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Get-Member ``` @@ -491,11 +510,13 @@ Get-Item -Path HKLM:\software\mycompany\sales | Get-Member The output shows that the item is a Microsoft.Win32.RegistryKey that does not have a Destination property. That explains why the command failed. -To fix the command, we must specify the destination in the `Move-ItemProperty` cmdlet. We can -use a `Get-ItemProperty` command to get the path, but the name and destination must be specified -in the `Move-ItemProperty` part of the command. +To fix the command, we must specify the destination in the `Move-ItemProperty` +cmdlet. We can use a `Get-ItemProperty` command to get the path, but the name +and destination must be specified in the `Move-ItemProperty` part of the +command. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\design | Move-ItemProperty -Dest HKLM:\software\mycompany\design -Name product @@ -510,9 +531,11 @@ Get-Itemproperty HKLM:\software\mycompany\sales The results show that the Product registry entry was moved to the Sales key. -``` -PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany\sales -PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany +```Output +PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany\sales +PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany PSChildName : sales PSDrive : HKLM PSProvider : Microsoft.PowerShell.Core\Registry diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_profiles.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_profiles.md index b7eabd81d0ce..eea0dd9f0d50 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_profiles.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_profiles.md @@ -1,104 +1,99 @@ --- -ms.date: 2017-06-25 +ms.date: 2017-11-30 schema: 2.0.0 keywords: powershell,cmdlet title: about_Profiles --- # About Profiles -## about_Profiles +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Describes how to create and use a PowerShell profile. -Describes how to create and use a Windows PowerShell profile. +## LONG DESCRIPTION -# LONG DESCRIPTION +You can create a PowerShell profile to customize your environment and to add +session-specific elements to every PowerShell session that you start. -You can create a Windows PowerShell profile to customize your environment -and to add session-specific elements to every Windows PowerShell session -that you start. +A PowerShell profile is a script that runs when PowerShell starts. You can use +the profile as a logon script to customize the environment. You can add +commands, aliases, functions, variables, snap-ins, modules, and PowerShell +drives. You can also add other session-specific elements to your profile so +they are available in every session without having to import or re-create +them. -A Windows PowerShell profile is a script that runs when Windows PowerShell -starts. You can use the profile as a logon script to customize the -environment. You can add commands, aliases, functions, variables, snap-ins, -modules, and Windows PowerShell drives. You can also add other -session-specific elements to your profile so they are available in every -session without having to import or re-create them. +PowerShell supports several profiles for users and host programs. However, it +does not create the profiles for you. This topic describes the profiles, and +it describes how to create and maintain profiles on your computer. -Windows PowerShell supports several profiles for users and host programs. -However, it does not create the profiles for you. This topic describes the -profiles, and it describes how to create and maintain profiles on your -computer. +It explains how to use the **NoProfile** parameter of the PowerShell console +(PowerShell.exe) to start PowerShell without any profiles. And, it explains +the effect of the PowerShell execution policy on profiles. -It explains how to use the **NoProfile** parameter of the Windows PowerShell -console (PowerShell.exe) to start Windows PowerShell without any profiles. -And, it explains the effect of the Windows PowerShell execution policy on -profiles. +## THE PROFILE FILES -# THE PROFILE FILES +PowerShell supports several profile files. Also, PowerShell host programs can +support their own host-specific profiles. - -Windows PowerShell supports several profile files. Also, Windows PowerShell -host programs can support their own host-specific profiles. - -For example, the Windows PowerShell console supports the following basic +For example, the PowerShell console supports the following basic profile files. The profiles are listed in precedence order. The first profile has the highest precedence. -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Profile.ps1 | -| Current User, All Hosts | $Home\\[My ]Documents\Profile.ps1 | -| All Users, Current Host | $PsHome\Microsoft.PowerShell_profile.ps1 | -| All Users, All Hosts | $PsHome\Profile.ps1 | +|Description | Path | +|--------------------------|------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Profile.ps1 | +|Current User, All Hosts |$Home\\[My ]Documents\\Profile.ps1 | +|All Users, Current Host |$PsHome\Microsoft.PowerShell_profile.ps1 | +|All Users, All Hosts |$PsHome\Profile.ps1 | The profile paths include the following variables: - The `$PsHome` variable, which stores the installation directory for -Windows PowerShell +PowerShell - The `$Home` variable, which stores the current user's home directory -In addition, other programs that host Windows PowerShell can support their -own profiles. For example, Windows PowerShell Integrated Scripting -Environment (ISE) supports the following host-specific profiles. - -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Microsoft.PowerShellISE_profile.ps1 | -| All users, Current Host | $PsHome\Microsoft.PowerShellISE_profile.ps1 | +In addition, other programs that host PowerShell can support their own +profiles. For example, PowerShell Integrated Scripting Environment (ISE) +supports the following host-specific profiles. -In Windows PowerShell Help, the "CurrentUser, Current Host" profile is the profile most -often referred to as "your Windows PowerShell profile". +|Description | Path | +|--------------------------|-------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Microsoft.PowerShellISE_profile.ps1 | +|All users, Current Host |$PsHome\Microsoft.PowerShellISE_profile.ps1| -# THE $PROFILE VARIABLE +In PowerShell Help, the "CurrentUser, Current Host" profile is the profile +most often referred to as "your PowerShell profile". +## THE $PROFILE VARIABLE -The `$Profile` automatic variable stores the paths to the Windows PowerShell -profiles that are available in the current session. +The `$Profile` automatic variable stores the paths to the PowerShell profiles +that are available in the current session. To view a profile path, display the value of the `$Profile` variable. You can also use the `$Profile` variable in a command to represent a path. -The `$Profile` variable stores the path to the "Current User, -Current Host" profile. The other profiles are saved in note properties of -the `$Profile` variable. +The `$Profile` variable stores the path to the "Current User, Current Host" +profile. The other profiles are saved in note properties of the `$Profile` +variable. For example, the `$Profile` variable has the following values in the Windows PowerShell console. -| Name | Description | -| ------------- | ------------- | -| $Profile | Current User, Current Host | -| $Profile.CurrentUserCurrentHost | Current User, Current Host | -| $Profile.CurrentUserAllHosts | Current User, All Hosts | -| $Profile.AllUsersCurrentHost | All Users, Current Host | -| $Profile.AllUsersAllHosts | All Users, All Hosts | +|Name |Description | +|--------------------------------|---------------------------| +|$Profile |Current User, Current Host | +|$Profile.CurrentUserCurrentHost |Current User, Current Host | +|$Profile.CurrentUserAllHosts |Current User, All Hosts | +|$Profile.AllUsersCurrentHost |All Users, Current Host | +|$Profile.AllUsersAllHosts |All Users, All Hosts | -Because the values of the `$Profile` variable change for each user and in -each host application, ensure that you display the values of the -profile variables in each Windows PowerShell host application that you use. +Because the values of the `$Profile` variable change for each user and in each +host application, ensure that you display the values of the profile variables +in each PowerShell host application that you use. To see the current values of the `$Profile` variable, type: @@ -107,24 +102,22 @@ $profile | Get-Member -Type NoteProperty ``` You can use the `$Profile` variable in many commands. For example, the -following command opens the "Current User, Current Host" profile in -Notepad: +following command opens the "Current User, Current Host" profile in Notepad: ```powershell notepad $profile ``` -The following command determines whether an "All Users, All Hosts" profile -has been created on the local computer: +The following command determines whether an "All Users, All Hosts" profile has +been created on the local computer: ```powershell Test-Path -Path $profile.AllUsersAllHosts ``` -# HOW TO CREATE A PROFILE +## HOW TO CREATE A PROFILE - -To create a Windows PowerShell profile, use the following command format: +To create a PowerShell profile, use the following command format: ```powershell if (!(Test-Path -Path )) @@ -132,7 +125,7 @@ if (!(Test-Path -Path )) ``` For example, to create a profile for the current user in the current -Windows PowerShell host application, use the following command: +PowerShell host application, use the following command: ```powershell if (!(Test-Path -Path $profile)) @@ -140,21 +133,18 @@ if (!(Test-Path -Path $profile)) ``` In this command, the If statement prevents you from overwriting an existing -profile. Replace the value of the placeholder with the path +profile. Replace the value of the \ placeholder with the path to the profile file that you want to create. ->Note: To create "All Users" profiles in Windows Vista and later versions ->of Windows, start Windows PowerShell with the "Run as administrator" ->option. - -# HOW TO EDIT A PROFILE +> Note: To create "All Users" profiles in Windows Vista and later versions of +> Windows, start PowerShell with the "Run as administrator" >option. +## HOW TO EDIT A PROFILE -You can open any Windows PowerShell profile in a text editor, such as -Notepad. +You can open any PowerShell profile in a text editor, such as Notepad. -To open the profile of the current user in the current Windows PowerShell -host application in Notepad, type: +To open the profile of the current user in the current PowerShell host +application in Notepad, type: ```powershell notepad $profile @@ -167,106 +157,99 @@ profile for all the users of all the host applications, type: notepad $profile.AllUsersAllHosts ``` -To apply the changes, save the profile file, and then restart Windows -PowerShell. +To apply the changes, save the profile file, and then restart PowerShell. -# HOW TO CHOOSE A PROFILE +## HOW TO CHOOSE A PROFILE +If you use multiple host applications, put the items that you use in all the +host applications into your `$Profile.CurrentUserAllHosts` profile. Put items +that are specific to a host application, such as a command that sets the +background color for a host application, in a profile that is specific to that +host application. -If you use multiple host applications, put the items that you use in all -the host applications into your `$Profile.CurrentUserAllHosts` profile. -Put items that are specific to a host application, such as a command that -sets the background color for a host application, in a profile that is -specific to that host application. - -If you are an administrator who is customizing Windows -PowerShell for many users, follow these guidelines: +If you are an administrator who is customizing Windows PowerShell for many +users, follow these guidelines: - Store the common items in the `$profile.AllUsersAllHosts` profile - - Store items that are specific to a host application in -`$profile.AllUsersCurrentHost` profiles that are specific to the host -application - + `$profile.AllUsersCurrentHost` profiles that are specific to the host + application - Store items for particular users in the user-specific profiles Be sure to check the host application documentation for any special -implementation of Windows PowerShell profiles. - -# HOW TO USE A PROFILE +implementation of PowerShell profiles. +## HOW TO USE A PROFILE -Many of the items that you create in Windows PowerShell and most commands -that you run affect only the current session. When you end the session, -the items are deleted. +Many of the items that you create in PowerShell and most commands that you run +affect only the current session. When you end the session, the items are +deleted. The session-specific commands and items include variables, preference -variables, aliases, functions, commands (except for [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), -and Windows PowerShell snap-ins that you add to the session. +variables, aliases, functions, commands (except for +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), +and PowerShell modules that you add to the session. -To save these items and make them available in all future sessions, add -them to a Windows PowerShell profile. +To save these items and make them available in all future sessions, add them +to a PowerShell profile. -Another common use for profiles is to save frequently-used functions, -aliases, and variables. When you save the items in a profile, you can -use them in any applicable session without re-creating them. +Another common use for profiles is to save frequently-used functions, aliases, +and variables. When you save the items in a profile, you can use them in any +applicable session without re-creating them. -# HOW TO START A PROFILE +## HOW TO START A PROFILE - -When you open the profile file, it is blank. However, you can fill it with -the variables, aliases, and commands that you use frequently. +When you open the profile file, it is blank. However, you can fill it with the +variables, aliases, and commands that you use frequently. Here are a few suggestions to get you started. -- Add commands that make it easy to open your profile. This is especially -useful if you use a profile other than the "Current User, Current Host" -profile. For example, add the following command: +### Add commands that make it easy to open your profile + +This is especially useful if you use a profile other than the "Current User, +Current Host" profile. For example, add the following command: ```powershell function Pro {notepad $profile.CurrentUserAllHosts} ``` -- Add a function that opens Windows PowerShell Help in a compiled HTML -Help file (.chm) +### Add a function that opens PowerShell Help in a compiled HTML + Help file (.chm) ```powershell -function Get-CHM -{ -Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" +function Get-CHM { + Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" } ``` -This function opens the English version of the .chm file. However, you -can replace the language code (0409) to open other versions of the .chm -file. +This function opens the English version of the .chm file. However, you can +replace the language code (0409) to open other versions of the .chm file. -- Add a function that lists the aliases for any cmdlet +### Add a function that lists the aliases for any cmdlet ```powershell -function Get-CmdletAlias ($cmdletname) -{ -Get-Alias | Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | Format-Table -Property Definition, Name -AutoSize +function Get-CmdletAlias ($cmdletname) { + Get-Alias | + Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | + Format-Table -Property Definition, Name -AutoSize } ``` -- Customize your console +### Customize your console ```powershell -function Color-Console -{ -$Host.ui.rawui.backgroundcolor = "white" -$Host.ui.rawui.foregroundcolor = "black" -$hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime -$hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" -$Host.UI.RawUI.WindowTitle = "Windows PowerShell $hostversion ($hosttime)" -Clear-Host +function Color-Console { + $Host.ui.rawui.backgroundcolor = "white" + $Host.ui.rawui.foregroundcolor = "black" + $hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime + $hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" + $Host.UI.RawUI.WindowTitle = "PowerShell $hostversion ($hosttime)" + Clear-Host } Color-Console ``` -- Add a customized Windows PowerShell prompt that includes the computer -name and the current path +### Add a customized PowerShell prompt ```powershell function Prompt @@ -275,18 +258,16 @@ $env:COMPUTERNAME + "\" + (Get-Location) + "> " } ``` -For more information about the Windows PowerShell prompt, see +For more information about the PowerShell prompt, see [about_Prompts](about_Prompts.md). -# THE NOPROFILE PARAMETER +## THE NOPROFILE PARAMETER +To start PowerShell without profiles, use the **NoProfile** parameter of +PowerShell.exe, the program that starts PowerShell. -To start Windows PowerShell without profiles, use the **NoProfile** parameter -of PowerShell.exe, the program that starts Windows PowerShell. - -To begin, open a program that can start Windows PowerShell, such as Cmd.exe -or Windows PowerShell itself. You can also use the Run dialog box in -Windows. +To begin, open a program that can start PowerShell, such as Cmd.exe or +PowerShell itself. You can also use the Run dialog box in Windows. Type: @@ -294,56 +275,58 @@ Type: PowerShell -NoProfile ``` -For a complete list of the parameters of PowerShell.exe, -type: +For a complete list of the parameters of PowerShell.exe, type: ``` PowerShell -? ``` -# PROFILES AND EXECUTION POLICY - +## PROFILES AND EXECUTION POLICY -The Windows PowerShell execution policy determines, in part, whether you -can run scripts and load configuration files, including the profiles. The -"Restricted" execution policy is the default. It prevents all scripts from -running, including the profiles. If you use the "Restricted" policy, the -profile does not run, and its contents are not applied. +The PowerShell execution policy determines, in part, whether you can run +scripts and load configuration files, including the profiles. The "Restricted" +execution policy is the default. It prevents all scripts from running, +including the profiles. If you use the "Restricted" policy, the profile does +not run, and its contents are not applied. A `Set-ExecutionPolicy` command sets and changes your execution policy. It is -one of the few commands that applies in all Windows PowerShell sessions -because the value is saved in the registry. You do not have to set it when -you open the console, and you do not have to store a `Set-ExecutionPolicy` -command in your profile. +one of the few commands that applies in all PowerShell sessions because the +value is saved in the registry. You do not have to set it when you open the +console, and you do not have to store a `Set-ExecutionPolicy` command in your +profile. -# PROFILES AND REMOTE SESSIONS +## PROFILES AND REMOTE SESSIONS +PowerShell profiles are not run automatically in remote sessions, so the +commands that the profiles add are not present in the remote session. In +addition, the `$Profile` automatic variable is not populated in remote +sessions. -Windows PowerShell profiles are not run automatically in remote sessions, -so the commands that the profiles add are not present in the remote session. -In addition, the `$Profile` automatic variable is not populated in remote sessions. +To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) +cmdlet. -To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) cmdlet. - -For example, the following command runs the "Current user, Current Host" profile from -the local computer in the session in $s. +For example, the following command runs the "Current user, Current Host" +profile from the local computer in the session in $s. ```powershell Invoke-Command -Session $s -FilePath $profile ``` -The following command runs the "Current user, Current Host" profile from the remote -computer in the session in $s. Because the `$Profile` variable is not populated, -the command uses the explicit path to the profile. +The following command runs the "Current user, Current Host" profile from the +remote computer in the session in $s. Because the `$Profile` variable is not +populated, the command uses the explicit path to the profile. ```powershell -Invoke-Command -SessionName $s -ScriptBlock {Invoke-Command -FilePath "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +Invoke-Command -SessionName $s -ScriptBlock { +$path = "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +Invoke-Command -FilePath $path +} ``` After running this command, the commands that the profile adds to the session are available in $s. -# SEE ALSO +## SEE ALSO [about_Automatic_Variables](about_Automatic_Variables.md) diff --git a/reference/3.0/Microsoft.PowerShell.Management/Get-Process.md b/reference/3.0/Microsoft.PowerShell.Management/Get-Process.md index 474484723bcd..10db0fdf498d 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Get-Process.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Get-Process.md @@ -80,18 +80,26 @@ The first command gets all the processes on the computer and then stores them in The second command uses the InputObject parameter to pass the process objects that are stored in the $a variable to the Get-Process cmdlet. The pipeline operator passes the objects to the Format-Table cmdlet, which formats the processes by using the Priority view. The Priority view, and other views, are defined in the PS1XML format files in the Windows PowerShell home directory ($pshome). + ### Example 5 -``` -PS C:\> get-process powershell -computername S1, localhost | ft @{Label="NPM(K)";Expression={[int]($_.NPM/1024)}}, @{Label="PM(K)";Expression={[int]($_.PM/1024)}},@{Label="WS(K)";Expression={[int]($_.WS/1024)}},@{Label="VM(M)";Expression={[int]($_.VM/1MB)}}, @{Label="CPU(s)";Expression={if ($_.CPU -ne $()) { $_.CPU.ToString("N")}}}, Id, MachineName, ProcessName -auto +```powershell +PS C:\> Get-Process powershell -ComputerName S1, localhost | + ft @{Label = "NPM(K)"; Expression = {[int]($_.NPM / 1024)}}, + @{Label = "PM(K)"; Expression = {[int]($_.PM / 1024)}}, + @{Label = "WS(K)"; Expression = {[int]($_.WS / 1024)}}, + @{Label = "VM(M)"; Expression = {[int]($_.VM / 1MB)}}, + @{Label = "CPU(s)"; Expression = {if ($_.CPU) {$_.CPU.ToString("N")}}}, + Id, MachineName, ProcessName -Auto NPM(K) PM(K) WS(K) VM(M) CPU(s) Id MachineName ProcessName ------ ----- ----- ----- ------ -- ----------- ----------- -6 23500 31340 142 1980 S1 powershell -6 23500 31348 142 4016 S1 powershell -27 54572 54520 576 4428 localhost powershell + 6 23500 31340 142 1.70 1980 S1 powershell + 6 23500 31348 142 2.75 4016 S1 powershell + 27 54572 54520 576 5.52 4428 localhost powershell ``` -This example provides a Format-Table (alias = ft) command that adds the MachineName property to the standard Get-Process output display. +This example provides a `Format-Table` (alias = ft) command that adds the MachineName property to the standard `Get-Process` output display. + ### Example 6 ``` PS C:\> get-process powershell -fileversioninfo diff --git a/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md b/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md index 356991652b06..1884a2f47f8b 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md @@ -14,9 +14,9 @@ Combines a path and a child path into a single path. The provider supplies the path delimiters. ## SYNTAX -``` -Join-Path [-Path] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] - [] +```powershell +Join-Path [-Path] [-ChildPath] + [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## DESCRIPTION @@ -76,7 +76,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True @@ -117,7 +117,7 @@ Parameter Sets: (All) Aliases: PSPath Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Get-TraceSource.md b/reference/3.0/Microsoft.PowerShell.Utility/Get-TraceSource.md index 0cc3f5939afa..89b617870d7c 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Get-TraceSource.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Get-TraceSource.md @@ -50,7 +50,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md index 7a62b5bef11e..0f745ac3aa94 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,232 +7,246 @@ title: about_Object_Creation --- # About Object Creation -## about_Object_Creation - ## SHORT DESCRIPTION -Explains how to create objects in Windows PowerShell®. +Explains how to create objects in PowerShell. ## LONG DESCRIPTION -You can create objects in Windows PowerShell and use the objects that you create in commands and scripts. - -There are several ways to create objects: - -New-Object: -The New-Object cmdlet creates an instance of a .NET Framework object or COM object. +You can create objects in PowerShell and use the objects that you create in +commands and scripts. -Hash tables: +There are several ways to create objects: -Beginning in Windows PowerShell 3.0, you can create objects from hash tables of property names and property values. +- `New-Object`: This cmdlet creates an instance of a .NET Framework object or + COM object. -Import-Csv: +- Hash tables: Beginning in PowerShell 3.0, you can create objects + from hash tables of property names and property values. -The Import-Csv cmdlet creates custom objects (PSCustomObject) from the items in a CSV file. Each row is an object instance and each column is an object property. +- `Import-Csv`: This cmdlet creates custom objects (PSCustomObject) from the + items in a CSV file. Each row is an object instance and each column is an + object property. This topic will demonstrate and discuss each of these methods. - ## NEW-OBJECT -The New-Object cmdlet provides a robust and consistent way to create new objects. The cmdlet works with almost all types and in all supported versions of Windows PowerShell. -To create a new object, specify either the type of a .NET Framework class or a ProgID of a COM object. +The `New-Object` cmdlet provides a robust and consistent way to create new +objects. The cmdlet works with almost all types and in all supported versions +of PowerShell. -For example, the following command creates a Version object. +To create a new object, specify either the type of a .NET Framework class or a +ProgID of a COM object. +For example, the following command creates a Version object. -``` -PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 +```powershell +PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 PS C:\> $v ``` - - -``` -Major Minor Build Revision ------ ----- ----- -------- +```Output +Major Minor Build Revision +----- ----- ----- -------- 2 0 0 1 ``` +```powershell +PS C:\> $v | Get-Member - -``` -PS C:\> $v | Get-Member - TypeName: System.Version ``` - For more information, see the help topic for the New-Object cmdlet. - ### CREATE 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: ``` -[]@{=;=} +[]@{ + = + = +} ``` - -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. ### CREATE CUSTOM OBJECTS FROM HASH TABLES -Custom objects are very useful and they are very easy to create by using the hash table method. To create a custom object, use the PSCustomObject class, a class designed specifically for this purpose. - -Custom objects are an excellent way to return customized output from a function or script; far more useful than returning formatted output that cannot be reformatted or piped to other commands. - -The commands in the Test-Object function set some variable values and then use those values to create a custom object. (You can see this object in use in the example section of the Update-Help cmdlet help topic.) - -``` -function Test-Object -{ $ModuleName = "PSScheduledJob" - $HelpCulture = "en-us" - $HelpVersion = "3.1.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} - - $ModuleName = "PSWorkflow" - $HelpCulture = "en-us" - $HelpVersion = "3.0.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} +Custom objects are very useful and they are very easy to create by using the +hash table method. To create a custom object, use the PSCustomObject class, a +class designed specifically for this purpose. + +Custom objects are an excellent way to return customized output from a +function or script; far more useful than returning formatted output that +cannot be reformatted or piped to other commands. + +The commands in the `Test-Object function` set some variable values and then +use those values to create a custom object. You can see this object in use in +the example section of the `Update-Help` cmdlet help topic. + +```powershell +function Test-Object { + $ModuleName = "PSScheduledJob" + $HelpCulture = "en-us" + $HelpVersion = "3.1.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } + $ModuleName = "PSWorkflow" + $HelpCulture = "en-us" + $HelpVersion = "3.0.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } } ``` +The output of this function is a collection of custom objects formatted as a +table by default. -The output of this function is a collection of custom objects formatted as a table by default. - +```powershell +PS C:\> Test-Object -``` -PS C:\> Test-Object - -ModuleName UICulture Version ---------- --------- ------- -PSScheduledJob en-us 3.1.0.0 +ModuleName UICulture Version +--------- --------- ------- +PSScheduledJob en-us 3.1.0.0 PSWorkflow en-us 3.0.0.0 ``` +Users can manage the properties of the custom objects just as they do with +standard objects. -Users can manage the properties of the custom objects just as they do with standard objects. - - -``` -PS C:\> (Test-Object).ModuleName - PSScheduledJob +```powershell +PS C:\> (Test-Object).ModuleName + PSScheduledJob PSWorkflow ``` - - #### CREATE NON-CUSTOM OBJECTS FROM HASH TABLES -You can also use hash tables to create objects for non-custom classes. When you create an object for a non-custom class, the full namespace name is required unless class is in the System namespace. Use only the properties of the class. -For example, the following command creates a session option object. +You can also use hash tables to create objects for non-custom classes. When +you create an object for a non-custom class, the full namespace name is +required unless class is in the System namespace. Use only the properties of +the class. +For example, the following command creates a session option object. +```powershell +[System.Management.Automation.Remoting.PSSessionOption]@{ + IdleTimeout=43200000 + SkipCnCheck=$True +} ``` -[System.Management.Automation.Remoting.PSSessionOption]@{IdleTimeout=43200000; SkipCnCheck=$True} -``` - -The requirements of the hash table feature, especially the null constructor requirement, eliminate many existing classes. However, most Windows PowerShell option classes are designed to work with this feature, as well as other very useful classes, such as the ScheduledJobTrigger class. +The requirements of the hash table feature, especially the null constructor +requirement, eliminate many existing classes. However, most PowerShell option +classes are designed to work with this feature, as well as other very useful +classes, such as the ScheduledJobTrigger class. +```powershell +[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{ + Frequency="Daily" + At="15:00" +} -``` -[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{Frequency="Daily";At="15:00"} - -Id Frequency Time DaysOfWeek Enabled --- --------- ---- ---------- ------- -0 Daily 6/6/2012 3:00:00 PM True +Id Frequency Time DaysOfWeek Enabled +-- --------- ---- ---------- ------- +0 Daily 6/6/2012 3:00:00 PM True ``` +You can also use the hash table feature when setting parameter values. For +example, the value of the **SessionOption** parameter of the New-PSSession +cmdlet and the value of the JobTrigger parameter of `Register-ScheduledJob` +can be a hash table. -You can also use the hash table feature when setting parameter values. For example, the value of the SessionOption parameter of the New-PSSession cmdlet and the value of the JobTrigger parameter of Register-ScheduledJob can be a hash table. - - -``` -New-PSSession -ComputerName Server01 -SessionOption @{IdleTimeout=43200000; SkipCnCheck=$True} -Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{Frequency="Daily";At="15:00"} +```powershell +New-PSSession -ComputerName Server01 -SessionOption @{ + IdleTimeout=43200000 + SkipCnCheck=$True +} +Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{ + Frequency="Daily" + At="15:00" +} ``` - - ### IMPORT-CSV -You can create custom objects from the items in a CSV file. When you use the Import-Csv cmdlet to import the CSV file, the cmdlet creates a custom object (PSCustomObject) for each item in the file. The column names are the object properties. -For example, if you import a CSV file of computer asset data, Import-CSV creates a collection of custom objects from the input. +You can create custom objects from the items in a CSV file. When you use the +`Import-Csv` cmdlet to import the CSV file, the cmdlet creates a custom object +(PSCustomObject) for each item in the file. The column names are the object +properties. +For example, if you import a CSV file of computer asset data, `Import-CSV` +creates a collection of custom objects from the input. ``` -#In Servers.csv -AssetID, Name, OS, Department -003, Server01, Windows Server 2012, IT -103, Server33, Windows 7, Marketing +#In Servers.csv +AssetID, Name, OS, Department +003, Server01, Windows Server 2012, IT +103, Server33, Windows 7, Marketing 212, Server35, Windows 8, Finance ``` +```powershell +PS C:\> $a = Import-Csv Servers.csv +PS C:\> $a - -``` -PS C:\> $a = Import-Csv Servers.csv -PS C:\> $a - -AssetID Name OS Department -------- ---- -- ---------- -003 Server01 Windows Server 2012 IT -103 Server33 Windows 7 Marketing +AssetID Name OS Department +------- ---- -- ---------- +003 Server01 Windows Server 2012 IT +103 Server33 Windows 7 Marketing 212 Server35 Windows 8 Finance ``` - Use the Get-Member cmdlet to confirm the object type. - -``` +```powershell PS C:\> $a | Get-Member ``` +```Output +TypeName: System.Management.Automation.PSCustomObject - -``` -TypeName: System.Management.Automation.PSCustomObject - -Name MemberType Definition ----- ---------- ---------- -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -AssetID NoteProperty System.String AssetID=003 -Department NoteProperty System.String Department=IT -Name NoteProperty System.String Name=Server01 +Name MemberType Definition +---- ---------- ---------- +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +AssetID NoteProperty System.String AssetID=003 +Department NoteProperty System.String Department=IT +Name NoteProperty System.String Name=Server01 OS NoteProperty System.String OS=Windows Server 2012 ``` - You can use the custom objects just as you would standard objects. - -``` +```powershell PS C:\> $a | where {$_.OS -eq "Windows 8"} ``` - - -``` -AssetID Name OS Department -------- ---- -- ---------- +```output +AssetID Name OS Department +------- ---- -- ---------- 212 Server35 Windows 8 Finance ``` - For more information, see the help topic for the Import-Csv cmdlet. - ## SEE ALSO [about_Objects](about_Objects.md) @@ -243,9 +257,8 @@ For more information, see the help topic for the Import-Csv cmdlet. [about_Pipelines](about_Pipelines.md) -Get-Member - -Import-Csv +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -New-Object +[Import-Csv](../../Microsoft.PowerShell.Utility/Import-Csv.md) +[New-Object](../../Microsoft.PowerShell.Utility/New-Object.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Objects.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Objects.md index 88ab499af532..58308cabd6d7 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Objects.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Objects.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -58,20 +58,13 @@ directory objects are passed down the pipeline to the second command. The second command `where { $_.PsIsContainer -eq $false }` uses the PsIsContainer property of all file system objects to select only -files, which have a value of False ($false) in their PsIsContainer +files, which have a value of False (\$false) in their PsIsContainer property. Folders, which are containers and, thus, have a value of -True ($true) in their PsIsContainer property, are not selected. +True (\$true) in their PsIsContainer property, are not selected. The second command passes only the file objects to the third command `Format-List`, which displays the file objects in a list. -## For More Information - -Now that you understand a bit about objects, see the [about_Methods](about_Methods.md) -help topic to learn how to find and use object methods, the -[about_Properties](about_Properties.md) topic to learn how to find and use object properties, -and the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) topic, to learn how to find an object type. - ## See Also [about_Methods](about_Methods.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 6e83191b889c..01d129ccc4bb 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,84 +10,85 @@ title: about_Operator_Precedence ## SHORT DESCRIPTION -Lists the Windows PowerShell operators in precedence order. +Lists the PowerShell operators in precedence order. -[This topic was contributed by Kirk Munro, a Windows PowerShell MVP +[This topic was contributed by Kirk Munro, a PowerShell MVP from Ottawa, Ontario] ## LONG DESCRIPTION -Windows PowerShell operators let you construct simple, but powerful -expressions. This topic lists the operators in precedence order. -Precedence order is the order in which Windows PowerShell evaluates -the operators when multiple operators appear in the same expression. - -When operators have equal precedence, Windows PowerShell evaluates -them from left to right. The exceptions are the assignment operators, -the cast operators, and the negation operators (!, -not, -bnot), -which are evaluated from right to left. - -You can use enclosures, such as parentheses, to override the -standard precedence order and force Windows PowerShell to evaluate -the enclosed part of an expression before an unenclosed part. - -In the following list, operators are listed in the order that they -are evaluated. Operators on the same line, or in the same group, have -equal precedence. - -The Operator column lists the operators. The Reference column lists -the Windows PowerShell Help topic in which the operator is described. -To display the topic, type `get-help `. - -|OPERATOR|REFERENCE| -|--------|---------| -|`$() @()`|[about_Operators](#index-operator)| -|`.` (dereference) `::` (static)|[about_Operators](about_Operators.md)| -|`[0]` (index operator)|[about_Operators](about_Operators.md)| +PowerShell operators let you construct simple, but powerful +expressions. This topic lists the operators in precedence order. Precedence +order is the order in which PowerShell evaluates the operators when +multiple operators appear in the same expression. + +When operators have equal precedence, PowerShell evaluates them from +left to right. The exceptions are the assignment operators, the cast +operators, and the negation operators (!, -not, -bnot), which are evaluated +from right to left. + +You can use enclosures, such as parentheses, to override the standard +precedence order and force PowerShell to evaluate the enclosed part of +an expression before an unenclosed part. + +In the following list, operators are listed in the order that they are +evaluated. Operators on the same line, or in the same group, have equal +precedence. + +The Operator column lists the operators. The Reference column lists the +PowerShell Help topic in which the operator is described. To display +the topic, type `get-help `. + +|OPERATOR |REFERENCE| +|------------------------|---------| +|`$() @()` |[about_Operators](#index-operator)| +|`.` (dereference) |[about_Operators](about_Operators.md)| +|`::` (static) |[about_Operators](about_Operators.md)| +|`[0]` (index operator) |[about_Operators](about_Operators.md)| |`[int]` (cast operators)|[about_Operators](about_Operators.md)| -|`-split` (unary)
`-join` (unary)|[about_Split](about_Split.md)
[about_Join](about_Join.md)| -|`,` (comma operator)|[about_Operators](about_Operators.md)| -|`++ --`|[about_Assignment_Operators](about_Assignment_Operators.md)| -|`-not`
`! -bNot`|[about_Logical_Operators](about_logical_operators.md)
[about_Comparison_Operators](about_Comparison_Operators.md)| -|`..` (range operator)|[about_Operators](about_Operators.md)| -|`-f` (format operator)|[about_Operators](about_Operators.md)| -|`* / %`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`+ -`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| - - -The following group of operators have equal precedence. Their -case-sensitive and explicitly case-insensitive variants have -the same precedence. - -|OPERATOR|REFERENCE| -|--------|---------| -|`-split` (unary)|[about_Split](about_Split.md)| -|`-join` (unary)|[about_Join](about_Join.md)| -|`-is -isnot -as`|[about_Type_Operators](about_Type_Operators.md)| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`,` (comma operator) |[about_Operators](about_Operators.md)| +|`++ --` |[about_Assignment_Operators](about_Assignment_Operators.md)| +|`-not` |[about_Logical_Operators](about_logical_operators.md)| +|`! -bNot` |[about_Comparison_Operators](about_Comparison_Operators.md)| +|`..` (range operator) |[about_Operators](about_Operators.md)| +|`-f` (format operator) |[about_Operators](about_Operators.md)| +|`* / % + -` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| + +The following group of operators have equal precedence. Their case-sensitive +and explicitly case-insensitive variants have the same precedence. + +|OPERATOR |REFERENCE| +|-------------------------|---------| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`-is -isnot -as` |[about_Type_Operators](about_Type_Operators.md)| |`-eq -ne -gt -gt -lt -le`|[about_Comparison_Operators](about_Comparison_Operators.md)| -|`-like -notlike`|[about_comparison_operators](about_comparison_operators.md)| -|`-match -notmatch`|[about_comparison_operators](about_comparison_operators.md)| -|`-in -notIn`|[about_comparison_operators](about_comparison_operators.md)| -|`-contains -notContains`|[about_comparison_operators](about_comparison_operators.md)| -|`-replace`|[about_comparison_operators](about_comparison_operators.md)| +|`-like -notlike` |[about_comparison_operators](about_comparison_operators.md)| +|`-match -notmatch` |[about_comparison_operators](about_comparison_operators.md)| +|`-in -notIn` |[about_comparison_operators](about_comparison_operators.md)| +|`-contains -notContains` |[about_comparison_operators](about_comparison_operators.md)| +|`-replace` |[about_comparison_operators](about_comparison_operators.md)| The list resumes here with the following operators in precedence order: -|OPERATOR|REFERENCE| -|--------|---------| -|`-band -bor -bxor`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor`|[about_comparison_operators](about_comparison_operators.md)| -|`.` (dot-source)
`&` (call)|[about_Scopes](about_Scopes.md)
[about_Operators](about_Operators.md)| +|OPERATOR |REFERENCE| +|--------------------------|---------| +|`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| +|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`.` (dot-source) |[about_Scopes](about_Scopes.md)| +|`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| -|`> >> 2> 2>> 2>&1`|[about_Redirection](about_Redirection.md)| -|`= += -= *= /= %=`|[about_Assignment_Operators](about_Assignment_Operators.md)| +|`> >> 2> 2>> 2>&1` |[about_Redirection](about_Redirection.md)| +|`= += -= *= /= %=` |[about_Assignment_Operators](about_Assignment_Operators.md)| # EXAMPLES -The following two commands show the arithmetic operators and -the effect of using parentheses to force Windows PowerShell to -evaluate the enclosed part of the expression first. +The following two commands show the arithmetic operators and the effect of +using parentheses to force PowerShell to evaluate the enclosed part of +the expression first. ```powershell C:\PS> 2 + 3 * 4 @@ -97,8 +98,8 @@ C:\PS> (2 + 3) * 4 20 ``` -The following example gets the read-only text files from the local -directory and saves them in the `$read_only` variable. +The following example gets the read-only text files from the local directory +and saves them in the `$read_only` variable. ```powershell $read_only = get-childitem *.txt | where-object {$_.isReadOnly} @@ -109,37 +110,37 @@ It is equivalent to the following example. $read_only = ( get-childitem *.txt | where-object {$_.isReadOnly} ) ``` -Because the pipeline operator (|) has a higher precedence than the -assignment operator (=), the files that the Get-ChildItem cmdlet -gets are sent to the Where-Object cmdlet for filtering before they -are assigned to the $read_only variable. +Because the pipeline operator (|) has a higher precedence than the assignment +operator (=), the files that the Get-ChildItem cmdlet gets are sent to the +Where-Object cmdlet for filtering before they are assigned to the $read_only +variable. -The following example demonstrates that the index operator takes -precedence over the cast operator. +The following example demonstrates that the index operator takes precedence +over the cast operator. -The first expression creates an array of three strings. Then, it -uses the index operator with a value of 0 to select the first object -in the array, which is the first string. Finally, it casts the -selected object as a string. In this case, the cast has no effect. +The first expression creates an array of three strings. Then, it uses the +index operator with a value of 0 to select the first object in the array, +which is the first string. Finally, it casts the selected object as a string. +In this case, the cast has no effect. ```powershell C:\PS> [string]@('Windows','PowerShell','2.0')[0] Windows ``` -The second expression uses parentheses to force the cast operation -to occur before the index selection. As a result, the entire array -is cast as a (single) string. Then, the index operator selects -the first item in the string array, which is the first character. +The second expression uses parentheses to force the cast operation to occur +before the index selection. As a result, the entire array is cast as a +(single) string. Then, the index operator selects the first item in the string +array, which is the first character. ```powershell C:\PS> ([string]@('Windows','PowerShell','2.0'))[0] W ``` -In the following example, because the -gt (greater-than) operator -has a higher precedence than the -and (logical AND) operator, the -result of the expression is FALSE. +In the following example, because the -gt (greater-than) operator has a higher +precedence than the -and (logical AND) operator, the result of the expression +is FALSE. ```powershell C:\PS> 2 -gt 4 -and 1 @@ -160,11 +161,11 @@ C:\PS> 2 -gt (4 -and 1) True ``` -However, this example demonstrates an important principle of managing -operator precedence. When an expression is difficult for people to -interpret, use parentheses to force the evaluation order, even when it -forces the default operator precedence. The parentheses make your -intentions clear to people who are reading and maintaining your scripts. +However, this example demonstrates an important principle of managing operator +precedence. When an expression is difficult for people to interpret, use +parentheses to force the evaluation order, even when it forces the default +operator precedence. The parentheses make your intentions clear to people who +are reading and maintaining your scripts. ## SEE ALSO @@ -185,4 +186,3 @@ intentions clear to people who are reading and maintaining your scripts. [about_Split](about_Split.md) [about_Type_Operators](about_Type_Operators.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 46c3c136e573..e9c4ebaefa98 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,449 +7,409 @@ title: about_Parameters_Default_Values --- # About Parameters Default Values -## about_Parameters_Default_Values - ## SHORT DESCRIPTION -Describes how to set custom default values for the parameters of cmdlets and advanced functions. +Describes how to set custom default values for the parameters of cmdlets and +advanced functions. ## LONG DESCRIPTION -The $PSDefaultParameterValues preference variable lets you specify custom default values for any cmdlet or advanced function. Cmdlets and functions use the custom default value unless you specify another value in the command. -The authors of cmdlets and advanced functions set standard default values for their parameters. Typically, the standard default values are useful, but they might not be appropriate for all environments. +The \$PSDefaultParameterValues preference variable lets you specify custom +default values for any cmdlet or advanced function. Cmdlets and functions use +the custom default value unless you specify another value in the command. + +The authors of cmdlets and advanced functions set standard default values for +their parameters. Typically, the standard default values are useful, but they +might not be appropriate for all environments. -This feature is especially useful when you must specify the same alternate parameter value nearly every time you use the command or when a particular parameter value is difficult to remember, such as an e-mail server name or project GUID. +This feature is especially useful when you must specify the same alternate +parameter value nearly every time you use the command or when a particular +parameter value is difficult to remember, such as an e-mail server name or +project GUID. -If the desired default value varies predictably, you can specify a script block that provides different default values for a parameter under different conditions. +If the desired default value varies predictably, you can specify a script +block that provides different default values for a parameter under different +conditions. -$PSDefaultParameterValues was introduced in Windows PowerShell® 3.0. +\$PSDefaultParameterValues was introduced in PowerShell 3.0. +## SYNTAX -### SYNTAX The syntax of the $PSDefaultParameterValues preference variable is as follows: +```powershell +$PSDefaultParameterValues=@{":"=""} + +$PSDefaultParameterValues=@{":"={}} -``` -$PSDefaultParameterValues=@{":"=""} - -$PSDefaultParameterValues=@{":"={}} - $PSDefaultParameterValues["Disabled"]=$true | $false ``` - Wildcard characters are permitted in the CmdletName and ParameterName values. -The value of $PSDefaultParameterValues is a System.Management.Automation.DefaultParameterDictionary, a type of hash table that validates the format of keys. Enter a hash table where the key consists of the cmdlet name and parameter name separated by a colon (:) and the value is the custom default value. - -To set, change, add, or remove entries from $PSDefaultParameterValues, use the methods that you would use to edit a standard hash table. +The value of \$PSDefaultParameterValues is a +System.Management.Automation.DefaultParameterDictionary, a type of hash table +that validates the format of keys. Enter a hash table where the key consists +of the cmdlet name and parameter name separated by a colon (:) and the value +is the custom default value. -The must be the name of a cmdlet or the name of an advanced function that uses the CmdletBinding attribute. You cannot use $PSDefaultParameterValues to specify default values for scripts or simple functions. +To set, change, add, or remove entries from \$PSDefaultParameterValues, use the +methods that you would use to edit a standard hash table. -The default value can be an object or a script block. If the value is a script block, Windows PowerShell evaluates the script block and uses the result as the parameter value. When the specified parameter takes a script block value, enclose the script block value in a second set of braces, such as: +The \ must be the name of a cmdlet or the name of an advanced +function that uses the CmdletBinding attribute. You cannot use +$PSDefaultParameterValues to specify default values for scripts or simple +functions. +The default value can be an object or a script block. If the value is a script +block, PowerShell evaluates the script block and uses the result as the +parameter value. When the specified parameter takes a script block value, +enclose the script block value in a second set of braces, such as: -``` +```powershell $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } ``` +For information about hash tables, see +[about_Hash_Tables](about_Hash_Tables.md). For information about script +blocks, see [about_Script_Blocks](about_Script_Blocks.md). For information +about preference variables, see +[about_Preference_Variables](about_Preference_Variables.md). -For information about hash tables, see about_Hash_Tables. For information about script blocks, see about_Script_Blocks. For information about preference variables, see about_Preference_Variables. - +## EXAMPLES -### EXAMPLES -The following command sets a custom default value for the SmtpServer parameter of the Send-MailMessage cmdlet. +The following command sets a custom default value for the SmtpServer parameter +of the Send-MailMessage cmdlet. - -``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"} +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" +} ``` +To set default values for multiple parameters, use a semi-colon (;) to +separate each Name\=Value pair. The following command adds a custom default +value for the LogName parameter of the `Get-WinEvent` cmdlet. -To set default values for multiple parameters, use a semi-colon (;) to separate each Name\=Value pair. The following command adds a custom default value for the LogName parameter of the Get-WinEvent cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5"; + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" +} ``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"} -``` - -You can use wildcard characters in the name of the cmdlet and parameter. The following command sets the Verbose common parameter to $true in all commands. Use $true and $false to set values for switch parameters, such as Verbose. +You can use wildcard characters in the name of the cmdlet and parameter. The +following command sets the Verbose common parameter to \$true in all commands. +Use \$true and \$false to set values for switch parameters, such as +**Verbose**. - -``` +```powershell $PSDefaultParameterValues = @{"*:Verbose"=$true} ``` +If a parameter takes multiple values (an array), you can set multiple values +as the default value. The following command sets the default value of the +**ComputerName** parameter of the Invoke-Command cmdlet to "Server01" and +"Server02". -If a parameter takes multiple values (an array), you can set multiple values as the default value. The following command sets the default value of the ComputerName parameter of the Invoke-Command cmdlet to "Server01" and "Server02". - - -``` -$PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"} -``` - - -You can use a script block to specify different default values for a parameter under different conditions. Windows PowerShell evaluates the script block and uses the result as the default parameter value. - -The following command sets the default value of the Autosize parameter of the Format-Table cmdlet to $true when the host program is the Windows PowerShell console. - - -``` -$PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}}} -``` - - -If a parameter takes a script block value, enclose the script block in an extra set of braces. When Windows PowerShell evaluates the outer script block, the result is the inner script block, which is set as the default parameter value. - -The following command sets the default value of the ScriptBlock parameter of Invoke-Command. Because the script block is enclosed in a second set of braces, the enclosed script block is passed to the Invoke-Command cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Invoke-Command:ComputerName"="Server01","Server02" +} ``` -$PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}} -``` - - - -### HOW TO SET $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. - -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues +You can use a script block to specify different default values for a parameter +under different conditions. PowerShell evaluates the script block and uses the +result as the default parameter value. -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. +The following command sets the default value of the Autosize parameter of the +Format-Table cmdlet to \$true when the host program is the PowerShell console. - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +$PSDefaultParameterValues=@{ + "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}} +} ``` +If a parameter takes a script block value, enclose the script block in an +extra set of braces. When PowerShell evaluates the outer script block, the +result is the inner script block, which is set as the default parameter value. +The following command sets the default value of the ScriptBlock parameter of +`Invoke-Command`. Because the script block is enclosed in a second set of +braces, the enclosed script block is passed to the `Invoke-Command` cmdlet. -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational -Get*:Verbose True +```powershell +$PSDefaultParameterValues=@{ + "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} +} ``` +### HOW TO SET \$PSDefaultParameterValues -To get the value of a key, use the following command syntax: +\$PSDefaultParameterValues is a preference variable, so it exists only in the +session in which it is set. It has no default value. +To set \$PSDefaultParameterValues, type the variable name and one or more +key-value pairs at the command line. -``` -$PSDefaultParameterValues[""] -``` +If you type another \$PSDefaultParameterValues command, its value replaces the +original value. The original is not retained. +To save \$PSDefaultParameterValues for future sessions, add a +\$PSDefaultParameterValues command to your PowerShell profile. For more +information, see [about_Profiles](about_Profiles.md). -For example: +### HOW TO GET \$PSDefaultParameterValues +To get the value of \$PSDefaultParameterValues, at the command prompt, type: +```powershell +$PSDefaultParameterValues ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] -Server01AB234x5 -``` - - - -### HOW TO ADD VALUES TO $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. +For example, the first command sets the value of \$PSDefaultParameterValues. +The second command gets the value of \$PSDefaultParameterValues. -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues - -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. - - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +PS C:\> $PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + "Get-*:Verbose"=$true +} ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To get the value of a \ key, use the following +command syntax: -To get the value of a key, use the following command syntax: - - -``` +```powershell $PSDefaultParameterValues[""] ``` - For example: - -``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] Server01AB234x5 ``` +### HOW TO ADD VALUES TO PSDefaultParameterValues +To add or remove values from \$PSDefaultParameterValues, use the methods that +you would use for a standard hash table. -### HOW TO ADD VALUES TO $PSDefaultParameterValues -To add or remove values from $PSDefaultParameterValues, use the methods that you would use for a standard hash table. - -For example, to add a value to $PSDefaultParameterValues without affecting the existing values, use the Add method of hash tables. +For example, to add a value to \$PSDefaultParameterValues without affecting the +existing values, use the Add method of hash tables. The syntax of the Add method is as follows: - ``` .Add(Key, Value) ``` +where the Key is ":" and the value is the parameter +value. -where the Key is ":" and the value is the parameter value. - -Use the following command format to call the Add method on $PSDefaultParameterValues. Be sure to use a comma (,) to separate the key from the value, instead of the equal sign (\=). - +Use the following command format to call the Add method on +\$PSDefaultParameterValues. Be sure to use a comma (,) to separate the key +from the value, instead of the equal sign (\=). +```powershell +$PSDefaultParameterValues.Add( + ":", "" +) ``` -$PSDefaultParameterValues.Add(":", "") -``` - -For example, the following command adds "PowerShell" as the default value of the Name parameter of the Get-Process cmdlet. +For example, the following command adds "PowerShell" as the default value of +the Name parameter of the Get-Process cmdlet. - -``` +```powershell $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO REMOVE VALUES FROM \$PSDefaultParameterValues - -### HOW TO REMOVE VALUES FROM $PSDefaultParameterValues -To remove a value from $PSDefaultParameterValues, use the Remove method of hash tables. +To remove a value from \$PSDefaultParameterValues, use the Remove method of +hash tables. The syntax of the Remove method is as follows: - -``` +```powershell .Remove(Key) ``` +Use the following command format to call the Remove method on +\$PSDefaultParameterValues. -Use the following command format to call the Remove method on $PSDefaultParameterValues. - - -``` +```powershell $PSDefaultParameterValues.Remove(":") ``` +For example, the following command removes the Name parameter of the +`Get-Process` cmdlet and its values. -For example, the following command removes the Name parameter of the Get-Process cmdlet and its values. - - -``` +```powershell $PSDefaultParameterValues.Remove("Get-Process:Name") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO CHANGE VALUES IN \$PSDefaultParameterValues +To change a value in $PSDefaultParameterValues, use the following command +format. -### HOW TO CHANGE VALUES IN $PSDefaultParameterValues -To change a value in $PSDefaultParameterValues, use the following command format. - - -``` +```powershell $PSDefaultParameterValues["CmdletName:ParameterName"]="" ``` - The following example shows the effect of this command. +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - +```powershell +$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" -``` - +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO DISABLE AND RE-ENABLE \$PSDefaultParameterValues +You can temporarily disable and then re-enable \$PSDefaultParameterValues. This +is very useful if you're running scripts that might assume different default +parameter values. -### HOW TO DISABLE AND RE-ENABLE $PSDefaultParameterValues -You can temporarily disable and then re-enable $PSDefaultParameterValues. This is very useful if you're running scripts that might assume different default parameter values. - -To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of $True. +To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of +\$True. For example, - -``` +```powershell $PSDefaultParameterValues.Add("Disabled", $true) ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$true ``` +The other values in \$PSDefaultParameterValues are preserved, but not +effective. -The other values in $PSDefaultParameterValues are preserved, but not effective. - +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Disabled True -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Disabled True +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To re-enable \$PSDefaultParameterValues, remove the Disabled key or change the +value of the Disabled key to \$False. -To re-enable $PSDefaultParameterValues, remove the Disabled key or change the value of the Disabled key to $False. - - -``` +```powershell $PSDefaultParameterValues.Remove("Disabled") ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$false ``` - -The previous value of $PSDefaultParameterValues is effective again. - +The previous value of \$PSDefaultParameterValues is effective again. ## KEYWORDS + about_PSDefaultParameterValues about_Parameters_DefaultValues about_DefaultValues - ## SEE ALSO [about_Hash_Tables](about_Hash_Tables.md) @@ -459,4 +419,3 @@ about_DefaultValues [about_Profiles](about_Profiles.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 886b4ed1dfc9..906dc159fb8a 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-05 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -248,7 +248,7 @@ debug message is not displayed and processing continues. The final command uses the Debug parameter to override the preference for a single command. ```powershell -PS> $debugpreference # Get the current value of \$DebugPreference +PS> $debugpreference # Get the current value of $DebugPreference SilentlyContinue PS> write-debug "Hello, World" @@ -301,7 +301,7 @@ uses the Debug parameter with a value of \$false to suppress the message for a single command. ```powershell -PS> \$debugpreference = "Inquire" +PS> $debugpreference = "Inquire" PS> write-debug "Hello, World" DEBUG: Hello, World @@ -375,7 +375,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value of the preference. -PS> \$ErrorActionPreference = "SilentlyContinue" +PS> $ErrorActionPreference = "SilentlyContinue" PS> # Generate an error message. PS> write-error "Hello, World" @@ -393,14 +393,14 @@ a non-existent file, nofile.txt. The example also uses the ErrorAction common parameter to override the preference. ```powershell -PS> \$erroractionpreference +PS> $erroractionpreference SilentlyContinue # Display the value of the preference. PS> get-childitem -path nofile.txt PS> # Error message is suppressed. PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> get-childitem -path nofile.txt Get-ChildItem : Cannot find path 'C:\nofile.txt' because it does not exist. @@ -412,7 +412,7 @@ PS> get-childitem -path nofile.txt -erroraction SilentlyContinue PS> # Error message is suppressed. PS> # Change the value to Inquire. -PS> \$ErrorActionPreference = "Inquire" +PS> $ErrorActionPreference = "Inquire" PS> get-childitem -path nofile.txt Confirm @@ -425,7 +425,7 @@ At line:1 char:4 + get-childitem <<<< nofile.txt PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> Get-Childitem nofile.txt -erroraction "Inquire" PS> # Use the ErrorAction parameter to override the preference value. @@ -462,7 +462,7 @@ NormalView. In this case, the Get-ChildItem command is used to find a non-existent file. ```powershell -PS> \$ErrorView # Verify the value. +PS> $ErrorView # Verify the value. NormalView PS> get-childitem nofile.txt # Find a non-existent file. @@ -475,7 +475,7 @@ This example shows how the same error appears when the value of \$ErrorView is CategoryView. ```powershell -PS> \$ErrorView = "CategoryView" # Change the value to +PS> $ErrorView = "CategoryView" # Change the value to CategoryView PS> get-childitem nofile.txt @@ -493,7 +493,7 @@ error in the error array (element 0) and formats all of the properties of the error object in a list. ```powershell -PS> \$error[0] | format-list -property * -force +PS> $error[0] | format-list -property * -force Exception : System.Management.Automation.ItemNotFoundException: Cannot find path 'C:\nofile.txt' because it does not exist. @@ -546,10 +546,10 @@ In the resulting display, the list in the Group column is now limited by the line length. In the final command in the example, use the Wrap parameter of Format-Table to display all of the processes in each Status group. -PS> \$formatenumerationlimit # Find the current value +```powershell +PS> $formatenumerationlimit # Find the current value 4 -```powershell PS> # List all services grouped by status PS> get-service | group-object -property status @@ -560,7 +560,7 @@ Count Name Group PS> # The list is truncated after 4 items. PS> # Increase the limit to 1000. -PS> \$formatenumerationlimit = 1000 +PS> $formatenumerationlimit = 1000 PS> get-service | group-object -property status Count Name Group @@ -650,20 +650,20 @@ The Log*Event preference variables are as follows: To enable a Log*Event, type the variable with a value of \$true, for example: ```powershell -\$LogCommandLifeCycleEvent +$LogCommandLifeCycleEvent ``` - or - ```powershell -\$LogCommandLifeCycleEvent = \$true +$LogCommandLifeCycleEvent = $true ``` To disable an event type, type the variable with a value of \$false, for example: ```powershell -\$LogCommandLifeCycleEvent = \$false +$LogCommandLifeCycleEvent = $false ``` The events that you enable are effective only for the current PowerShell @@ -719,26 +719,26 @@ To count the errors on your system, use the Count property of the \$Error array. Type: ```powershell -\$Error.count +$Error.count ``` To display a specific error, use array notation to display the error. For example, to see the most recent error, type: ```powershell -\$Error[0] +$Error[0] ``` To display the oldest retained error, type: ```powershell -\$Error[(\$Error.Count -1] +$Error[($Error.Count -1] ``` To display the properties of the ErrorRecord object, type: ```powershell -\$Error[0] | format-list -property * -force +$Error[0] | format-list -property * -force ``` In this command, the Force parameter overrides the special formatting of @@ -748,11 +748,11 @@ To delete all errors from the error history, use the Clear method of the error array. ```powershell -PS> \$Error.count +PS> $Error.count 17 -PS> \$Error.clear() +PS> $Error.clear() PS> -PS> \$Error.count +PS> $Error.count 0 ``` @@ -844,9 +844,9 @@ is converted to a string. In this case, an array of integers is stored in a variable and then the variable is cast as a string. ```powershell -PS> \$array = 1,2,3 # Store an array of integers. +PS> $array = 1,2,3 # Store an array of integers. -PS> [string]\$array # Cast the array to a string. +PS> [string]$array # Cast the array to a string. 1 2 3 # Spaces separate the elements ``` @@ -854,9 +854,9 @@ To change the separator, add the \$OFS variable by assigning a value to it. To work correctly, the variable must be named \$OFS. ```powershell -PS> \$OFS = "+" # Create \$OFS and assign a "+" +PS> $OFS = "+" # Create $OFS and assign a "+" -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1+2+3 # Plus signs separate the elements ``` @@ -865,10 +865,10 @@ To restore the default behavior, you can assign a space (" ") to the value of verifies that the separator is a space. ```powershell -PS> Remove-Variable OFS # Delete \$OFS +PS> Remove-Variable OFS # Delete $OFS PS> -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1 2 3 # Spaces separate the elements ``` @@ -897,7 +897,7 @@ The first command finds the value of \$OutputEncoding. Because the value is an encoding object, display only its EncodingName property. ```powershell -PS> \$OutputEncoding.EncodingName # Find the current value US-ASCII +PS> $OutputEncoding.EncodingName # Find the current value US-ASCII ``` In this example, a FINDSTR command is used to search for two Chinese @@ -918,9 +918,9 @@ locale selected for Windows. Because OutputEncoding is a static property of the console, use double-colons (::) in the command. ```powershell -PS> \$OutputEncoding = [console]::outputencoding +PS> $OutputEncoding = [console]::outputencoding PS> # Set the value equal to the OutputEncoding property of the console. -PS> \$OutputEncoding.EncodingName +PS> $OutputEncoding.EncodingName OEM United States ``` As a result of this change, the FINDSTR command finds the characters. @@ -1100,7 +1100,7 @@ values you prefer. Save the output in a variable called \$PSSessionOption. For example, ```powershell -\$PSSessionOption = New-PSSessionOption -NoCompression +$PSSessionOption = New-PSSessionOption -NoCompression ``` To use the \$PSSessionOption preference variable in every PowerShell session, @@ -1202,7 +1202,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$VerbosePreference = "Inquire" +PS> $VerbosePreference = "Inquire" PS> Write-Verbose "Verbose message test." VERBOSE: Verbose message test. Confirm @@ -1249,7 +1249,7 @@ value. This example shows the effect of the Continue value, which is the default. ```powershell -PS> \$WarningPreference # Find the current value. +PS> $WarningPreference # Find the current value. Continue PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1263,7 +1263,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value to SilentlyContinue. -PS> \$WarningPreference = "SilentlyContinue" +PS> $WarningPreference = "SilentlyContinue" PS> Write-Warning "This action can delete data." PS> # Write a warning message. @@ -1280,7 +1280,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$WarningPreference = "Inquire" +PS> $WarningPreference = "Inquire" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1299,7 +1299,7 @@ This example shows the effect of the Stop value. ```powershell PS> # Change the value to Stop. -PS> \$WarningPreference = "Stop" +PS> $WarningPreference = "Stop" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1360,7 +1360,7 @@ This example shows the effect of the 0 (not enabled) value, which is the default. ```powershell -PS> \$whatifpreference +PS> $whatifpreference 0 # Check the current value. PS> # Verify that the file exists. @@ -1400,8 +1400,8 @@ Remove-Item to delete a cmdlet, Remove-Item displays the path to the file that it would delete, but it does not delete the file. ```powershell -PS> \$whatifpreference = 1 -PS> \$whatifpreference +PS> $whatifpreference = 1 +PS> $whatifpreference 1 # Change the value. PS> # Try to delete a file. @@ -1417,8 +1417,8 @@ This example shows how to delete a file when the value of \$WhatIfPreference is 1. It uses the WhatIf parameter with a value of \$false. ```powershell -PS> # Use the WhatIf parameter with \$false. -PS> remove-item test.txt -whatif:\$false +PS> # Use the WhatIf parameter with $false. +PS> remove-item test.txt -whatif:$false ``` This example demonstrates that some cmdlets support WhatIf behavior and others @@ -1430,7 +1430,7 @@ a value of \$false. ```powershell PS> # Change the value to 1. -PS> \$whatifpreference = 1 +PS> $whatifpreference = 1 PS> get-process winword A Get-Process command completes. @@ -1443,8 +1443,8 @@ PS> # A Stop-Process command uses WhatIf. PS> stop-process -name winword What if: Performing operation "Stop-Process" on Target "WINWORD (2312)". -PS> stop-process -name winword -whatif:\$false -PS> # WhatIf:\$false overrides the preference. +PS> stop-process -name winword -whatif:$false +PS> # WhatIf:$false overrides the preference. PS> # Verify that the process is stopped. PS> get-process winword diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Prompts.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Prompts.md index 52e5fba3fc21..6f1820bea646 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Prompts.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Prompts.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,308 +7,284 @@ title: about_Prompts --- # About Prompts -## about_Prompts - ## SHORT DESCRIPTION -Describes the Prompt function and demonstrates how to create a custom Prompt function. +Describes the Prompt function and demonstrates how to create a custom Prompt +function. ## LONG DESCRIPTION -The Windows PowerShell® command prompt indicates that Windows PowerShell is ready to run a command: +The PowerShell command prompt indicates that PowerShell is ready to run a +command: ``` PS C:\> ``` +The PowerShell prompt is determined by the built-in Prompt function. You can +customize the prompt by creating your own Prompt function and saving it in +your PowerShell profile. -The Windows PowerShell prompt is determined by the built-in Prompt function. You can customize the prompt by creating your own Prompt function and saving it in your Windows PowerShell profile. - +## ABOUT THE PROMPT FUNCTION -### ABOUT THE PROMPT FUNCTION -The Prompt function determines the appearance of the Windows PowerShell prompt. Windows PowerShell comes with a built-in Prompt function, but you can override it by defining your own Prompt function. +The Prompt function determines the appearance of the PowerShell prompt. +PowerShell comes with a built-in Prompt function, but you can override it by +defining your own Prompt function. The Prompt function has the following syntax: - -``` +```powershell function Prompt { } ``` +The Prompt function must return an object. As a best practice, return a string +or an object that is formatted as a string. The maximum recommended length is +80 characters. -The Prompt function must return an object. As a best practice, return a string or an object that is formatted as a string. The maximum recommended length is 80 characters. - -For example, the following prompt function returns a "Hello, World" string followed by a caret (>). +For example, the following prompt function returns a "Hello, World" string +followed by a caret (>). - -``` -PS C:\> function prompt {"Hello, World > "} +```powershell +PS C:\> function prompt {"Hello, World > "} Hello, World > ``` - - ### GETTING THE PROMPT FUNCTION -To get the Prompt function, use the Get-Command cmdlet or use the Get-Item cmdlet in the Function drive. -Functions are commands. So, you can use the Get-Command cmdlet to get functions, including the Prompt function. +To get the Prompt function, use the `Get-Command` cmdlet or use the `Get-Item` +cmdlet in the Function drive. For example: +```powershell +PS C:\> Get-Command Prompt -``` -PS C:\> Get-Command Prompt - -CommandType Name ModuleName ------------ ---- ---------- +CommandType Name ModuleName +----------- ---- ---------- Function prompt ``` - -To get the script that sets the value of the prompt, use the dot method to get the ScriptBlock property of the Prompt function. +To get the script that sets the value of the prompt, use the dot method to get +the ScriptBlock property of the Prompt function. For example: +```powershell +PS C:\> (Get-Command Prompt).ScriptBlock -``` -PS C:\> (Get-Command Prompt).ScriptBlock - -"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -# .Link -# http://go.microsoft.com/fwlink/?LinkID=225750 +"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPr +omptLevel + 1)) " +# .Link +# http://go.microsoft.com/fwlink/?LinkID=225750 # .ExternalHelp System.Management.Automation.dll-help.xml ``` +Like all functions, the Prompt function is stored in the Function: drive. To +display the script that creates the current Prompt function, type: -Like all functions, the Prompt function is stored in the Function: drive. To display the script that creates the current Prompt function, type: - - -``` +```powershell (Get-Item function:prompt).ScriptBlock ``` - ### THE DEFAULT PROMPT -The default prompt appears only when the Prompt function generates an error or does not return an object. -The default Windows PowerShell prompt is: +The default prompt appears only when the Prompt function generates an error or +does not return an object. +The default PowerShell prompt is: ``` PS> ``` +For example, the following command sets the Prompt function to $null, which is +invalid. As a result, the default prompt appears. -For example, the following command sets the Prompt function to $null, which is invalid. As a result, the default prompt appears. - - -``` -PS C:\> function prompt {$null} +```powershell +PS C:\> function prompt {$null} PS> ``` - -Because Windows PowerShell comes with a built-in prompt, you usually do not see the default prompt. - +Because PowerShell comes with a built-in prompt, you usually do not see the +default prompt. ### BUILT-IN PROMPT -Windows PowerShell includes a built-in prompt function. - -In Windows PowerShell 3.0, the built-in prompt function is: - - -``` -function prompt -{ - "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -} -``` - -This simplified prompt starts with "PS" followed by the current location, and one ">" for each nested prompt level. +PowerShell includes a built-in prompt function. -In Windows PowerShell 2.0, the built-in prompt function is: - - -``` -function prompt -{ - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - else { '' }) + 'PS ' + $(Get-Location) ` - + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +```powershell +function prompt { + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + else { '' }) + 'PS ' + $(Get-Location) ` + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +The function uses the Test-Path cmdlet to determine whether the +\$PSDebugContext automatic variable is populated. If \$PSDebugContext is +populated, you are in debugging mode, and "[DBG]" is added to the prompt, as +follows: -The function uses the Test-Path cmdlet to determine whether the $PSDebugContext automatic variable is populated. If $PSDebugContext is populated, you are in debugging mode, and "[DBG]" is added to the prompt, as follows: - - -``` +```Output [DBG] PS C:\ps-test> ``` +If \$PSDebugContext is not populated, the function adds "PS" to the prompt. +And, the function uses the `Get-Location` cmdlet to get the current file +system directory location. Then, it adds a right angle bracket (>). -If $PSDebugContext is not populated, the function adds "PS" to the prompt. And, the function uses the Get-Location cmdlet to get the current file system directory location. Then, it adds a right angle bracket (>). - +For example: -``` -For example: - PS C:\ps-test> +```Output +PS C:\ps-test> ``` +If you are in a nested prompt, the function adds two angle brackets (>>) to +the prompt. (You are in a nested prompt if the value of the +\$NestedPromptLevel automatic variable is greater than 1.) -If you are in a nested prompt, the function adds two angle brackets (>>) to the prompt. (You are in a nested prompt if the value of the $NestedPromptLevel automatic variable is greater than 1.) +For example, when you are debugging in a nested prompt, the prompt resembles +the following prompt: -For example, when you are debugging in a nested prompt, the prompt resembles the following prompt: - - -``` +```Output [DBG] PS C:\ps-test>>> ``` - - ### CHANGES TO THE PROMPT -The Enter-PSSession cmdlet prepends the name of the remote computer to the current Prompt function. When you use the Enter-PSSession cmdlet to start a session with a remote computer, the command prompt changes to include the name of the remote computer. For example: +The Enter-PSSession cmdlet prepends the name of the remote computer to the +current Prompt function. When you use the Enter-PSSession cmdlet to start a +session with a remote computer, the command prompt changes to include the name +of the remote computer. For example: -``` -PS Hello, World> Enter-PSSession Server01 +```Output +PS Hello, World> Enter-PSSession Server01 [Server01]: PS Hello, World> ``` +Other PowerShell host applications and alternate shells might have their own +custom command prompts. -Other Windows PowerShell host applications and alternate shells might have their own custom command prompts. - -For more information about the $PSDebugContext and $NestedPromptLevel automatic variables, see about_Automatic_Variables. - +For more information about the \$PSDebugContext and $NestedPromptLevel +automatic variables, see [about_Automatic_Variables](about_Automatic_Variables.md). ### HOW TO CUSTOMIZE THE PROMPT -To customize the prompt, write a new Prompt function. The function is not protected, so you can overwrite it. -To write a prompt function, type the following: +To customize the prompt, write a new Prompt function. The function is not +protected, so you can overwrite it. +To write a prompt function, type the following: -``` +```powershell function prompt { } ``` - -Then, between the braces, enter the commands or the string that creates your prompt. +Then, between the braces, enter the commands or the string that creates your +prompt. For example, the following prompt includes your computer name: - -``` +```powershell function prompt {"PS [$env:COMPUTERNAME]> "} ``` - On the Server01 computer, the prompt resembles the following prompt: - -``` +```Output PS [Server01] > ``` - The following prompt function includes the current date and time: - -``` +```powershell function prompt {"$(get-date)> "} ``` - The prompt resembles the following prompt: - -``` +```Output 03/15/2012 17:49:47> ``` - You can also change the default Prompt function: -For example, the following modified Prompt function adds "[ADMIN]:" to the built-in Windows PowerShell prompt when Windows PowerShell is opened by using the "Run as administrator" option: - - -``` -function prompt -{ - $identity = [Security.Principal.WindowsIdentity]::GetCurrent() - $principal = [Security.Principal.WindowsPrincipal] $identity - - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - - elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) - { "[ADMIN]: " } - - else { '' }) + 'PS ' + $(Get-Location) + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +For example, the following modified Prompt function adds "[ADMIN]:" to the +built-in PowerShell prompt when PowerShell is opened by using the "Run as +administrator" option: + +```powershell +function prompt { + $identity = [Security.Principal.WindowsIdentity]::GetCurrent() + $principal = [Security.Principal.WindowsPrincipal] $identity + + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] + "Administrator")) { "[ADMIN]: " } + else { '' } + ) + 'PS ' + $(Get-Location) + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +When you start PowerShell by using the "Run as administrator" option, a prompt +that resembles the following prompt appears: -When you start Windows PowerShell by using the "Run as administrator" option, a prompt that resembles the following prompt appears: - - -``` +```Output [ADMIN]: PS C:\ps-test> ``` +The following Prompt function displays the history ID of the next command. To +view the command history, use the `Get-History` cmdlet. -The following Prompt function displays the history ID of the next command. To view the command history, use the Get-History cmdlet. - +```powershell +function prompt { + # The at sign creates an array in case only one history item exists. + $history = @(get-history) + if($history.Count -gt 0) + { + $lastItem = $history[$history.Count - 1] + $lastId = $lastItem.Id + } -``` -function prompt -{ - # The at sign creates an array in case only one history item exists. - $history = @(get-history) - if($history.Count -gt 0) - { - $lastItem = $history[$history.Count - 1] - $lastId = $lastItem.Id - } - - $nextCommand = $lastId + 1 - $currentDirectory = get-location - "PS: $nextCommand $currentDirectory >" + $nextCommand = $lastId + 1 + $currentDirectory = get-location + "PS: $nextCommand $currentDirectory >" } ``` +The following prompt uses the Write-Host and Get-Random cmdlets to create a +prompt that changes color randomly. Because `Write-Host` writes to the current +host application but does not return an object, this function includes a +Return statement. Without it, PowerShell uses the default prompt, "PS>". -The following prompt uses the Write-Host and Get-Random cmdlets to create a prompt that changes color randomly. Because Write-Host writes to the current host application but does not return an object, this function includes a Return statement. Without it, Windows PowerShell uses the default prompt, "PS>". - - -``` -function prompt -{ - $color = Get-Random -Min 1 -Max 16 - Write-Host ("PS " + $(Get-Location) +">") -NoNewLine -ForegroundColor $Color - return " " +```powershell +function prompt { + $color = Get-Random -Min 1 -Max 16 + Write-Host ("PS " + $(Get-Location) +">") -NoNewLine ` + -ForegroundColor $Color + return " " } ``` - - ### SAVING THE PROMPT FUNCTION -Like any function, the Prompt function exists only in the current session. To save the Prompt function for future sessions, add it to your Windows PowerShell profiles. For more information about profiles, see about_Profiles. +Like any function, the Prompt function exists only in the current session. To +save the Prompt function for future sessions, add it to your PowerShell +profiles. For more information about profiles, see about_Profiles. ## SEE ALSO -Get-Location +[Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) -Enter-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Get-History +[Get-History](../Get-History.md) -Get-Random +[Get-Random](../../Microsoft.PowerShell.Utility/Get-Random.md) -Write-Host +[Write-Host](../../Microsoft.PowerShell.Utility/Write-Host.md) [about_Profiles](about_Profiles.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md deleted file mode 100644 index af9999f5f30a..000000000000 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_packagemanagement ---- - -# About PackageManagement -## about_PackageManagement -# TOPIC - -about_PackageManagement - -# SHORT DESCRIPTION - -PackageManagement is an aggregator for software package managers. - -# LONG DESCRIPTION - -PackageManagement functionality was introduced in Windows PowerShell 5.0. - -PackageManagement is a unified interface for software package management systems; you -can run PackageManagement cmdlets to perform software discovery, installation, and -inventory (SDII) tasks. Regardless of the underlying installation technology, -you can run the common cmdlets in the PackageManagement module to search for, -install, or uninstall packages; add, remove, and query package repositories; and -run queries on a computer to determine which software packages are installed. - -PackageManagement supports a flexible plug-in model that enables support for other -software package management systems. - -The PackageManagement module is included with Windows PowerShell 5.0 and later releases -of Windows PowerShell, and works on three levels of package management -structure: package providers, package sources, and the packages themselves. - -Term Description ----------- ------------------------------ -Package manager Software package management system. In -PackageManagement terms, this is a package provider. -Package provider PackageManagement term for a package manager. Examples -can include Windows Installer, Chocolatey, -and others. -Package source A URL, local folder, or network shared folder that -you configure package providers to use as a -repository. -Package A piece of software that a package provider manages, -and that is stored in a specific package source. - -The PackageManagement module includes the following cmdlets. You can find the -Help for these cmdlets on TechNet starting on the following page: -http://technet.microsoft.com/library/dn890951(v=wps.640).aspx. - -Cmdlet Description ----------- ------------------------------ -Get-PackageProvider Returns a list of package providers that are -connected to PackageManagement. -Get-PackageSource Gets a list of package sources that are -registered for a package provider. -Register-PackageSource Adds a package source for a specified -package provider. -Set-PackageSource Sets properties on an existing package -source. -Unregister-PackageSource Removes a registered package source. -Get-Package Returns a list of installed software -packages. -Find-Package Finds software packages in available -package sources. -Install-Package Installs one or more software packages. -Save-Package Saves packages to the local computer -without installing them. -Uninstall-Package Uninstalls one or more software packages. - -PackageManagement Package Provider Bootstrapping and Dynamic Cmdlet Parameters - -By default, PackageManagement ships with a core bootstrap provider. You can install -additional package providers as you need them by bootstrapping the providers; -that is, responding to a prompt to install the provider automatically, from a -web service. You can specify a package provider with any PackageManagement cmdlet; -if the specified provider is not available, PackageManagement prompts you to bootstrap ---or automatically install--the provider. In the following examples, if the -Chocolatey provider is not already installed, PackageManagement bootstrapping installs -the provider. - -Find-Package -Provider Chocolatey - -If the Chocolatey provider is not already installed, when you run the -preceding command, you are prompted to install it. - -Install-Package -ForceBootstrap - -If the Chocolatey provider is not already installed, when you run the -preceding command, the provider is installed; but because the ForceBootstrap -parameter has been added to the command, you are not prompted to install it; -both the provider and the package are installed automatically. - -When you try to install a package, if you do not already have the supporting -provider installed, and you do not add the ForceBootstrap parameter to your -command, PackageManagement prompts you to install the provider. - -Specifying a package provider in your PackageManagement command can make -dynamic parameters available that are specific to that package provider. -When you run Get-Help for a specific PackageManagement cmdlet, a list of -parameter sets are returned, grouping dynamic parameters for available -package providers in separate parameter sets. - -More Information About the PackageManagement Project - -For more information about the PackageManagement open development project, -including how to create a PackageManagement package provider, see the -PackageManagement project on GitHub at https://oneget.org. - -# SEE ALSO - -Get-PackageProvider - -Get-PackageSource - -Register-PackageSource - -Set-PackageSource - -Unregister-PackageSource - -Get-Package - -Find-Package - -Install-Package - -Save-Package - -Uninstall-Package - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_pipelines.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_pipelines.md index 1ae1a64986f8..97cd9535c505 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_pipelines.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_pipelines.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,41 +7,39 @@ title: about_pipelines --- # About Pipelines -## about_Pipelines - - ### Short Description -Combining commands into pipelines in the Windows PowerShell +Combining commands into pipelines in the PowerShell ### Long Description -A pipeline is a series of commands connected by pipeline operators -(`|`)(ASCII 124). Each pipeline operator sends the results of the preceding -command to the next command. +A pipeline is a series of commands connected by pipeline operators (`|`) +(ASCII 124). Each pipeline operator sends the results of the preceding command +to the next command. -You can use pipelines to send the objects that are output by one command -to be used as input to another command for processing. And you can send the -output of that command to yet another command. The result is a very powerful -command chain or "pipeline" that is comprised of a series of simple commands. +You can use pipelines to send the objects that are output by one command to be +used as input to another command for processing. And you can send the output +of that command to yet another command. The result is a very powerful command +chain or "pipeline" that is comprised of a series of simple commands. For example, + ```powershell Command-1 | Command-2 | Command-3 ``` In this example, the objects that `Command-1` emits are sent to `Command-2`. -`Command-2` processes the objects and sends them to `Command-3`. `Command-3` processes -the objects and send them down the pipeline. Because there are no more commands in -the pipeline, the results are displayed at the console. +`Command-2` processes the objects and sends them to `Command-3`. `Command-3` +processes the objects and send them down the pipeline. Because there are no +more commands in the pipeline, the results are displayed at the console. -In a pipeline, the commands are processed from left to right in the order -that they appear. The processing is handled as a single operation and -output is displayed as it is generated. +In a pipeline, the commands are processed from left to right in the order that +they appear. The processing is handled as a single operation and output is +displayed as it is generated. -Here is a simple example. The following command gets the Notepad process -and then stops it. +Here is a simple example. The following command gets the Notepad process and +then stops it. For example, ```powershell @@ -49,77 +47,69 @@ Get-Process notepad | Stop-Process ``` The first command uses the `Get-Process` cmdlet to get an object representing -the Notepad process. It uses a pipeline operator (`|`) to send the process object -to the `Stop-Process` cmdlet, which stops the Notepad process. Notice that the -`Stop-Process` command does not have a Name or ID parameter to specify the process, -because the specified process is submitted through the pipeline. +the Notepad process. It uses a pipeline operator (`|`) to send the process +object to the `Stop-Process` cmdlet, which stops the Notepad process. Notice +that the `Stop-Process` command does not have a Name or ID parameter to +specify the process, because the specified process is submitted through the +pipeline. Here is a practical example. This command pipeline gets the text files in the -current directory, selects only the files that are more than 10,000 bytes long, -sorts them by length, and displays the name and length of each file in a table. +current directory, selects only the files that are more than 10,000 bytes +long, sorts them by length, and displays the name and length of each file in a +table. ```powershell Get-ChildItem -Path *.txt | Where-Object {$_.length -gt 10000} | Sort-Object -Property length | Format-Table -Property name, length ``` -This pipeline is comprised of four commands in the specified order. The command -is written horizontally, but we will show the process vertically in the following -graphic. +This pipeline is comprised of four commands in the specified order. The +command is written horizontally, but we will show the process vertically in +the following graphic. `Get-ChildItem` `-Path` *.txt - **|** - -| (FileInfo objects ) -| ( .txt ) - - **|** - - **V** +``` +| +| (FileInfo objects for *.txt) +| +V +``` `Where-Object` {$_.length `-gt` 10000} - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| +V +``` `Sort-Object` `-Property` Length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| +V +``` `Format-Table` `-Property` name, length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) -| (Formatted in a table ) - - **|** - - **V** - ``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| ( Formatted in a table ) +| +V +``` + +```output Name Length ---- ------ tmp1.txt 82920 @@ -129,13 +119,13 @@ tmp3.txt 114000 ### Using Pipelines +The PowerShell cmdlets were designed to be used in pipelines. For example, you +can usually pipe the results of a Get cmdlet to an action cmdlet (such as a +Set, Start, Stop, or Rename cmdlet) for the same noun. -The Windows PowerShell cmdlets were designed to be used in pipelines. For example, -you can usually pipe the results of a Get cmdlet to an action cmdlet (such as a Set, -Start, Stop, or Rename cmdlet) for the same noun. - -For example, you can pipe any service from the `Get-Service` cmdlet to the `Start-Service` -or `Stop-Service` cmdlets (although disabled services cannot be restarted in this way). +For example, you can pipe any service from the `Get-Service` cmdlet to the +`Start-Service` or `Stop-Service` cmdlets (although disabled services cannot +be restarted in this way). This command pipeline starts the WMI service on the computer: @@ -144,90 +134,98 @@ For example, Get-Service wmi | Start-Service ``` -The cmdlets that get and set objects of the Windows PowerShell providers, such as the +The cmdlets that get and set objects of the PowerShell providers, such as the Item and ItemProperty cmdlets, are also designed to be used in pipelines. -For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` command in the -Windows PowerShell registry provider to the `New-ItemProperty` cmdlet. This command adds -a new registry entry, NoOfEmployees, with a value of 8124, to the MyCompany registry key. +For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` +command in the PowerShell registry provider to the `New-ItemProperty` cmdlet. +This command adds a new registry entry, NoOfEmployees, with a value of 8124, +to the MyCompany registry key. For example, ```powershell -Get-Item -Path HKLM:\Software\MyCompany | New-ItemProperty -Name NoOfEmployees -Value 8124 +Get-Item -Path HKLM:\Software\MyCompany | + New-ItemProperty -Name NoOfEmployees -Value 8124 ``` -Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, `Sort-Object`, `Group-Object`, -and `Measure-Object` are used almost exclusively in pipelines. You can pipe any objects to -these cmdlets. +Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, +`Sort-Object`, `Group-Object`, and `Measure-Object` are used almost +exclusively in pipelines. You can pipe any objects to these cmdlets. -For example, you can pipe all of the processes on the computer to the `Sort-Object` command -and have them sorted by the number of handles in the process. +For example, you can pipe all of the processes on the computer to the +`Sort-Object` command and have them sorted by the number of handles in the +process. For example, + ```powershell Get-Process | Sort-Object -Property handles ``` -Also, you can pipe any objects to the formatting cmdlets, such as `Format-List` and -`Format-Table`, the Export cmdlets, such as `Export-Clixml` and `Export-CSV`, and the Out -cmdlets, such as `Out-Printer`. +Also, you can pipe any objects to the formatting cmdlets, such as +`Format-List` and `Format-Table`, the Export cmdlets, such as `Export-Clixml` +and `Export-CSV`, and the Out cmdlets, such as `Out-Printer`. -For example, you can pipe the Winlogon process to the `Format-List` cmdlet to display all -of the properties of the process in a list. +For example, you can pipe the Winlogon process to the `Format-List` cmdlet to +display all of the properties of the process in a list. For example, + ```powershell Get-Process winlogon | Format-List -Property * ``` -With a bit of practice, you'll find that combining simple commands into pipelines -saves time and typing, and makes your scripting more efficient. +With a bit of practice, you'll find that combining simple commands into +pipelines saves time and typing, and makes your scripting more efficient. ### How Pipelines Work +When you "pipe" objects, that is send the objects in the output of one command +to another command, PowerShell tries to associate the piped objects with one +of the parameters of the receiving cmdlet. -When you "pipe" objects, that is send the objects in the output of one command to another -command, Windows PowerShell tries to associate the piped objects with one of the parameters -of the receiving cmdlet. - -To do so, the Windows PowerShell "parameter binding" component, which associates input objects -with cmdlet parameters, tries to find a parameter that meets the following criteria: +To do so, the PowerShell "parameter binding" component, which associates input +objects with cmdlet parameters, tries to find a parameter that meets the +following criteria: - The parameter must accept input from a pipeline (not all do) -- The parameter must accept the type of object being sent or a type that the object -can be converted to. +- The parameter must accept the type of object being sent or a type that the + object can be converted to. - The parameter must not already be used in the command. -For example, the `Start-Service` cmdlet has many parameters, but only two of them, `-Name` and `-InputObject` -accept pipeline input. The `-Name` parameter takes strings and the `-InputObject` parameter takes -service objects. Therefore, you can pipe strings and service objects (and objects with properties -that can be converted to string and service objects) to `Start-Service`. +For example, the `Start-Service` cmdlet has many parameters, but only two of +them, `-Name` and `-InputObject` accept pipeline input. The `-Name` parameter +takes strings and the `-InputObject` parameter takes service objects. +Therefore, you can pipe strings and service objects (and objects with +properties that can be converted to string and service objects) to +`Start-Service`. -If the parameter binding component of Windows PowerShell cannot associate the piped objects -with a parameter of the receiving cmdlet, the command fails and Windows PowerShell prompts you -for the missing parameter values. +If the parameter binding component of PowerShell cannot associate the piped +objects with a parameter of the receiving cmdlet, the command fails and +PowerShell prompts you for the missing parameter values. -You cannot force the parameter binding component to associate the piped objects with a particular -parameter -- you cannot even suggest a parameter. Instead, the logic of the component manages -the piping as efficiently as possible. +You cannot force the parameter binding component to associate the piped +objects with a particular parameter. You cannot even suggest a parameter. +Instead, the logic of the component manages the piping as efficiently as +possible. ### One-At-A-Time Processing +Piping objects to a command is much like using a parameter of the command to +submit the objects. -Piping objects to a command is much like using a parameter of the command to submit the -objects. - -For example, piping objects representing the services on the computer to a `Format-Table` command, -such as: +For example, piping objects representing the services on the computer to a +`Format-Table` command, such as: ```powershell Get-Service | Format-Table -Property name, dependentservices ``` -is much like saving the service objects in a variable and using the InputObject parameter -of `Format-Table` to submit the service object. +is much like saving the service objects in a variable and using the +InputObject parameter of `Format-Table` to submit the service object. For example, + ```powershell $services = Get-Service Format-Table -InputObject $services -Property name, dependentservices @@ -236,51 +234,58 @@ Format-Table -InputObject $services -Property name, dependentservices or imbedding the command in the parameter value For example, + ```powershell -Format-Table -InputObject (Get-Service wmi) -Property name, dependentservices +Format-Table -InputObject (Get-Service wmi) -Property name,dependentservices ``` -However, there is an important difference. When you pipe multiple objects to a command, -Windows PowerShell sends the objects to the command one at a time. When you use a -command parameter, the objects are sent as a single array object. +However, there is an important difference. When you pipe multiple objects to a +command, PowerShell sends the objects to the command one at a time. When you +use a command parameter, the objects are sent as a single array object. + +This seemingly technical difference can have interesting, and sometimes +useful, consequences. -This seemingly technical difference can have interesting, and sometimes useful, consequences. +For example, if you pipe multiple process objects from the `Get-Process` +cmdlet to the `Get-Member` cmdlet, PowerShell sends each process object, one +at a time, to `Get-Member`. `Get-Member` displays the .NET class (type) of the +process objects, and their properties and methods. -For example, if you pipe multiple process objects from the `Get-Process` cmdlet to the -`Get-Member` cmdlet, Windows PowerShell sends each process object, one at a time, to `Get-Member`. -`Get-Member` displays the .NET class (type) of the process objects, and their properties and methods. -(`Get-Member` eliminates duplicates, so if the objects are all of the same type, it displays only -one object type.) +NOTE: `Get-Member` eliminates duplicates, so if the objects are all of the +same type, it displays only one object type. -In this case, `Get-Member` displays the properties and methods of each process object, that is, a -System.Diagnostics.Process object. +In this case, `Get-Member` displays the properties and methods of each process +object, that is, a System.Diagnostics.Process object. For example, + ```powershell Get-Process | Get-Member ``` -``` +```Output TypeName: System.Diagnostics.Process -Name MemberType Definition ----- ---------- ---------- -Handles AliasProperty Handles = Handlecount -Name AliasProperty Name = ProcessName -NPM AliasProperty NPM = NonpagedSystemMemorySize +Name MemberType Definition +---- ---------- ---------- +Handles AliasProperty Handles = Handlecount +Name AliasProperty Name = ProcessName +NPM AliasProperty NPM = NonpagedSystemMemorySize ... ``` -However, if you use the InputObject parameter of `Get-Member`, then `Get-Member` receives an -array of System.Diagnostics.Process objects as a single unit, and it displays the properties -of an array of objects. (Note the array symbol ([]) after the System.Object type name.) +However, if you use the InputObject parameter of `Get-Member`, then +`Get-Member` receives an array of System.Diagnostics.Process objects as a +single unit, and it displays the properties of an array of objects. (Note the +array symbol ([]) after the System.Object type name.) For example, + ```powershell Get-Member -InputObject (Get-Process) ``` -``` +```Output TypeName: System.Object[] Name MemberType Definition @@ -291,30 +296,32 @@ Clone Method System.Object Clone() ... ``` -This result might not be what you intended, but after you understand it, you can use it. For -example, an array of process objects has a Count property that you can use to count the number -of processes on the computer. +This result might not be what you intended, but after you understand it, you +can use it. For example, an array of process objects has a Count property that +you can use to count the number of processes on the computer. For example, + ```powershell (Get-Process).count ``` -This distinction can be important, so remember that when you pipe objects to a cmdlet, they -are delivered one at a time. +This distinction can be important, so remember that when you pipe objects to a +cmdlet, they are delivered one at a time. ### Accepts Pipeline Input -In order to receive objects in a pipeline, the receiving cmdlet must have a parameter -that accepts pipeline input. You can use a `Get-Help` command with the **Full** or **Parameter** -parameters to determine which, if any, of a cmdlet's parameters accepts pipeline input. +In order to receive objects in a pipeline, the receiving cmdlet must have a +parameter that accepts pipeline input. You can use a `Get-Help` command with +the **Full** or **Parameter** parameters to determine which, if any, of a +cmdlet's parameters accepts pipeline input. -In the `Get-Help` default display, the "Accept pipeline input?" item appears in a table -of parameter attributes. This table is displayed only when you use the **Full** or **Parameter** -parameters of the `Get-Help` cmdlet. +In the `Get-Help` default display, the "Accept pipeline input?" item appears +in a table of parameter attributes. This table is displayed only when you use +the **Full** or **Parameter** parameters of the `Get-Help` cmdlet. -For example, to determine which of the parameters of the `Start-Service` cmdlet accepts -pipeline input, type: +For example, to determine which of the parameters of the `Start-Service` +cmdlet accepts pipeline input, type: ```powershell Get-Help Start-Service -Full @@ -326,108 +333,115 @@ or Get-Help Start-Service -Parameter * ``` -For example, the help for the `Start-Service` cmdlet shows that the **InputObject** and **Name** -parameters accept pipeline input ("true"). All other parameters have a value of "false" -in the "Accept pipeline input?" row. +For example, the help for the `Start-Service` cmdlet shows that the +**InputObject** and **Name** parameters accept pipeline input ("true"). All +other parameters have a value of "false" in the "Accept pipeline input?" row. ``` -InputObject - Specifies ServiceController objects representing the services to be started. - Enter a variable that contains the objects, or type a command or expression - that gets the objects. +Specifies ServiceController objects representing the services to be started. +Enter a variable that contains the objects, or type a command or expression +that gets the objects. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByValue) +Accept wildcard characters? false -Name - Specifies the service names for the service to be started. +Specifies the service names for the service to be started. - The parameter name is optional. You can use Name or its alias, ServiceName, - or you can omit the parameter name. +The parameter name is optional. You can use Name or its alias, ServiceName, +or you can omit the parameter name. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByPropertyName, ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByPropertyName, ByValue) +Accept wildcard characters? false ``` This means that you can send objects (PsObjects) through the pipeline to the -`Where-Object` cmdlet and Windows PowerShell will associate the object with the +`Where-Object` cmdlet and PowerShell will associate the object with the **InputObject** and **Name** parameters. ### Methods Of Accepting Pipeline Input - Cmdlets parameters can accept pipeline input in one of two different ways: - ByValue: Parameters that accept input "by value" can accept piped objects -that have the same .NET type as their parameter value or objects that can be -converted to that type. - -For example, the Name parameter of `Start-Service` accepts pipeline input -by value. It can accept string objects or objects that can be converted to -strings. + that have the same .NET type as their parameter value or objects that can be + converted to that type. -- ByPropertyName: Parameters that accept input "by property name" can accept piped -objects only when a property of the object has the same name as the parameter. + For example, the Name parameter of `Start-Service` accepts pipeline input by + value. It can accept string objects or objects that can be converted to + strings. -For example, the Name parameter of `Start-Service` can accept objects that have -a Name property. +- ByPropertyName: Parameters that accept input "by property name" can accept + piped objects only when a property of the object has the same name as the + parameter. -(To list the properties of an object, pipe it to `Get-Member`.) + For example, the Name parameter of `Start-Service` can accept objects that + have a Name property. To list the properties of an object, pipe it to + `Get-Member`. -Some parameters can accept objects by value or by property name. These parameters are -designed to take input from the pipeline easily. +Some parameters can accept objects by value or by property name. These +parameters are designed to take input from the pipeline easily. ### Investigating Pipeline Errors - -If a command fails because of a pipeline error, you can investigate the failure and -rewrite the command. +If a command fails because of a pipeline error, you can investigate the +failure and rewrite the command. For example, the following command tries to move a registry entry from one -registry key to another by using the `Get-Item` cmdlet to get the destination path and -then piping the path to the `Move-ItemProperty` cmdlet. +registry key to another by using the `Get-Item` cmdlet to get the destination +path and then piping the path to the `Move-ItemProperty` cmdlet. -Specifically, the command uses the `Get-Item` cmdlet to get the destination path. It uses -a pipeline operator to send the result to the `Move-ItemProperty` cmdlet. The `Move-ItemProperty` -command specifies the current path and name of the registry entry to be moved. +Specifically, the command uses the `Get-Item` cmdlet to get the destination +path. It uses a pipeline operator to send the result to the +`Move-ItemProperty` cmdlet. The `Move-ItemProperty` command specifies the +current path and name of the registry entry to be moved. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product ``` -``` -The command fails and Windows PowerShell displays the following error +The command fails and PowerShell displays the following error message: -Move-ItemProperty : The input object cannot be bound to any parameters for the -command either because the command does not take pipeline input or the input -and its properties do not match any of the parameters that take pipeline input. +```output +Move-ItemProperty : The input object cannot be bound to any parameters for +the command either because the command does not take pipeline input or the +input and its properties do not match any of the parameters that take +pipeline input. At line:1 char:23 -+ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name product ++ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name p ``` -To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding component of -Windows PowerShell. The following command traces the Parameter Binding component while the -command is processing. It uses the `-PSHost` parameter to display the results at the console -and the `-filepath` command to send them to the debug.txt file for later reference. +To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding +component of PowerShell. The following command traces the Parameter Binding +component while the command is processing. It uses the `-PSHost` parameter to +display the results at the console and the `-filepath` command to send them to +the debug.txt file for later reference. For example, + ```powershell -Trace-Command -Name parameterbinding -Expression {Get-Item -Path HKLM:\software\mycompany\sales | -Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} -PSHost -FilePath debug.txt +Trace-Command -Name parameterbinding -Expression { + Get-Item -Path HKLM:\software\mycompany\sales | + Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} ` + -PSHost -FilePath debug.txt ``` -The results of the trace are lengthy, but they show the values being bound to the `Get-Item` cmdlet -and then the named values being bound to the `Move-ItemProperty` cmdlet. +The results of the trace are lengthy, but they show the values being bound to +the `Get-Item` cmdlet and then the named values being bound to the +`Move-ItemProperty` cmdlet. +``` ... BIND NAMED cmd line args [`Move-ItemProperty`] @@ -442,31 +456,35 @@ BIND arg [product] to parameter [Name] BIND POSITIONAL cmd line args [`Move-ItemProperty`] ... +``` -Finally, it shows that the attempt to bind the path to the Destination parameter -of `Move-ItemProperty` failed. +Finally, it shows that the attempt to bind the path to the **Destination** +parameter of `Move-ItemProperty` failed. +``` ... BIND PIPELINE object to parameters: [`Move-ItemProperty`] PIPELINE object TYPE = [Microsoft.Win32.RegistryKey] RESTORING pipeline parameter's original values -Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION -Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION +Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO CO +ERCION +Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COE +RCION ... +``` - -To investigate the failure, use the `Get-Help` cmdlet to view the attributes of the -**Destination** parameter. The following command gets detailed information about the -**Destination** parameter. +To investigate the failure, use the `Get-Help` cmdlet to view the attributes +of the **Destination** parameter. The following command gets detailed +information about the **Destination** parameter. ```powershell Get-Help Move-ItemProperty -Parameter Destination ``` -The results show that **Destination** takes pipeline input only "by property name". -That is, the piped object must have a property named Destination. +The results show that **Destination** takes pipeline input only "by property +name". That is, the piped object must have a property named Destination. ``` -Destination @@ -479,11 +497,12 @@ That is, the piped object must have a property named Destination. Accept wildcard characters? false ``` -To see the properties of the object being piped to the `Move-ItemProperty` cmdlet, -pipe it to the `Get-Member` cmdlet. The following command pipes the results of the -first part of the command to the `Get-Member` cmdlet. +To see the properties of the object being piped to the `Move-ItemProperty` +cmdlet, pipe it to the `Get-Member` cmdlet. The following command pipes the +results of the first part of the command to the `Get-Member` cmdlet. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Get-Member ``` @@ -491,11 +510,13 @@ Get-Item -Path HKLM:\software\mycompany\sales | Get-Member The output shows that the item is a Microsoft.Win32.RegistryKey that does not have a Destination property. That explains why the command failed. -To fix the command, we must specify the destination in the `Move-ItemProperty` cmdlet. We can -use a `Get-ItemProperty` command to get the path, but the name and destination must be specified -in the `Move-ItemProperty` part of the command. +To fix the command, we must specify the destination in the `Move-ItemProperty` +cmdlet. We can use a `Get-ItemProperty` command to get the path, but the name +and destination must be specified in the `Move-ItemProperty` part of the +command. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\design | Move-ItemProperty -Dest HKLM:\software\mycompany\design -Name product @@ -510,9 +531,11 @@ Get-Itemproperty HKLM:\software\mycompany\sales The results show that the Product registry entry was moved to the Sales key. -``` -PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany\sales -PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany +```Output +PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany\sales +PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany PSChildName : sales PSDrive : HKLM PSProvider : Microsoft.PowerShell.Core\Registry @@ -528,4 +551,3 @@ Product : 18 [about_command_syntax](about_command_syntax.md) [about_foreach](about_foreach.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_profiles.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_profiles.md index b7eabd81d0ce..eea0dd9f0d50 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_profiles.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_profiles.md @@ -1,104 +1,99 @@ --- -ms.date: 2017-06-25 +ms.date: 2017-11-30 schema: 2.0.0 keywords: powershell,cmdlet title: about_Profiles --- # About Profiles -## about_Profiles +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Describes how to create and use a PowerShell profile. -Describes how to create and use a Windows PowerShell profile. +## LONG DESCRIPTION -# LONG DESCRIPTION +You can create a PowerShell profile to customize your environment and to add +session-specific elements to every PowerShell session that you start. -You can create a Windows PowerShell profile to customize your environment -and to add session-specific elements to every Windows PowerShell session -that you start. +A PowerShell profile is a script that runs when PowerShell starts. You can use +the profile as a logon script to customize the environment. You can add +commands, aliases, functions, variables, snap-ins, modules, and PowerShell +drives. You can also add other session-specific elements to your profile so +they are available in every session without having to import or re-create +them. -A Windows PowerShell profile is a script that runs when Windows PowerShell -starts. You can use the profile as a logon script to customize the -environment. You can add commands, aliases, functions, variables, snap-ins, -modules, and Windows PowerShell drives. You can also add other -session-specific elements to your profile so they are available in every -session without having to import or re-create them. +PowerShell supports several profiles for users and host programs. However, it +does not create the profiles for you. This topic describes the profiles, and +it describes how to create and maintain profiles on your computer. -Windows PowerShell supports several profiles for users and host programs. -However, it does not create the profiles for you. This topic describes the -profiles, and it describes how to create and maintain profiles on your -computer. +It explains how to use the **NoProfile** parameter of the PowerShell console +(PowerShell.exe) to start PowerShell without any profiles. And, it explains +the effect of the PowerShell execution policy on profiles. -It explains how to use the **NoProfile** parameter of the Windows PowerShell -console (PowerShell.exe) to start Windows PowerShell without any profiles. -And, it explains the effect of the Windows PowerShell execution policy on -profiles. +## THE PROFILE FILES -# THE PROFILE FILES +PowerShell supports several profile files. Also, PowerShell host programs can +support their own host-specific profiles. - -Windows PowerShell supports several profile files. Also, Windows PowerShell -host programs can support their own host-specific profiles. - -For example, the Windows PowerShell console supports the following basic +For example, the PowerShell console supports the following basic profile files. The profiles are listed in precedence order. The first profile has the highest precedence. -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Profile.ps1 | -| Current User, All Hosts | $Home\\[My ]Documents\Profile.ps1 | -| All Users, Current Host | $PsHome\Microsoft.PowerShell_profile.ps1 | -| All Users, All Hosts | $PsHome\Profile.ps1 | +|Description | Path | +|--------------------------|------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Profile.ps1 | +|Current User, All Hosts |$Home\\[My ]Documents\\Profile.ps1 | +|All Users, Current Host |$PsHome\Microsoft.PowerShell_profile.ps1 | +|All Users, All Hosts |$PsHome\Profile.ps1 | The profile paths include the following variables: - The `$PsHome` variable, which stores the installation directory for -Windows PowerShell +PowerShell - The `$Home` variable, which stores the current user's home directory -In addition, other programs that host Windows PowerShell can support their -own profiles. For example, Windows PowerShell Integrated Scripting -Environment (ISE) supports the following host-specific profiles. - -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Microsoft.PowerShellISE_profile.ps1 | -| All users, Current Host | $PsHome\Microsoft.PowerShellISE_profile.ps1 | +In addition, other programs that host PowerShell can support their own +profiles. For example, PowerShell Integrated Scripting Environment (ISE) +supports the following host-specific profiles. -In Windows PowerShell Help, the "CurrentUser, Current Host" profile is the profile most -often referred to as "your Windows PowerShell profile". +|Description | Path | +|--------------------------|-------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Microsoft.PowerShellISE_profile.ps1 | +|All users, Current Host |$PsHome\Microsoft.PowerShellISE_profile.ps1| -# THE $PROFILE VARIABLE +In PowerShell Help, the "CurrentUser, Current Host" profile is the profile +most often referred to as "your PowerShell profile". +## THE $PROFILE VARIABLE -The `$Profile` automatic variable stores the paths to the Windows PowerShell -profiles that are available in the current session. +The `$Profile` automatic variable stores the paths to the PowerShell profiles +that are available in the current session. To view a profile path, display the value of the `$Profile` variable. You can also use the `$Profile` variable in a command to represent a path. -The `$Profile` variable stores the path to the "Current User, -Current Host" profile. The other profiles are saved in note properties of -the `$Profile` variable. +The `$Profile` variable stores the path to the "Current User, Current Host" +profile. The other profiles are saved in note properties of the `$Profile` +variable. For example, the `$Profile` variable has the following values in the Windows PowerShell console. -| Name | Description | -| ------------- | ------------- | -| $Profile | Current User, Current Host | -| $Profile.CurrentUserCurrentHost | Current User, Current Host | -| $Profile.CurrentUserAllHosts | Current User, All Hosts | -| $Profile.AllUsersCurrentHost | All Users, Current Host | -| $Profile.AllUsersAllHosts | All Users, All Hosts | +|Name |Description | +|--------------------------------|---------------------------| +|$Profile |Current User, Current Host | +|$Profile.CurrentUserCurrentHost |Current User, Current Host | +|$Profile.CurrentUserAllHosts |Current User, All Hosts | +|$Profile.AllUsersCurrentHost |All Users, Current Host | +|$Profile.AllUsersAllHosts |All Users, All Hosts | -Because the values of the `$Profile` variable change for each user and in -each host application, ensure that you display the values of the -profile variables in each Windows PowerShell host application that you use. +Because the values of the `$Profile` variable change for each user and in each +host application, ensure that you display the values of the profile variables +in each PowerShell host application that you use. To see the current values of the `$Profile` variable, type: @@ -107,24 +102,22 @@ $profile | Get-Member -Type NoteProperty ``` You can use the `$Profile` variable in many commands. For example, the -following command opens the "Current User, Current Host" profile in -Notepad: +following command opens the "Current User, Current Host" profile in Notepad: ```powershell notepad $profile ``` -The following command determines whether an "All Users, All Hosts" profile -has been created on the local computer: +The following command determines whether an "All Users, All Hosts" profile has +been created on the local computer: ```powershell Test-Path -Path $profile.AllUsersAllHosts ``` -# HOW TO CREATE A PROFILE +## HOW TO CREATE A PROFILE - -To create a Windows PowerShell profile, use the following command format: +To create a PowerShell profile, use the following command format: ```powershell if (!(Test-Path -Path )) @@ -132,7 +125,7 @@ if (!(Test-Path -Path )) ``` For example, to create a profile for the current user in the current -Windows PowerShell host application, use the following command: +PowerShell host application, use the following command: ```powershell if (!(Test-Path -Path $profile)) @@ -140,21 +133,18 @@ if (!(Test-Path -Path $profile)) ``` In this command, the If statement prevents you from overwriting an existing -profile. Replace the value of the placeholder with the path +profile. Replace the value of the \ placeholder with the path to the profile file that you want to create. ->Note: To create "All Users" profiles in Windows Vista and later versions ->of Windows, start Windows PowerShell with the "Run as administrator" ->option. - -# HOW TO EDIT A PROFILE +> Note: To create "All Users" profiles in Windows Vista and later versions of +> Windows, start PowerShell with the "Run as administrator" >option. +## HOW TO EDIT A PROFILE -You can open any Windows PowerShell profile in a text editor, such as -Notepad. +You can open any PowerShell profile in a text editor, such as Notepad. -To open the profile of the current user in the current Windows PowerShell -host application in Notepad, type: +To open the profile of the current user in the current PowerShell host +application in Notepad, type: ```powershell notepad $profile @@ -167,106 +157,99 @@ profile for all the users of all the host applications, type: notepad $profile.AllUsersAllHosts ``` -To apply the changes, save the profile file, and then restart Windows -PowerShell. +To apply the changes, save the profile file, and then restart PowerShell. -# HOW TO CHOOSE A PROFILE +## HOW TO CHOOSE A PROFILE +If you use multiple host applications, put the items that you use in all the +host applications into your `$Profile.CurrentUserAllHosts` profile. Put items +that are specific to a host application, such as a command that sets the +background color for a host application, in a profile that is specific to that +host application. -If you use multiple host applications, put the items that you use in all -the host applications into your `$Profile.CurrentUserAllHosts` profile. -Put items that are specific to a host application, such as a command that -sets the background color for a host application, in a profile that is -specific to that host application. - -If you are an administrator who is customizing Windows -PowerShell for many users, follow these guidelines: +If you are an administrator who is customizing Windows PowerShell for many +users, follow these guidelines: - Store the common items in the `$profile.AllUsersAllHosts` profile - - Store items that are specific to a host application in -`$profile.AllUsersCurrentHost` profiles that are specific to the host -application - + `$profile.AllUsersCurrentHost` profiles that are specific to the host + application - Store items for particular users in the user-specific profiles Be sure to check the host application documentation for any special -implementation of Windows PowerShell profiles. - -# HOW TO USE A PROFILE +implementation of PowerShell profiles. +## HOW TO USE A PROFILE -Many of the items that you create in Windows PowerShell and most commands -that you run affect only the current session. When you end the session, -the items are deleted. +Many of the items that you create in PowerShell and most commands that you run +affect only the current session. When you end the session, the items are +deleted. The session-specific commands and items include variables, preference -variables, aliases, functions, commands (except for [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), -and Windows PowerShell snap-ins that you add to the session. +variables, aliases, functions, commands (except for +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), +and PowerShell modules that you add to the session. -To save these items and make them available in all future sessions, add -them to a Windows PowerShell profile. +To save these items and make them available in all future sessions, add them +to a PowerShell profile. -Another common use for profiles is to save frequently-used functions, -aliases, and variables. When you save the items in a profile, you can -use them in any applicable session without re-creating them. +Another common use for profiles is to save frequently-used functions, aliases, +and variables. When you save the items in a profile, you can use them in any +applicable session without re-creating them. -# HOW TO START A PROFILE +## HOW TO START A PROFILE - -When you open the profile file, it is blank. However, you can fill it with -the variables, aliases, and commands that you use frequently. +When you open the profile file, it is blank. However, you can fill it with the +variables, aliases, and commands that you use frequently. Here are a few suggestions to get you started. -- Add commands that make it easy to open your profile. This is especially -useful if you use a profile other than the "Current User, Current Host" -profile. For example, add the following command: +### Add commands that make it easy to open your profile + +This is especially useful if you use a profile other than the "Current User, +Current Host" profile. For example, add the following command: ```powershell function Pro {notepad $profile.CurrentUserAllHosts} ``` -- Add a function that opens Windows PowerShell Help in a compiled HTML -Help file (.chm) +### Add a function that opens PowerShell Help in a compiled HTML + Help file (.chm) ```powershell -function Get-CHM -{ -Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" +function Get-CHM { + Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" } ``` -This function opens the English version of the .chm file. However, you -can replace the language code (0409) to open other versions of the .chm -file. +This function opens the English version of the .chm file. However, you can +replace the language code (0409) to open other versions of the .chm file. -- Add a function that lists the aliases for any cmdlet +### Add a function that lists the aliases for any cmdlet ```powershell -function Get-CmdletAlias ($cmdletname) -{ -Get-Alias | Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | Format-Table -Property Definition, Name -AutoSize +function Get-CmdletAlias ($cmdletname) { + Get-Alias | + Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | + Format-Table -Property Definition, Name -AutoSize } ``` -- Customize your console +### Customize your console ```powershell -function Color-Console -{ -$Host.ui.rawui.backgroundcolor = "white" -$Host.ui.rawui.foregroundcolor = "black" -$hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime -$hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" -$Host.UI.RawUI.WindowTitle = "Windows PowerShell $hostversion ($hosttime)" -Clear-Host +function Color-Console { + $Host.ui.rawui.backgroundcolor = "white" + $Host.ui.rawui.foregroundcolor = "black" + $hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime + $hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" + $Host.UI.RawUI.WindowTitle = "PowerShell $hostversion ($hosttime)" + Clear-Host } Color-Console ``` -- Add a customized Windows PowerShell prompt that includes the computer -name and the current path +### Add a customized PowerShell prompt ```powershell function Prompt @@ -275,18 +258,16 @@ $env:COMPUTERNAME + "\" + (Get-Location) + "> " } ``` -For more information about the Windows PowerShell prompt, see +For more information about the PowerShell prompt, see [about_Prompts](about_Prompts.md). -# THE NOPROFILE PARAMETER +## THE NOPROFILE PARAMETER +To start PowerShell without profiles, use the **NoProfile** parameter of +PowerShell.exe, the program that starts PowerShell. -To start Windows PowerShell without profiles, use the **NoProfile** parameter -of PowerShell.exe, the program that starts Windows PowerShell. - -To begin, open a program that can start Windows PowerShell, such as Cmd.exe -or Windows PowerShell itself. You can also use the Run dialog box in -Windows. +To begin, open a program that can start PowerShell, such as Cmd.exe or +PowerShell itself. You can also use the Run dialog box in Windows. Type: @@ -294,56 +275,58 @@ Type: PowerShell -NoProfile ``` -For a complete list of the parameters of PowerShell.exe, -type: +For a complete list of the parameters of PowerShell.exe, type: ``` PowerShell -? ``` -# PROFILES AND EXECUTION POLICY - +## PROFILES AND EXECUTION POLICY -The Windows PowerShell execution policy determines, in part, whether you -can run scripts and load configuration files, including the profiles. The -"Restricted" execution policy is the default. It prevents all scripts from -running, including the profiles. If you use the "Restricted" policy, the -profile does not run, and its contents are not applied. +The PowerShell execution policy determines, in part, whether you can run +scripts and load configuration files, including the profiles. The "Restricted" +execution policy is the default. It prevents all scripts from running, +including the profiles. If you use the "Restricted" policy, the profile does +not run, and its contents are not applied. A `Set-ExecutionPolicy` command sets and changes your execution policy. It is -one of the few commands that applies in all Windows PowerShell sessions -because the value is saved in the registry. You do not have to set it when -you open the console, and you do not have to store a `Set-ExecutionPolicy` -command in your profile. +one of the few commands that applies in all PowerShell sessions because the +value is saved in the registry. You do not have to set it when you open the +console, and you do not have to store a `Set-ExecutionPolicy` command in your +profile. -# PROFILES AND REMOTE SESSIONS +## PROFILES AND REMOTE SESSIONS +PowerShell profiles are not run automatically in remote sessions, so the +commands that the profiles add are not present in the remote session. In +addition, the `$Profile` automatic variable is not populated in remote +sessions. -Windows PowerShell profiles are not run automatically in remote sessions, -so the commands that the profiles add are not present in the remote session. -In addition, the `$Profile` automatic variable is not populated in remote sessions. +To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) +cmdlet. -To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) cmdlet. - -For example, the following command runs the "Current user, Current Host" profile from -the local computer in the session in $s. +For example, the following command runs the "Current user, Current Host" +profile from the local computer in the session in $s. ```powershell Invoke-Command -Session $s -FilePath $profile ``` -The following command runs the "Current user, Current Host" profile from the remote -computer in the session in $s. Because the `$Profile` variable is not populated, -the command uses the explicit path to the profile. +The following command runs the "Current user, Current Host" profile from the +remote computer in the session in $s. Because the `$Profile` variable is not +populated, the command uses the explicit path to the profile. ```powershell -Invoke-Command -SessionName $s -ScriptBlock {Invoke-Command -FilePath "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +Invoke-Command -SessionName $s -ScriptBlock { +$path = "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +Invoke-Command -FilePath $path +} ``` After running this command, the commands that the profile adds to the session are available in $s. -# SEE ALSO +## SEE ALSO [about_Automatic_Variables](about_Automatic_Variables.md) diff --git a/reference/4.0/Microsoft.PowerShell.Management/Get-Process.md b/reference/4.0/Microsoft.PowerShell.Management/Get-Process.md index f352bea3b094..d4df0ff413d9 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Get-Process.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Get-Process.md @@ -103,17 +103,23 @@ The pipeline operator passes the objects to the Format-Table cmdlet, which forma The Priority view, and other views, are defined in the PS1XML format files in the Windows PowerShell home directory ($pshome). ### Example 5 -``` -PS C:\> get-process powershell -computername S1, localhost | ft @{Label="NPM(K)";Expression={[int]($_.NPM/1024)}}, @{Label="PM(K)";Expression={[int]($_.PM/1024)}},@{Label="WS(K)";Expression={[int]($_.WS/1024)}},@{Label="VM(M)";Expression={[int]($_.VM/1MB)}}, @{Label="CPU(s)";Expression={if ($_.CPU -ne $()) { $_.CPU.ToString("N")}}}, Id, MachineName, ProcessName -auto +```powershell +PS C:\> Get-Process powershell -ComputerName S1, localhost | + ft @{Label = "NPM(K)"; Expression = {[int]($_.NPM / 1024)}}, + @{Label = "PM(K)"; Expression = {[int]($_.PM / 1024)}}, + @{Label = "WS(K)"; Expression = {[int]($_.WS / 1024)}}, + @{Label = "VM(M)"; Expression = {[int]($_.VM / 1MB)}}, + @{Label = "CPU(s)"; Expression = {if ($_.CPU) {$_.CPU.ToString("N")}}}, + Id, MachineName, ProcessName -Auto NPM(K) PM(K) WS(K) VM(M) CPU(s) Id MachineName ProcessName ------ ----- ----- ----- ------ -- ----------- ----------- -6 23500 31340 142 1980 S1 powershell -6 23500 31348 142 4016 S1 powershell -27 54572 54520 576 4428 localhost powershell + 6 23500 31340 142 1.70 1980 S1 powershell + 6 23500 31348 142 2.75 4016 S1 powershell + 27 54572 54520 576 5.52 4428 localhost powershell ``` -This example provides a Format-Table (alias = ft) command that adds the MachineName property to the standard Get-Process output display. +This example provides a `Format-Table` (alias = ft) command that adds the MachineName property to the standard `Get-Process` output display. ### Example 6 ``` diff --git a/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md b/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md index 5747b471a171..822e30e4af21 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md @@ -16,9 +16,9 @@ The provider supplies the path delimiters. ## SYNTAX -``` -Join-Path [-Path] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] - [] +```powershell +Join-Path [-Path] [-ChildPath] + [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## DESCRIPTION @@ -84,7 +84,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True @@ -125,7 +125,7 @@ Parameter Sets: (All) Aliases: PSPath Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Get-TraceSource.md b/reference/4.0/Microsoft.PowerShell.Utility/Get-TraceSource.md index 0dac5c1b685a..c105d7a82284 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Get-TraceSource.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Get-TraceSource.md @@ -55,7 +55,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md index ac34a820e26c..0f745ac3aa94 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Object_Creation.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,232 +7,246 @@ title: about_Object_Creation --- # About Object Creation -## about_Object_Creation - ## SHORT DESCRIPTION -Explains how to create objects in Windows PowerShell? +Explains how to create objects in PowerShell. ## LONG DESCRIPTION -You can create objects in Windows PowerShell and use the objects that you create in commands and scripts. - -There are several ways to create objects: - -New-Object: -The New-Object cmdlet creates an instance of a .NET Framework object or COM object. +You can create objects in PowerShell and use the objects that you create in +commands and scripts. -Hash tables: +There are several ways to create objects: -Beginning in Windows PowerShell 3.0, you can create objects from hash tables of property names and property values. +- `New-Object`: This cmdlet creates an instance of a .NET Framework object or + COM object. -Import-Csv: +- Hash tables: Beginning in PowerShell 3.0, you can create objects + from hash tables of property names and property values. -The Import-Csv cmdlet creates custom objects (PSCustomObject) from the items in a CSV file. Each row is an object instance and each column is an object property. +- `Import-Csv`: This cmdlet creates custom objects (PSCustomObject) from the + items in a CSV file. Each row is an object instance and each column is an + object property. This topic will demonstrate and discuss each of these methods. - ## NEW-OBJECT -The New-Object cmdlet provides a robust and consistent way to create new objects. The cmdlet works with almost all types and in all supported versions of Windows PowerShell. -To create a new object, specify either the type of a .NET Framework class or a ProgID of a COM object. +The `New-Object` cmdlet provides a robust and consistent way to create new +objects. The cmdlet works with almost all types and in all supported versions +of PowerShell. -For example, the following command creates a Version object. +To create a new object, specify either the type of a .NET Framework class or a +ProgID of a COM object. +For example, the following command creates a Version object. -``` -PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 +```powershell +PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 PS C:\> $v ``` - - -``` -Major Minor Build Revision ------ ----- ----- -------- +```Output +Major Minor Build Revision +----- ----- ----- -------- 2 0 0 1 ``` +```powershell +PS C:\> $v | Get-Member - -``` -PS C:\> $v | Get-Member - TypeName: System.Version ``` - For more information, see the help topic for the New-Object cmdlet. - ### CREATE 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: ``` -[]@{=;=} +[]@{ + = + = +} ``` - -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. ### CREATE CUSTOM OBJECTS FROM HASH TABLES -Custom objects are very useful and they are very easy to create by using the hash table method. To create a custom object, use the PSCustomObject class, a class designed specifically for this purpose. - -Custom objects are an excellent way to return customized output from a function or script; far more useful than returning formatted output that cannot be reformatted or piped to other commands. - -The commands in the Test-Object function set some variable values and then use those values to create a custom object. (You can see this object in use in the example section of the Update-Help cmdlet help topic.) - -``` -function Test-Object -{ $ModuleName = "PSScheduledJob" - $HelpCulture = "en-us" - $HelpVersion = "3.1.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} - - $ModuleName = "PSWorkflow" - $HelpCulture = "en-us" - $HelpVersion = "3.0.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} +Custom objects are very useful and they are very easy to create by using the +hash table method. To create a custom object, use the PSCustomObject class, a +class designed specifically for this purpose. + +Custom objects are an excellent way to return customized output from a +function or script; far more useful than returning formatted output that +cannot be reformatted or piped to other commands. + +The commands in the `Test-Object function` set some variable values and then +use those values to create a custom object. You can see this object in use in +the example section of the `Update-Help` cmdlet help topic. + +```powershell +function Test-Object { + $ModuleName = "PSScheduledJob" + $HelpCulture = "en-us" + $HelpVersion = "3.1.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } + $ModuleName = "PSWorkflow" + $HelpCulture = "en-us" + $HelpVersion = "3.0.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } } ``` +The output of this function is a collection of custom objects formatted as a +table by default. -The output of this function is a collection of custom objects formatted as a table by default. - +```powershell +PS C:\> Test-Object -``` -PS C:\> Test-Object - -ModuleName UICulture Version ---------- --------- ------- -PSScheduledJob en-us 3.1.0.0 +ModuleName UICulture Version +--------- --------- ------- +PSScheduledJob en-us 3.1.0.0 PSWorkflow en-us 3.0.0.0 ``` +Users can manage the properties of the custom objects just as they do with +standard objects. -Users can manage the properties of the custom objects just as they do with standard objects. - - -``` -PS C:\> (Test-Object).ModuleName - PSScheduledJob +```powershell +PS C:\> (Test-Object).ModuleName + PSScheduledJob PSWorkflow ``` - - #### CREATE NON-CUSTOM OBJECTS FROM HASH TABLES -You can also use hash tables to create objects for non-custom classes. When you create an object for a non-custom class, the full namespace name is required unless class is in the System namespace. Use only the properties of the class. -For example, the following command creates a session option object. +You can also use hash tables to create objects for non-custom classes. When +you create an object for a non-custom class, the full namespace name is +required unless class is in the System namespace. Use only the properties of +the class. +For example, the following command creates a session option object. +```powershell +[System.Management.Automation.Remoting.PSSessionOption]@{ + IdleTimeout=43200000 + SkipCnCheck=$True +} ``` -[System.Management.Automation.Remoting.PSSessionOption]@{IdleTimeout=43200000; SkipCnCheck=$True} -``` - -The requirements of the hash table feature, especially the null constructor requirement, eliminate many existing classes. However, most Windows PowerShell option classes are designed to work with this feature, as well as other very useful classes, such as the ScheduledJobTrigger class. +The requirements of the hash table feature, especially the null constructor +requirement, eliminate many existing classes. However, most PowerShell option +classes are designed to work with this feature, as well as other very useful +classes, such as the ScheduledJobTrigger class. +```powershell +[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{ + Frequency="Daily" + At="15:00" +} -``` -[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{Frequency="Daily";At="15:00"} - -Id Frequency Time DaysOfWeek Enabled --- --------- ---- ---------- ------- -0 Daily 6/6/2012 3:00:00 PM True +Id Frequency Time DaysOfWeek Enabled +-- --------- ---- ---------- ------- +0 Daily 6/6/2012 3:00:00 PM True ``` +You can also use the hash table feature when setting parameter values. For +example, the value of the **SessionOption** parameter of the New-PSSession +cmdlet and the value of the JobTrigger parameter of `Register-ScheduledJob` +can be a hash table. -You can also use the hash table feature when setting parameter values. For example, the value of the SessionOption parameter of the New-PSSession cmdlet and the value of the JobTrigger parameter of Register-ScheduledJob can be a hash table. - - -``` -New-PSSession -ComputerName Server01 -SessionOption @{IdleTimeout=43200000; SkipCnCheck=$True} -Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{Frequency="Daily";At="15:00"} +```powershell +New-PSSession -ComputerName Server01 -SessionOption @{ + IdleTimeout=43200000 + SkipCnCheck=$True +} +Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{ + Frequency="Daily" + At="15:00" +} ``` - - ### IMPORT-CSV -You can create custom objects from the items in a CSV file. When you use the Import-Csv cmdlet to import the CSV file, the cmdlet creates a custom object (PSCustomObject) for each item in the file. The column names are the object properties. -For example, if you import a CSV file of computer asset data, Import-CSV creates a collection of custom objects from the input. +You can create custom objects from the items in a CSV file. When you use the +`Import-Csv` cmdlet to import the CSV file, the cmdlet creates a custom object +(PSCustomObject) for each item in the file. The column names are the object +properties. +For example, if you import a CSV file of computer asset data, `Import-CSV` +creates a collection of custom objects from the input. ``` -#In Servers.csv -AssetID, Name, OS, Department -003, Server01, Windows Server 2012, IT -103, Server33, Windows 7, Marketing +#In Servers.csv +AssetID, Name, OS, Department +003, Server01, Windows Server 2012, IT +103, Server33, Windows 7, Marketing 212, Server35, Windows 8, Finance ``` +```powershell +PS C:\> $a = Import-Csv Servers.csv +PS C:\> $a - -``` -PS C:\> $a = Import-Csv Servers.csv -PS C:\> $a - -AssetID Name OS Department -------- ---- -- ---------- -003 Server01 Windows Server 2012 IT -103 Server33 Windows 7 Marketing +AssetID Name OS Department +------- ---- -- ---------- +003 Server01 Windows Server 2012 IT +103 Server33 Windows 7 Marketing 212 Server35 Windows 8 Finance ``` - Use the Get-Member cmdlet to confirm the object type. - -``` +```powershell PS C:\> $a | Get-Member ``` +```Output +TypeName: System.Management.Automation.PSCustomObject - -``` -TypeName: System.Management.Automation.PSCustomObject - -Name MemberType Definition ----- ---------- ---------- -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -AssetID NoteProperty System.String AssetID=003 -Department NoteProperty System.String Department=IT -Name NoteProperty System.String Name=Server01 +Name MemberType Definition +---- ---------- ---------- +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +AssetID NoteProperty System.String AssetID=003 +Department NoteProperty System.String Department=IT +Name NoteProperty System.String Name=Server01 OS NoteProperty System.String OS=Windows Server 2012 ``` - You can use the custom objects just as you would standard objects. - -``` +```powershell PS C:\> $a | where {$_.OS -eq "Windows 8"} ``` - - -``` -AssetID Name OS Department -------- ---- -- ---------- +```output +AssetID Name OS Department +------- ---- -- ---------- 212 Server35 Windows 8 Finance ``` - For more information, see the help topic for the Import-Csv cmdlet. - ## SEE ALSO [about_Objects](about_Objects.md) @@ -243,9 +257,8 @@ For more information, see the help topic for the Import-Csv cmdlet. [about_Pipelines](about_Pipelines.md) -Get-Member - -Import-Csv +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -New-Object +[Import-Csv](../../Microsoft.PowerShell.Utility/Import-Csv.md) +[New-Object](../../Microsoft.PowerShell.Utility/New-Object.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Objects.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Objects.md index 88ab499af532..58308cabd6d7 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Objects.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Objects.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -58,20 +58,13 @@ directory objects are passed down the pipeline to the second command. The second command `where { $_.PsIsContainer -eq $false }` uses the PsIsContainer property of all file system objects to select only -files, which have a value of False ($false) in their PsIsContainer +files, which have a value of False (\$false) in their PsIsContainer property. Folders, which are containers and, thus, have a value of -True ($true) in their PsIsContainer property, are not selected. +True (\$true) in their PsIsContainer property, are not selected. The second command passes only the file objects to the third command `Format-List`, which displays the file objects in a list. -## For More Information - -Now that you understand a bit about objects, see the [about_Methods](about_Methods.md) -help topic to learn how to find and use object methods, the -[about_Properties](about_Properties.md) topic to learn how to find and use object properties, -and the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) topic, to learn how to find an object type. - ## See Also [about_Methods](about_Methods.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 6e83191b889c..01d129ccc4bb 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,84 +10,85 @@ title: about_Operator_Precedence ## SHORT DESCRIPTION -Lists the Windows PowerShell operators in precedence order. +Lists the PowerShell operators in precedence order. -[This topic was contributed by Kirk Munro, a Windows PowerShell MVP +[This topic was contributed by Kirk Munro, a PowerShell MVP from Ottawa, Ontario] ## LONG DESCRIPTION -Windows PowerShell operators let you construct simple, but powerful -expressions. This topic lists the operators in precedence order. -Precedence order is the order in which Windows PowerShell evaluates -the operators when multiple operators appear in the same expression. - -When operators have equal precedence, Windows PowerShell evaluates -them from left to right. The exceptions are the assignment operators, -the cast operators, and the negation operators (!, -not, -bnot), -which are evaluated from right to left. - -You can use enclosures, such as parentheses, to override the -standard precedence order and force Windows PowerShell to evaluate -the enclosed part of an expression before an unenclosed part. - -In the following list, operators are listed in the order that they -are evaluated. Operators on the same line, or in the same group, have -equal precedence. - -The Operator column lists the operators. The Reference column lists -the Windows PowerShell Help topic in which the operator is described. -To display the topic, type `get-help `. - -|OPERATOR|REFERENCE| -|--------|---------| -|`$() @()`|[about_Operators](#index-operator)| -|`.` (dereference) `::` (static)|[about_Operators](about_Operators.md)| -|`[0]` (index operator)|[about_Operators](about_Operators.md)| +PowerShell operators let you construct simple, but powerful +expressions. This topic lists the operators in precedence order. Precedence +order is the order in which PowerShell evaluates the operators when +multiple operators appear in the same expression. + +When operators have equal precedence, PowerShell evaluates them from +left to right. The exceptions are the assignment operators, the cast +operators, and the negation operators (!, -not, -bnot), which are evaluated +from right to left. + +You can use enclosures, such as parentheses, to override the standard +precedence order and force PowerShell to evaluate the enclosed part of +an expression before an unenclosed part. + +In the following list, operators are listed in the order that they are +evaluated. Operators on the same line, or in the same group, have equal +precedence. + +The Operator column lists the operators. The Reference column lists the +PowerShell Help topic in which the operator is described. To display +the topic, type `get-help `. + +|OPERATOR |REFERENCE| +|------------------------|---------| +|`$() @()` |[about_Operators](#index-operator)| +|`.` (dereference) |[about_Operators](about_Operators.md)| +|`::` (static) |[about_Operators](about_Operators.md)| +|`[0]` (index operator) |[about_Operators](about_Operators.md)| |`[int]` (cast operators)|[about_Operators](about_Operators.md)| -|`-split` (unary)
`-join` (unary)|[about_Split](about_Split.md)
[about_Join](about_Join.md)| -|`,` (comma operator)|[about_Operators](about_Operators.md)| -|`++ --`|[about_Assignment_Operators](about_Assignment_Operators.md)| -|`-not`
`! -bNot`|[about_Logical_Operators](about_logical_operators.md)
[about_Comparison_Operators](about_Comparison_Operators.md)| -|`..` (range operator)|[about_Operators](about_Operators.md)| -|`-f` (format operator)|[about_Operators](about_Operators.md)| -|`* / %`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`+ -`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| - - -The following group of operators have equal precedence. Their -case-sensitive and explicitly case-insensitive variants have -the same precedence. - -|OPERATOR|REFERENCE| -|--------|---------| -|`-split` (unary)|[about_Split](about_Split.md)| -|`-join` (unary)|[about_Join](about_Join.md)| -|`-is -isnot -as`|[about_Type_Operators](about_Type_Operators.md)| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`,` (comma operator) |[about_Operators](about_Operators.md)| +|`++ --` |[about_Assignment_Operators](about_Assignment_Operators.md)| +|`-not` |[about_Logical_Operators](about_logical_operators.md)| +|`! -bNot` |[about_Comparison_Operators](about_Comparison_Operators.md)| +|`..` (range operator) |[about_Operators](about_Operators.md)| +|`-f` (format operator) |[about_Operators](about_Operators.md)| +|`* / % + -` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| + +The following group of operators have equal precedence. Their case-sensitive +and explicitly case-insensitive variants have the same precedence. + +|OPERATOR |REFERENCE| +|-------------------------|---------| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`-is -isnot -as` |[about_Type_Operators](about_Type_Operators.md)| |`-eq -ne -gt -gt -lt -le`|[about_Comparison_Operators](about_Comparison_Operators.md)| -|`-like -notlike`|[about_comparison_operators](about_comparison_operators.md)| -|`-match -notmatch`|[about_comparison_operators](about_comparison_operators.md)| -|`-in -notIn`|[about_comparison_operators](about_comparison_operators.md)| -|`-contains -notContains`|[about_comparison_operators](about_comparison_operators.md)| -|`-replace`|[about_comparison_operators](about_comparison_operators.md)| +|`-like -notlike` |[about_comparison_operators](about_comparison_operators.md)| +|`-match -notmatch` |[about_comparison_operators](about_comparison_operators.md)| +|`-in -notIn` |[about_comparison_operators](about_comparison_operators.md)| +|`-contains -notContains` |[about_comparison_operators](about_comparison_operators.md)| +|`-replace` |[about_comparison_operators](about_comparison_operators.md)| The list resumes here with the following operators in precedence order: -|OPERATOR|REFERENCE| -|--------|---------| -|`-band -bor -bxor`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor`|[about_comparison_operators](about_comparison_operators.md)| -|`.` (dot-source)
`&` (call)|[about_Scopes](about_Scopes.md)
[about_Operators](about_Operators.md)| +|OPERATOR |REFERENCE| +|--------------------------|---------| +|`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| +|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`.` (dot-source) |[about_Scopes](about_Scopes.md)| +|`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| -|`> >> 2> 2>> 2>&1`|[about_Redirection](about_Redirection.md)| -|`= += -= *= /= %=`|[about_Assignment_Operators](about_Assignment_Operators.md)| +|`> >> 2> 2>> 2>&1` |[about_Redirection](about_Redirection.md)| +|`= += -= *= /= %=` |[about_Assignment_Operators](about_Assignment_Operators.md)| # EXAMPLES -The following two commands show the arithmetic operators and -the effect of using parentheses to force Windows PowerShell to -evaluate the enclosed part of the expression first. +The following two commands show the arithmetic operators and the effect of +using parentheses to force PowerShell to evaluate the enclosed part of +the expression first. ```powershell C:\PS> 2 + 3 * 4 @@ -97,8 +98,8 @@ C:\PS> (2 + 3) * 4 20 ``` -The following example gets the read-only text files from the local -directory and saves them in the `$read_only` variable. +The following example gets the read-only text files from the local directory +and saves them in the `$read_only` variable. ```powershell $read_only = get-childitem *.txt | where-object {$_.isReadOnly} @@ -109,37 +110,37 @@ It is equivalent to the following example. $read_only = ( get-childitem *.txt | where-object {$_.isReadOnly} ) ``` -Because the pipeline operator (|) has a higher precedence than the -assignment operator (=), the files that the Get-ChildItem cmdlet -gets are sent to the Where-Object cmdlet for filtering before they -are assigned to the $read_only variable. +Because the pipeline operator (|) has a higher precedence than the assignment +operator (=), the files that the Get-ChildItem cmdlet gets are sent to the +Where-Object cmdlet for filtering before they are assigned to the $read_only +variable. -The following example demonstrates that the index operator takes -precedence over the cast operator. +The following example demonstrates that the index operator takes precedence +over the cast operator. -The first expression creates an array of three strings. Then, it -uses the index operator with a value of 0 to select the first object -in the array, which is the first string. Finally, it casts the -selected object as a string. In this case, the cast has no effect. +The first expression creates an array of three strings. Then, it uses the +index operator with a value of 0 to select the first object in the array, +which is the first string. Finally, it casts the selected object as a string. +In this case, the cast has no effect. ```powershell C:\PS> [string]@('Windows','PowerShell','2.0')[0] Windows ``` -The second expression uses parentheses to force the cast operation -to occur before the index selection. As a result, the entire array -is cast as a (single) string. Then, the index operator selects -the first item in the string array, which is the first character. +The second expression uses parentheses to force the cast operation to occur +before the index selection. As a result, the entire array is cast as a +(single) string. Then, the index operator selects the first item in the string +array, which is the first character. ```powershell C:\PS> ([string]@('Windows','PowerShell','2.0'))[0] W ``` -In the following example, because the -gt (greater-than) operator -has a higher precedence than the -and (logical AND) operator, the -result of the expression is FALSE. +In the following example, because the -gt (greater-than) operator has a higher +precedence than the -and (logical AND) operator, the result of the expression +is FALSE. ```powershell C:\PS> 2 -gt 4 -and 1 @@ -160,11 +161,11 @@ C:\PS> 2 -gt (4 -and 1) True ``` -However, this example demonstrates an important principle of managing -operator precedence. When an expression is difficult for people to -interpret, use parentheses to force the evaluation order, even when it -forces the default operator precedence. The parentheses make your -intentions clear to people who are reading and maintaining your scripts. +However, this example demonstrates an important principle of managing operator +precedence. When an expression is difficult for people to interpret, use +parentheses to force the evaluation order, even when it forces the default +operator precedence. The parentheses make your intentions clear to people who +are reading and maintaining your scripts. ## SEE ALSO @@ -185,4 +186,3 @@ intentions clear to people who are reading and maintaining your scripts. [about_Split](about_Split.md) [about_Type_Operators](about_Type_Operators.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index d2fc74e0c5c4..e9c4ebaefa98 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,449 +7,409 @@ title: about_Parameters_Default_Values --- # About Parameters Default Values -## about_Parameters_Default_Values - ## SHORT DESCRIPTION -Describes how to set custom default values for the parameters of cmdlets and advanced functions. +Describes how to set custom default values for the parameters of cmdlets and +advanced functions. ## LONG DESCRIPTION -The $PSDefaultParameterValues preference variable lets you specify custom default values for any cmdlet or advanced function. Cmdlets and functions use the custom default value unless you specify another value in the command. -The authors of cmdlets and advanced functions set standard default values for their parameters. Typically, the standard default values are useful, but they might not be appropriate for all environments. +The \$PSDefaultParameterValues preference variable lets you specify custom +default values for any cmdlet or advanced function. Cmdlets and functions use +the custom default value unless you specify another value in the command. + +The authors of cmdlets and advanced functions set standard default values for +their parameters. Typically, the standard default values are useful, but they +might not be appropriate for all environments. -This feature is especially useful when you must specify the same alternate parameter value nearly every time you use the command or when a particular parameter value is difficult to remember, such as an e-mail server name or project GUID. +This feature is especially useful when you must specify the same alternate +parameter value nearly every time you use the command or when a particular +parameter value is difficult to remember, such as an e-mail server name or +project GUID. -If the desired default value varies predictably, you can specify a script block that provides different default values for a parameter under different conditions. +If the desired default value varies predictably, you can specify a script +block that provides different default values for a parameter under different +conditions. -$PSDefaultParameterValues was introduced in Windows PowerShell?3.0. +\$PSDefaultParameterValues was introduced in PowerShell 3.0. +## SYNTAX -### SYNTAX The syntax of the $PSDefaultParameterValues preference variable is as follows: +```powershell +$PSDefaultParameterValues=@{":"=""} + +$PSDefaultParameterValues=@{":"={}} -``` -$PSDefaultParameterValues=@{":"=""} - -$PSDefaultParameterValues=@{":"={}} - $PSDefaultParameterValues["Disabled"]=$true | $false ``` - Wildcard characters are permitted in the CmdletName and ParameterName values. -The value of $PSDefaultParameterValues is a System.Management.Automation.DefaultParameterDictionary, a type of hash table that validates the format of keys. Enter a hash table where the key consists of the cmdlet name and parameter name separated by a colon (:) and the value is the custom default value. - -To set, change, add, or remove entries from $PSDefaultParameterValues, use the methods that you would use to edit a standard hash table. +The value of \$PSDefaultParameterValues is a +System.Management.Automation.DefaultParameterDictionary, a type of hash table +that validates the format of keys. Enter a hash table where the key consists +of the cmdlet name and parameter name separated by a colon (:) and the value +is the custom default value. -The must be the name of a cmdlet or the name of an advanced function that uses the CmdletBinding attribute. You cannot use $PSDefaultParameterValues to specify default values for scripts or simple functions. +To set, change, add, or remove entries from \$PSDefaultParameterValues, use the +methods that you would use to edit a standard hash table. -The default value can be an object or a script block. If the value is a script block, Windows PowerShell evaluates the script block and uses the result as the parameter value. When the specified parameter takes a script block value, enclose the script block value in a second set of braces, such as: +The \ must be the name of a cmdlet or the name of an advanced +function that uses the CmdletBinding attribute. You cannot use +$PSDefaultParameterValues to specify default values for scripts or simple +functions. +The default value can be an object or a script block. If the value is a script +block, PowerShell evaluates the script block and uses the result as the +parameter value. When the specified parameter takes a script block value, +enclose the script block value in a second set of braces, such as: -``` +```powershell $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } ``` +For information about hash tables, see +[about_Hash_Tables](about_Hash_Tables.md). For information about script +blocks, see [about_Script_Blocks](about_Script_Blocks.md). For information +about preference variables, see +[about_Preference_Variables](about_Preference_Variables.md). -For information about hash tables, see about_Hash_Tables. For information about script blocks, see about_Script_Blocks. For information about preference variables, see about_Preference_Variables. - +## EXAMPLES -### EXAMPLES -The following command sets a custom default value for the SmtpServer parameter of the Send-MailMessage cmdlet. +The following command sets a custom default value for the SmtpServer parameter +of the Send-MailMessage cmdlet. - -``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"} +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" +} ``` +To set default values for multiple parameters, use a semi-colon (;) to +separate each Name\=Value pair. The following command adds a custom default +value for the LogName parameter of the `Get-WinEvent` cmdlet. -To set default values for multiple parameters, use a semi-colon (;) to separate each Name\=Value pair. The following command adds a custom default value for the LogName parameter of the Get-WinEvent cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5"; + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" +} ``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"} -``` - -You can use wildcard characters in the name of the cmdlet and parameter. The following command sets the Verbose common parameter to $true in all commands. Use $true and $false to set values for switch parameters, such as Verbose. +You can use wildcard characters in the name of the cmdlet and parameter. The +following command sets the Verbose common parameter to \$true in all commands. +Use \$true and \$false to set values for switch parameters, such as +**Verbose**. - -``` +```powershell $PSDefaultParameterValues = @{"*:Verbose"=$true} ``` +If a parameter takes multiple values (an array), you can set multiple values +as the default value. The following command sets the default value of the +**ComputerName** parameter of the Invoke-Command cmdlet to "Server01" and +"Server02". -If a parameter takes multiple values (an array), you can set multiple values as the default value. The following command sets the default value of the ComputerName parameter of the Invoke-Command cmdlet to "Server01" and "Server02". - - -``` -$PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"} -``` - - -You can use a script block to specify different default values for a parameter under different conditions. Windows PowerShell evaluates the script block and uses the result as the default parameter value. - -The following command sets the default value of the Autosize parameter of the Format-Table cmdlet to $true when the host program is the Windows PowerShell console. - - -``` -$PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}}} -``` - - -If a parameter takes a script block value, enclose the script block in an extra set of braces. When Windows PowerShell evaluates the outer script block, the result is the inner script block, which is set as the default parameter value. - -The following command sets the default value of the ScriptBlock parameter of Invoke-Command. Because the script block is enclosed in a second set of braces, the enclosed script block is passed to the Invoke-Command cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Invoke-Command:ComputerName"="Server01","Server02" +} ``` -$PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}} -``` - - - -### HOW TO SET $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. - -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues +You can use a script block to specify different default values for a parameter +under different conditions. PowerShell evaluates the script block and uses the +result as the default parameter value. -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. +The following command sets the default value of the Autosize parameter of the +Format-Table cmdlet to \$true when the host program is the PowerShell console. - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +$PSDefaultParameterValues=@{ + "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}} +} ``` +If a parameter takes a script block value, enclose the script block in an +extra set of braces. When PowerShell evaluates the outer script block, the +result is the inner script block, which is set as the default parameter value. +The following command sets the default value of the ScriptBlock parameter of +`Invoke-Command`. Because the script block is enclosed in a second set of +braces, the enclosed script block is passed to the `Invoke-Command` cmdlet. -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational -Get*:Verbose True +```powershell +$PSDefaultParameterValues=@{ + "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} +} ``` +### HOW TO SET \$PSDefaultParameterValues -To get the value of a key, use the following command syntax: +\$PSDefaultParameterValues is a preference variable, so it exists only in the +session in which it is set. It has no default value. +To set \$PSDefaultParameterValues, type the variable name and one or more +key-value pairs at the command line. -``` -$PSDefaultParameterValues[""] -``` +If you type another \$PSDefaultParameterValues command, its value replaces the +original value. The original is not retained. +To save \$PSDefaultParameterValues for future sessions, add a +\$PSDefaultParameterValues command to your PowerShell profile. For more +information, see [about_Profiles](about_Profiles.md). -For example: +### HOW TO GET \$PSDefaultParameterValues +To get the value of \$PSDefaultParameterValues, at the command prompt, type: +```powershell +$PSDefaultParameterValues ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] -Server01AB234x5 -``` - - - -### HOW TO ADD VALUES TO $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. +For example, the first command sets the value of \$PSDefaultParameterValues. +The second command gets the value of \$PSDefaultParameterValues. -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues - -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. - - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +PS C:\> $PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + "Get-*:Verbose"=$true +} ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To get the value of a \ key, use the following +command syntax: -To get the value of a key, use the following command syntax: - - -``` +```powershell $PSDefaultParameterValues[""] ``` - For example: - -``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] Server01AB234x5 ``` +### HOW TO ADD VALUES TO PSDefaultParameterValues +To add or remove values from \$PSDefaultParameterValues, use the methods that +you would use for a standard hash table. -### HOW TO ADD VALUES TO $PSDefaultParameterValues -To add or remove values from $PSDefaultParameterValues, use the methods that you would use for a standard hash table. - -For example, to add a value to $PSDefaultParameterValues without affecting the existing values, use the Add method of hash tables. +For example, to add a value to \$PSDefaultParameterValues without affecting the +existing values, use the Add method of hash tables. The syntax of the Add method is as follows: - ``` .Add(Key, Value) ``` +where the Key is ":" and the value is the parameter +value. -where the Key is ":" and the value is the parameter value. - -Use the following command format to call the Add method on $PSDefaultParameterValues. Be sure to use a comma (,) to separate the key from the value, instead of the equal sign (\=). - +Use the following command format to call the Add method on +\$PSDefaultParameterValues. Be sure to use a comma (,) to separate the key +from the value, instead of the equal sign (\=). +```powershell +$PSDefaultParameterValues.Add( + ":", "" +) ``` -$PSDefaultParameterValues.Add(":", "") -``` - -For example, the following command adds "PowerShell" as the default value of the Name parameter of the Get-Process cmdlet. +For example, the following command adds "PowerShell" as the default value of +the Name parameter of the Get-Process cmdlet. - -``` +```powershell $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO REMOVE VALUES FROM \$PSDefaultParameterValues - -### HOW TO REMOVE VALUES FROM $PSDefaultParameterValues -To remove a value from $PSDefaultParameterValues, use the Remove method of hash tables. +To remove a value from \$PSDefaultParameterValues, use the Remove method of +hash tables. The syntax of the Remove method is as follows: - -``` +```powershell .Remove(Key) ``` +Use the following command format to call the Remove method on +\$PSDefaultParameterValues. -Use the following command format to call the Remove method on $PSDefaultParameterValues. - - -``` +```powershell $PSDefaultParameterValues.Remove(":") ``` +For example, the following command removes the Name parameter of the +`Get-Process` cmdlet and its values. -For example, the following command removes the Name parameter of the Get-Process cmdlet and its values. - - -``` +```powershell $PSDefaultParameterValues.Remove("Get-Process:Name") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO CHANGE VALUES IN \$PSDefaultParameterValues +To change a value in $PSDefaultParameterValues, use the following command +format. -### HOW TO CHANGE VALUES IN $PSDefaultParameterValues -To change a value in $PSDefaultParameterValues, use the following command format. - - -``` +```powershell $PSDefaultParameterValues["CmdletName:ParameterName"]="" ``` - The following example shows the effect of this command. +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - +```powershell +$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" -``` - +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO DISABLE AND RE-ENABLE \$PSDefaultParameterValues +You can temporarily disable and then re-enable \$PSDefaultParameterValues. This +is very useful if you're running scripts that might assume different default +parameter values. -### HOW TO DISABLE AND RE-ENABLE $PSDefaultParameterValues -You can temporarily disable and then re-enable $PSDefaultParameterValues. This is very useful if you're running scripts that might assume different default parameter values. - -To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of $True. +To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of +\$True. For example, - -``` +```powershell $PSDefaultParameterValues.Add("Disabled", $true) ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$true ``` +The other values in \$PSDefaultParameterValues are preserved, but not +effective. -The other values in $PSDefaultParameterValues are preserved, but not effective. - +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Disabled True -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Disabled True +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To re-enable \$PSDefaultParameterValues, remove the Disabled key or change the +value of the Disabled key to \$False. -To re-enable $PSDefaultParameterValues, remove the Disabled key or change the value of the Disabled key to $False. - - -``` +```powershell $PSDefaultParameterValues.Remove("Disabled") ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$false ``` - -The previous value of $PSDefaultParameterValues is effective again. - +The previous value of \$PSDefaultParameterValues is effective again. ## KEYWORDS + about_PSDefaultParameterValues about_Parameters_DefaultValues about_DefaultValues - ## SEE ALSO [about_Hash_Tables](about_Hash_Tables.md) @@ -459,4 +419,3 @@ about_DefaultValues [about_Profiles](about_Profiles.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 886b4ed1dfc9..906dc159fb8a 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-05 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -248,7 +248,7 @@ debug message is not displayed and processing continues. The final command uses the Debug parameter to override the preference for a single command. ```powershell -PS> $debugpreference # Get the current value of \$DebugPreference +PS> $debugpreference # Get the current value of $DebugPreference SilentlyContinue PS> write-debug "Hello, World" @@ -301,7 +301,7 @@ uses the Debug parameter with a value of \$false to suppress the message for a single command. ```powershell -PS> \$debugpreference = "Inquire" +PS> $debugpreference = "Inquire" PS> write-debug "Hello, World" DEBUG: Hello, World @@ -375,7 +375,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value of the preference. -PS> \$ErrorActionPreference = "SilentlyContinue" +PS> $ErrorActionPreference = "SilentlyContinue" PS> # Generate an error message. PS> write-error "Hello, World" @@ -393,14 +393,14 @@ a non-existent file, nofile.txt. The example also uses the ErrorAction common parameter to override the preference. ```powershell -PS> \$erroractionpreference +PS> $erroractionpreference SilentlyContinue # Display the value of the preference. PS> get-childitem -path nofile.txt PS> # Error message is suppressed. PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> get-childitem -path nofile.txt Get-ChildItem : Cannot find path 'C:\nofile.txt' because it does not exist. @@ -412,7 +412,7 @@ PS> get-childitem -path nofile.txt -erroraction SilentlyContinue PS> # Error message is suppressed. PS> # Change the value to Inquire. -PS> \$ErrorActionPreference = "Inquire" +PS> $ErrorActionPreference = "Inquire" PS> get-childitem -path nofile.txt Confirm @@ -425,7 +425,7 @@ At line:1 char:4 + get-childitem <<<< nofile.txt PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> Get-Childitem nofile.txt -erroraction "Inquire" PS> # Use the ErrorAction parameter to override the preference value. @@ -462,7 +462,7 @@ NormalView. In this case, the Get-ChildItem command is used to find a non-existent file. ```powershell -PS> \$ErrorView # Verify the value. +PS> $ErrorView # Verify the value. NormalView PS> get-childitem nofile.txt # Find a non-existent file. @@ -475,7 +475,7 @@ This example shows how the same error appears when the value of \$ErrorView is CategoryView. ```powershell -PS> \$ErrorView = "CategoryView" # Change the value to +PS> $ErrorView = "CategoryView" # Change the value to CategoryView PS> get-childitem nofile.txt @@ -493,7 +493,7 @@ error in the error array (element 0) and formats all of the properties of the error object in a list. ```powershell -PS> \$error[0] | format-list -property * -force +PS> $error[0] | format-list -property * -force Exception : System.Management.Automation.ItemNotFoundException: Cannot find path 'C:\nofile.txt' because it does not exist. @@ -546,10 +546,10 @@ In the resulting display, the list in the Group column is now limited by the line length. In the final command in the example, use the Wrap parameter of Format-Table to display all of the processes in each Status group. -PS> \$formatenumerationlimit # Find the current value +```powershell +PS> $formatenumerationlimit # Find the current value 4 -```powershell PS> # List all services grouped by status PS> get-service | group-object -property status @@ -560,7 +560,7 @@ Count Name Group PS> # The list is truncated after 4 items. PS> # Increase the limit to 1000. -PS> \$formatenumerationlimit = 1000 +PS> $formatenumerationlimit = 1000 PS> get-service | group-object -property status Count Name Group @@ -650,20 +650,20 @@ The Log*Event preference variables are as follows: To enable a Log*Event, type the variable with a value of \$true, for example: ```powershell -\$LogCommandLifeCycleEvent +$LogCommandLifeCycleEvent ``` - or - ```powershell -\$LogCommandLifeCycleEvent = \$true +$LogCommandLifeCycleEvent = $true ``` To disable an event type, type the variable with a value of \$false, for example: ```powershell -\$LogCommandLifeCycleEvent = \$false +$LogCommandLifeCycleEvent = $false ``` The events that you enable are effective only for the current PowerShell @@ -719,26 +719,26 @@ To count the errors on your system, use the Count property of the \$Error array. Type: ```powershell -\$Error.count +$Error.count ``` To display a specific error, use array notation to display the error. For example, to see the most recent error, type: ```powershell -\$Error[0] +$Error[0] ``` To display the oldest retained error, type: ```powershell -\$Error[(\$Error.Count -1] +$Error[($Error.Count -1] ``` To display the properties of the ErrorRecord object, type: ```powershell -\$Error[0] | format-list -property * -force +$Error[0] | format-list -property * -force ``` In this command, the Force parameter overrides the special formatting of @@ -748,11 +748,11 @@ To delete all errors from the error history, use the Clear method of the error array. ```powershell -PS> \$Error.count +PS> $Error.count 17 -PS> \$Error.clear() +PS> $Error.clear() PS> -PS> \$Error.count +PS> $Error.count 0 ``` @@ -844,9 +844,9 @@ is converted to a string. In this case, an array of integers is stored in a variable and then the variable is cast as a string. ```powershell -PS> \$array = 1,2,3 # Store an array of integers. +PS> $array = 1,2,3 # Store an array of integers. -PS> [string]\$array # Cast the array to a string. +PS> [string]$array # Cast the array to a string. 1 2 3 # Spaces separate the elements ``` @@ -854,9 +854,9 @@ To change the separator, add the \$OFS variable by assigning a value to it. To work correctly, the variable must be named \$OFS. ```powershell -PS> \$OFS = "+" # Create \$OFS and assign a "+" +PS> $OFS = "+" # Create $OFS and assign a "+" -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1+2+3 # Plus signs separate the elements ``` @@ -865,10 +865,10 @@ To restore the default behavior, you can assign a space (" ") to the value of verifies that the separator is a space. ```powershell -PS> Remove-Variable OFS # Delete \$OFS +PS> Remove-Variable OFS # Delete $OFS PS> -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1 2 3 # Spaces separate the elements ``` @@ -897,7 +897,7 @@ The first command finds the value of \$OutputEncoding. Because the value is an encoding object, display only its EncodingName property. ```powershell -PS> \$OutputEncoding.EncodingName # Find the current value US-ASCII +PS> $OutputEncoding.EncodingName # Find the current value US-ASCII ``` In this example, a FINDSTR command is used to search for two Chinese @@ -918,9 +918,9 @@ locale selected for Windows. Because OutputEncoding is a static property of the console, use double-colons (::) in the command. ```powershell -PS> \$OutputEncoding = [console]::outputencoding +PS> $OutputEncoding = [console]::outputencoding PS> # Set the value equal to the OutputEncoding property of the console. -PS> \$OutputEncoding.EncodingName +PS> $OutputEncoding.EncodingName OEM United States ``` As a result of this change, the FINDSTR command finds the characters. @@ -1100,7 +1100,7 @@ values you prefer. Save the output in a variable called \$PSSessionOption. For example, ```powershell -\$PSSessionOption = New-PSSessionOption -NoCompression +$PSSessionOption = New-PSSessionOption -NoCompression ``` To use the \$PSSessionOption preference variable in every PowerShell session, @@ -1202,7 +1202,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$VerbosePreference = "Inquire" +PS> $VerbosePreference = "Inquire" PS> Write-Verbose "Verbose message test." VERBOSE: Verbose message test. Confirm @@ -1249,7 +1249,7 @@ value. This example shows the effect of the Continue value, which is the default. ```powershell -PS> \$WarningPreference # Find the current value. +PS> $WarningPreference # Find the current value. Continue PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1263,7 +1263,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value to SilentlyContinue. -PS> \$WarningPreference = "SilentlyContinue" +PS> $WarningPreference = "SilentlyContinue" PS> Write-Warning "This action can delete data." PS> # Write a warning message. @@ -1280,7 +1280,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$WarningPreference = "Inquire" +PS> $WarningPreference = "Inquire" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1299,7 +1299,7 @@ This example shows the effect of the Stop value. ```powershell PS> # Change the value to Stop. -PS> \$WarningPreference = "Stop" +PS> $WarningPreference = "Stop" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1360,7 +1360,7 @@ This example shows the effect of the 0 (not enabled) value, which is the default. ```powershell -PS> \$whatifpreference +PS> $whatifpreference 0 # Check the current value. PS> # Verify that the file exists. @@ -1400,8 +1400,8 @@ Remove-Item to delete a cmdlet, Remove-Item displays the path to the file that it would delete, but it does not delete the file. ```powershell -PS> \$whatifpreference = 1 -PS> \$whatifpreference +PS> $whatifpreference = 1 +PS> $whatifpreference 1 # Change the value. PS> # Try to delete a file. @@ -1417,8 +1417,8 @@ This example shows how to delete a file when the value of \$WhatIfPreference is 1. It uses the WhatIf parameter with a value of \$false. ```powershell -PS> # Use the WhatIf parameter with \$false. -PS> remove-item test.txt -whatif:\$false +PS> # Use the WhatIf parameter with $false. +PS> remove-item test.txt -whatif:$false ``` This example demonstrates that some cmdlets support WhatIf behavior and others @@ -1430,7 +1430,7 @@ a value of \$false. ```powershell PS> # Change the value to 1. -PS> \$whatifpreference = 1 +PS> $whatifpreference = 1 PS> get-process winword A Get-Process command completes. @@ -1443,8 +1443,8 @@ PS> # A Stop-Process command uses WhatIf. PS> stop-process -name winword What if: Performing operation "Stop-Process" on Target "WINWORD (2312)". -PS> stop-process -name winword -whatif:\$false -PS> # WhatIf:\$false overrides the preference. +PS> stop-process -name winword -whatif:$false +PS> # WhatIf:$false overrides the preference. PS> # Verify that the process is stopped. PS> get-process winword diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Prompts.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Prompts.md index 22a263dff4f8..6f1820bea646 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Prompts.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Prompts.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,308 +7,284 @@ title: about_Prompts --- # About Prompts -## about_Prompts - ## SHORT DESCRIPTION -Describes the Prompt function and demonstrates how to create a custom Prompt function. +Describes the Prompt function and demonstrates how to create a custom Prompt +function. ## LONG DESCRIPTION -The Windows PowerShell?command prompt indicates that Windows PowerShell is ready to run a command: +The PowerShell command prompt indicates that PowerShell is ready to run a +command: ``` PS C:\> ``` +The PowerShell prompt is determined by the built-in Prompt function. You can +customize the prompt by creating your own Prompt function and saving it in +your PowerShell profile. -The Windows PowerShell prompt is determined by the built-in Prompt function. You can customize the prompt by creating your own Prompt function and saving it in your Windows PowerShell profile. - +## ABOUT THE PROMPT FUNCTION -### ABOUT THE PROMPT FUNCTION -The Prompt function determines the appearance of the Windows PowerShell prompt. Windows PowerShell comes with a built-in Prompt function, but you can override it by defining your own Prompt function. +The Prompt function determines the appearance of the PowerShell prompt. +PowerShell comes with a built-in Prompt function, but you can override it by +defining your own Prompt function. The Prompt function has the following syntax: - -``` +```powershell function Prompt { } ``` +The Prompt function must return an object. As a best practice, return a string +or an object that is formatted as a string. The maximum recommended length is +80 characters. -The Prompt function must return an object. As a best practice, return a string or an object that is formatted as a string. The maximum recommended length is 80 characters. - -For example, the following prompt function returns a "Hello, World" string followed by a caret (>). +For example, the following prompt function returns a "Hello, World" string +followed by a caret (>). - -``` -PS C:\> function prompt {"Hello, World > "} +```powershell +PS C:\> function prompt {"Hello, World > "} Hello, World > ``` - - ### GETTING THE PROMPT FUNCTION -To get the Prompt function, use the Get-Command cmdlet or use the Get-Item cmdlet in the Function drive. -Functions are commands. So, you can use the Get-Command cmdlet to get functions, including the Prompt function. +To get the Prompt function, use the `Get-Command` cmdlet or use the `Get-Item` +cmdlet in the Function drive. For example: +```powershell +PS C:\> Get-Command Prompt -``` -PS C:\> Get-Command Prompt - -CommandType Name ModuleName ------------ ---- ---------- +CommandType Name ModuleName +----------- ---- ---------- Function prompt ``` - -To get the script that sets the value of the prompt, use the dot method to get the ScriptBlock property of the Prompt function. +To get the script that sets the value of the prompt, use the dot method to get +the ScriptBlock property of the Prompt function. For example: +```powershell +PS C:\> (Get-Command Prompt).ScriptBlock -``` -PS C:\> (Get-Command Prompt).ScriptBlock - -"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -# .Link -# http://go.microsoft.com/fwlink/?LinkID=225750 +"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPr +omptLevel + 1)) " +# .Link +# http://go.microsoft.com/fwlink/?LinkID=225750 # .ExternalHelp System.Management.Automation.dll-help.xml ``` +Like all functions, the Prompt function is stored in the Function: drive. To +display the script that creates the current Prompt function, type: -Like all functions, the Prompt function is stored in the Function: drive. To display the script that creates the current Prompt function, type: - - -``` +```powershell (Get-Item function:prompt).ScriptBlock ``` - ### THE DEFAULT PROMPT -The default prompt appears only when the Prompt function generates an error or does not return an object. -The default Windows PowerShell prompt is: +The default prompt appears only when the Prompt function generates an error or +does not return an object. +The default PowerShell prompt is: ``` PS> ``` +For example, the following command sets the Prompt function to $null, which is +invalid. As a result, the default prompt appears. -For example, the following command sets the Prompt function to $null, which is invalid. As a result, the default prompt appears. - - -``` -PS C:\> function prompt {$null} +```powershell +PS C:\> function prompt {$null} PS> ``` - -Because Windows PowerShell comes with a built-in prompt, you usually do not see the default prompt. - +Because PowerShell comes with a built-in prompt, you usually do not see the +default prompt. ### BUILT-IN PROMPT -Windows PowerShell includes a built-in prompt function. - -In Windows PowerShell 3.0, the built-in prompt function is: - - -``` -function prompt -{ - "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -} -``` - -This simplified prompt starts with "PS" followed by the current location, and one ">" for each nested prompt level. +PowerShell includes a built-in prompt function. -In Windows PowerShell 2.0, the built-in prompt function is: - - -``` -function prompt -{ - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - else { '' }) + 'PS ' + $(Get-Location) ` - + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +```powershell +function prompt { + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + else { '' }) + 'PS ' + $(Get-Location) ` + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +The function uses the Test-Path cmdlet to determine whether the +\$PSDebugContext automatic variable is populated. If \$PSDebugContext is +populated, you are in debugging mode, and "[DBG]" is added to the prompt, as +follows: -The function uses the Test-Path cmdlet to determine whether the $PSDebugContext automatic variable is populated. If $PSDebugContext is populated, you are in debugging mode, and "[DBG]" is added to the prompt, as follows: - - -``` +```Output [DBG] PS C:\ps-test> ``` +If \$PSDebugContext is not populated, the function adds "PS" to the prompt. +And, the function uses the `Get-Location` cmdlet to get the current file +system directory location. Then, it adds a right angle bracket (>). -If $PSDebugContext is not populated, the function adds "PS" to the prompt. And, the function uses the Get-Location cmdlet to get the current file system directory location. Then, it adds a right angle bracket (>). - +For example: -``` -For example: - PS C:\ps-test> +```Output +PS C:\ps-test> ``` +If you are in a nested prompt, the function adds two angle brackets (>>) to +the prompt. (You are in a nested prompt if the value of the +\$NestedPromptLevel automatic variable is greater than 1.) -If you are in a nested prompt, the function adds two angle brackets (>>) to the prompt. (You are in a nested prompt if the value of the $NestedPromptLevel automatic variable is greater than 1.) +For example, when you are debugging in a nested prompt, the prompt resembles +the following prompt: -For example, when you are debugging in a nested prompt, the prompt resembles the following prompt: - - -``` +```Output [DBG] PS C:\ps-test>>> ``` - - ### CHANGES TO THE PROMPT -The Enter-PSSession cmdlet prepends the name of the remote computer to the current Prompt function. When you use the Enter-PSSession cmdlet to start a session with a remote computer, the command prompt changes to include the name of the remote computer. For example: +The Enter-PSSession cmdlet prepends the name of the remote computer to the +current Prompt function. When you use the Enter-PSSession cmdlet to start a +session with a remote computer, the command prompt changes to include the name +of the remote computer. For example: -``` -PS Hello, World> Enter-PSSession Server01 +```Output +PS Hello, World> Enter-PSSession Server01 [Server01]: PS Hello, World> ``` +Other PowerShell host applications and alternate shells might have their own +custom command prompts. -Other Windows PowerShell host applications and alternate shells might have their own custom command prompts. - -For more information about the $PSDebugContext and $NestedPromptLevel automatic variables, see about_Automatic_Variables. - +For more information about the \$PSDebugContext and $NestedPromptLevel +automatic variables, see [about_Automatic_Variables](about_Automatic_Variables.md). ### HOW TO CUSTOMIZE THE PROMPT -To customize the prompt, write a new Prompt function. The function is not protected, so you can overwrite it. -To write a prompt function, type the following: +To customize the prompt, write a new Prompt function. The function is not +protected, so you can overwrite it. +To write a prompt function, type the following: -``` +```powershell function prompt { } ``` - -Then, between the braces, enter the commands or the string that creates your prompt. +Then, between the braces, enter the commands or the string that creates your +prompt. For example, the following prompt includes your computer name: - -``` +```powershell function prompt {"PS [$env:COMPUTERNAME]> "} ``` - On the Server01 computer, the prompt resembles the following prompt: - -``` +```Output PS [Server01] > ``` - The following prompt function includes the current date and time: - -``` +```powershell function prompt {"$(get-date)> "} ``` - The prompt resembles the following prompt: - -``` +```Output 03/15/2012 17:49:47> ``` - You can also change the default Prompt function: -For example, the following modified Prompt function adds "[ADMIN]:" to the built-in Windows PowerShell prompt when Windows PowerShell is opened by using the "Run as administrator" option: - - -``` -function prompt -{ - $identity = [Security.Principal.WindowsIdentity]::GetCurrent() - $principal = [Security.Principal.WindowsPrincipal] $identity - - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - - elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) - { "[ADMIN]: " } - - else { '' }) + 'PS ' + $(Get-Location) + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +For example, the following modified Prompt function adds "[ADMIN]:" to the +built-in PowerShell prompt when PowerShell is opened by using the "Run as +administrator" option: + +```powershell +function prompt { + $identity = [Security.Principal.WindowsIdentity]::GetCurrent() + $principal = [Security.Principal.WindowsPrincipal] $identity + + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] + "Administrator")) { "[ADMIN]: " } + else { '' } + ) + 'PS ' + $(Get-Location) + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +When you start PowerShell by using the "Run as administrator" option, a prompt +that resembles the following prompt appears: -When you start Windows PowerShell by using the "Run as administrator" option, a prompt that resembles the following prompt appears: - - -``` +```Output [ADMIN]: PS C:\ps-test> ``` +The following Prompt function displays the history ID of the next command. To +view the command history, use the `Get-History` cmdlet. -The following Prompt function displays the history ID of the next command. To view the command history, use the Get-History cmdlet. - +```powershell +function prompt { + # The at sign creates an array in case only one history item exists. + $history = @(get-history) + if($history.Count -gt 0) + { + $lastItem = $history[$history.Count - 1] + $lastId = $lastItem.Id + } -``` -function prompt -{ - # The at sign creates an array in case only one history item exists. - $history = @(get-history) - if($history.Count -gt 0) - { - $lastItem = $history[$history.Count - 1] - $lastId = $lastItem.Id - } - - $nextCommand = $lastId + 1 - $currentDirectory = get-location - "PS: $nextCommand $currentDirectory >" + $nextCommand = $lastId + 1 + $currentDirectory = get-location + "PS: $nextCommand $currentDirectory >" } ``` +The following prompt uses the Write-Host and Get-Random cmdlets to create a +prompt that changes color randomly. Because `Write-Host` writes to the current +host application but does not return an object, this function includes a +Return statement. Without it, PowerShell uses the default prompt, "PS>". -The following prompt uses the Write-Host and Get-Random cmdlets to create a prompt that changes color randomly. Because Write-Host writes to the current host application but does not return an object, this function includes a Return statement. Without it, Windows PowerShell uses the default prompt, "PS>". - - -``` -function prompt -{ - $color = Get-Random -Min 1 -Max 16 - Write-Host ("PS " + $(Get-Location) +">") -NoNewLine -ForegroundColor $Color - return " " +```powershell +function prompt { + $color = Get-Random -Min 1 -Max 16 + Write-Host ("PS " + $(Get-Location) +">") -NoNewLine ` + -ForegroundColor $Color + return " " } ``` - - ### SAVING THE PROMPT FUNCTION -Like any function, the Prompt function exists only in the current session. To save the Prompt function for future sessions, add it to your Windows PowerShell profiles. For more information about profiles, see about_Profiles. +Like any function, the Prompt function exists only in the current session. To +save the Prompt function for future sessions, add it to your PowerShell +profiles. For more information about profiles, see about_Profiles. ## SEE ALSO -Get-Location +[Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) -Enter-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Get-History +[Get-History](../Get-History.md) -Get-Random +[Get-Random](../../Microsoft.PowerShell.Utility/Get-Random.md) -Write-Host +[Write-Host](../../Microsoft.PowerShell.Utility/Write-Host.md) [about_Profiles](about_Profiles.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md index af9999f5f30a..7933f7f0a80e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md @@ -1,93 +1,87 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -title: about_packagemanagement +title: about_PackageManagement --- # About PackageManagement -## about_PackageManagement -# TOPIC -about_PackageManagement - -# SHORT DESCRIPTION +## SHORT DESCRIPTION PackageManagement is an aggregator for software package managers. -# LONG DESCRIPTION +## LONG DESCRIPTION PackageManagement functionality was introduced in Windows PowerShell 5.0. -PackageManagement is a unified interface for software package management systems; you -can run PackageManagement cmdlets to perform software discovery, installation, and -inventory (SDII) tasks. Regardless of the underlying installation technology, -you can run the common cmdlets in the PackageManagement module to search for, -install, or uninstall packages; add, remove, and query package repositories; and -run queries on a computer to determine which software packages are installed. - -PackageManagement supports a flexible plug-in model that enables support for other -software package management systems. - -The PackageManagement module is included with Windows PowerShell 5.0 and later releases -of Windows PowerShell, and works on three levels of package management -structure: package providers, package sources, and the packages themselves. - -Term Description ----------- ------------------------------ -Package manager Software package management system. In -PackageManagement terms, this is a package provider. -Package provider PackageManagement term for a package manager. Examples -can include Windows Installer, Chocolatey, -and others. -Package source A URL, local folder, or network shared folder that -you configure package providers to use as a -repository. -Package A piece of software that a package provider manages, -and that is stored in a specific package source. - -The PackageManagement module includes the following cmdlets. You can find the -Help for these cmdlets on TechNet starting on the following page: -http://technet.microsoft.com/library/dn890951(v=wps.640).aspx. - -Cmdlet Description ----------- ------------------------------ -Get-PackageProvider Returns a list of package providers that are -connected to PackageManagement. -Get-PackageSource Gets a list of package sources that are -registered for a package provider. -Register-PackageSource Adds a package source for a specified -package provider. -Set-PackageSource Sets properties on an existing package -source. -Unregister-PackageSource Removes a registered package source. -Get-Package Returns a list of installed software -packages. -Find-Package Finds software packages in available -package sources. -Install-Package Installs one or more software packages. -Save-Package Saves packages to the local computer -without installing them. -Uninstall-Package Uninstalls one or more software packages. - -PackageManagement Package Provider Bootstrapping and Dynamic Cmdlet Parameters - -By default, PackageManagement ships with a core bootstrap provider. You can install -additional package providers as you need them by bootstrapping the providers; -that is, responding to a prompt to install the provider automatically, from a -web service. You can specify a package provider with any PackageManagement cmdlet; -if the specified provider is not available, PackageManagement prompts you to bootstrap ---or automatically install--the provider. In the following examples, if the -Chocolatey provider is not already installed, PackageManagement bootstrapping installs -the provider. - +PackageManagement is a unified interface for software package management +systems; you can run PackageManagement cmdlets to perform software discovery, +installation, and inventory (SDII) tasks. Regardless of the underlying +installation technology, you can run the common cmdlets in the +PackageManagement module to search for, install, or uninstall packages; add, +remove, and query package repositories; and run queries on a computer to +determine which software packages are installed. + +PackageManagement supports a flexible plug-in model that enables support for +other software package management systems. + +The PackageManagement module is included with Windows PowerShell 5.0 and later +releases of Windows PowerShell, and works on three levels of package +management structure: package providers, package sources, and the packages +themselves. Let us define some terms: + +- Package manager: Software package management system. In PackageManagement + terms, this is a package provider. +- Package provider: PackageManagement term for a package manager. Examples can + include Windows Installer, Chocolatey, and others. +- Package source: A URL, local folder, or network shared folder that you + configure package providers to use as a repository. +- Package: A piece of software that a package provider manages, and that is + stored in a specific package source. + +The PackageManagement module includes the following cmdlets. For more +information, see the +[PackageManagement](/powershell/gallery/psget/oneget/packagemanagement_cmdlets) +help. + +- `Get-PackageProvider`: Returns a list of package providers that are + connected to PackageManagement. +- `Get-PackageSource`: Gets a list of package sources that are registered for + a package provider. +- `Register-PackageSource`: Adds a package source for a specified package + provider. +- `Set-PackageSource`: Sets properties on an existing package source. +- `Unregister-PackageSource`: Removes a registered package source. +- `Get-Package`: Returns a list of installed software packages. +- `Find-Package`: Finds software packages in available package sources. +- `Install-Package`: Installs one or more software packages. +- `Save-Package`: Saves packages to the local computer without installing + them. +- `Uninstall-Package`: Uninstalls one or more software packages. + +### Package Provider Bootstrapping and Dynamic Cmdlet Parameters + +By default, PackageManagement ships with a core bootstrap provider. You can +install additional package providers as you need them by bootstrapping the +providers; that is, responding to a prompt to install the provider +automatically, from a web service. You can specify a package provider with any +PackageManagement cmdlet; if the specified provider is not available, +PackageManagement prompts you to bootstrap (or automatically install) the +provider. In the following examples, if the Chocolatey provider is not already +installed, PackageManagement bootstrapping installs the provider. + +```powershell Find-Package -Provider Chocolatey +``` If the Chocolatey provider is not already installed, when you run the preceding command, you are prompted to install it. +```powershell Install-Package -ForceBootstrap +``` If the Chocolatey provider is not already installed, when you run the preceding command, the provider is installed; but because the ForceBootstrap @@ -99,10 +93,10 @@ provider installed, and you do not add the ForceBootstrap parameter to your command, PackageManagement prompts you to install the provider. Specifying a package provider in your PackageManagement command can make -dynamic parameters available that are specific to that package provider. -When you run Get-Help for a specific PackageManagement cmdlet, a list of -parameter sets are returned, grouping dynamic parameters for available -package providers in separate parameter sets. +dynamic parameters available that are specific to that package provider. When +you run Get-Help for a specific PackageManagement cmdlet, a list of parameter +sets are returned, grouping dynamic parameters for available package providers +in separate parameter sets. More Information About the PackageManagement Project @@ -131,4 +125,3 @@ Install-Package Save-Package Uninstall-Package - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_pipelines.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_pipelines.md index 1ae1a64986f8..97cd9535c505 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_pipelines.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_pipelines.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,41 +7,39 @@ title: about_pipelines --- # About Pipelines -## about_Pipelines - - ### Short Description -Combining commands into pipelines in the Windows PowerShell +Combining commands into pipelines in the PowerShell ### Long Description -A pipeline is a series of commands connected by pipeline operators -(`|`)(ASCII 124). Each pipeline operator sends the results of the preceding -command to the next command. +A pipeline is a series of commands connected by pipeline operators (`|`) +(ASCII 124). Each pipeline operator sends the results of the preceding command +to the next command. -You can use pipelines to send the objects that are output by one command -to be used as input to another command for processing. And you can send the -output of that command to yet another command. The result is a very powerful -command chain or "pipeline" that is comprised of a series of simple commands. +You can use pipelines to send the objects that are output by one command to be +used as input to another command for processing. And you can send the output +of that command to yet another command. The result is a very powerful command +chain or "pipeline" that is comprised of a series of simple commands. For example, + ```powershell Command-1 | Command-2 | Command-3 ``` In this example, the objects that `Command-1` emits are sent to `Command-2`. -`Command-2` processes the objects and sends them to `Command-3`. `Command-3` processes -the objects and send them down the pipeline. Because there are no more commands in -the pipeline, the results are displayed at the console. +`Command-2` processes the objects and sends them to `Command-3`. `Command-3` +processes the objects and send them down the pipeline. Because there are no +more commands in the pipeline, the results are displayed at the console. -In a pipeline, the commands are processed from left to right in the order -that they appear. The processing is handled as a single operation and -output is displayed as it is generated. +In a pipeline, the commands are processed from left to right in the order that +they appear. The processing is handled as a single operation and output is +displayed as it is generated. -Here is a simple example. The following command gets the Notepad process -and then stops it. +Here is a simple example. The following command gets the Notepad process and +then stops it. For example, ```powershell @@ -49,77 +47,69 @@ Get-Process notepad | Stop-Process ``` The first command uses the `Get-Process` cmdlet to get an object representing -the Notepad process. It uses a pipeline operator (`|`) to send the process object -to the `Stop-Process` cmdlet, which stops the Notepad process. Notice that the -`Stop-Process` command does not have a Name or ID parameter to specify the process, -because the specified process is submitted through the pipeline. +the Notepad process. It uses a pipeline operator (`|`) to send the process +object to the `Stop-Process` cmdlet, which stops the Notepad process. Notice +that the `Stop-Process` command does not have a Name or ID parameter to +specify the process, because the specified process is submitted through the +pipeline. Here is a practical example. This command pipeline gets the text files in the -current directory, selects only the files that are more than 10,000 bytes long, -sorts them by length, and displays the name and length of each file in a table. +current directory, selects only the files that are more than 10,000 bytes +long, sorts them by length, and displays the name and length of each file in a +table. ```powershell Get-ChildItem -Path *.txt | Where-Object {$_.length -gt 10000} | Sort-Object -Property length | Format-Table -Property name, length ``` -This pipeline is comprised of four commands in the specified order. The command -is written horizontally, but we will show the process vertically in the following -graphic. +This pipeline is comprised of four commands in the specified order. The +command is written horizontally, but we will show the process vertically in +the following graphic. `Get-ChildItem` `-Path` *.txt - **|** - -| (FileInfo objects ) -| ( .txt ) - - **|** - - **V** +``` +| +| (FileInfo objects for *.txt) +| +V +``` `Where-Object` {$_.length `-gt` 10000} - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| +V +``` `Sort-Object` `-Property` Length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| +V +``` `Format-Table` `-Property` name, length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) -| (Formatted in a table ) - - **|** - - **V** - ``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| ( Formatted in a table ) +| +V +``` + +```output Name Length ---- ------ tmp1.txt 82920 @@ -129,13 +119,13 @@ tmp3.txt 114000 ### Using Pipelines +The PowerShell cmdlets were designed to be used in pipelines. For example, you +can usually pipe the results of a Get cmdlet to an action cmdlet (such as a +Set, Start, Stop, or Rename cmdlet) for the same noun. -The Windows PowerShell cmdlets were designed to be used in pipelines. For example, -you can usually pipe the results of a Get cmdlet to an action cmdlet (such as a Set, -Start, Stop, or Rename cmdlet) for the same noun. - -For example, you can pipe any service from the `Get-Service` cmdlet to the `Start-Service` -or `Stop-Service` cmdlets (although disabled services cannot be restarted in this way). +For example, you can pipe any service from the `Get-Service` cmdlet to the +`Start-Service` or `Stop-Service` cmdlets (although disabled services cannot +be restarted in this way). This command pipeline starts the WMI service on the computer: @@ -144,90 +134,98 @@ For example, Get-Service wmi | Start-Service ``` -The cmdlets that get and set objects of the Windows PowerShell providers, such as the +The cmdlets that get and set objects of the PowerShell providers, such as the Item and ItemProperty cmdlets, are also designed to be used in pipelines. -For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` command in the -Windows PowerShell registry provider to the `New-ItemProperty` cmdlet. This command adds -a new registry entry, NoOfEmployees, with a value of 8124, to the MyCompany registry key. +For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` +command in the PowerShell registry provider to the `New-ItemProperty` cmdlet. +This command adds a new registry entry, NoOfEmployees, with a value of 8124, +to the MyCompany registry key. For example, ```powershell -Get-Item -Path HKLM:\Software\MyCompany | New-ItemProperty -Name NoOfEmployees -Value 8124 +Get-Item -Path HKLM:\Software\MyCompany | + New-ItemProperty -Name NoOfEmployees -Value 8124 ``` -Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, `Sort-Object`, `Group-Object`, -and `Measure-Object` are used almost exclusively in pipelines. You can pipe any objects to -these cmdlets. +Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, +`Sort-Object`, `Group-Object`, and `Measure-Object` are used almost +exclusively in pipelines. You can pipe any objects to these cmdlets. -For example, you can pipe all of the processes on the computer to the `Sort-Object` command -and have them sorted by the number of handles in the process. +For example, you can pipe all of the processes on the computer to the +`Sort-Object` command and have them sorted by the number of handles in the +process. For example, + ```powershell Get-Process | Sort-Object -Property handles ``` -Also, you can pipe any objects to the formatting cmdlets, such as `Format-List` and -`Format-Table`, the Export cmdlets, such as `Export-Clixml` and `Export-CSV`, and the Out -cmdlets, such as `Out-Printer`. +Also, you can pipe any objects to the formatting cmdlets, such as +`Format-List` and `Format-Table`, the Export cmdlets, such as `Export-Clixml` +and `Export-CSV`, and the Out cmdlets, such as `Out-Printer`. -For example, you can pipe the Winlogon process to the `Format-List` cmdlet to display all -of the properties of the process in a list. +For example, you can pipe the Winlogon process to the `Format-List` cmdlet to +display all of the properties of the process in a list. For example, + ```powershell Get-Process winlogon | Format-List -Property * ``` -With a bit of practice, you'll find that combining simple commands into pipelines -saves time and typing, and makes your scripting more efficient. +With a bit of practice, you'll find that combining simple commands into +pipelines saves time and typing, and makes your scripting more efficient. ### How Pipelines Work +When you "pipe" objects, that is send the objects in the output of one command +to another command, PowerShell tries to associate the piped objects with one +of the parameters of the receiving cmdlet. -When you "pipe" objects, that is send the objects in the output of one command to another -command, Windows PowerShell tries to associate the piped objects with one of the parameters -of the receiving cmdlet. - -To do so, the Windows PowerShell "parameter binding" component, which associates input objects -with cmdlet parameters, tries to find a parameter that meets the following criteria: +To do so, the PowerShell "parameter binding" component, which associates input +objects with cmdlet parameters, tries to find a parameter that meets the +following criteria: - The parameter must accept input from a pipeline (not all do) -- The parameter must accept the type of object being sent or a type that the object -can be converted to. +- The parameter must accept the type of object being sent or a type that the + object can be converted to. - The parameter must not already be used in the command. -For example, the `Start-Service` cmdlet has many parameters, but only two of them, `-Name` and `-InputObject` -accept pipeline input. The `-Name` parameter takes strings and the `-InputObject` parameter takes -service objects. Therefore, you can pipe strings and service objects (and objects with properties -that can be converted to string and service objects) to `Start-Service`. +For example, the `Start-Service` cmdlet has many parameters, but only two of +them, `-Name` and `-InputObject` accept pipeline input. The `-Name` parameter +takes strings and the `-InputObject` parameter takes service objects. +Therefore, you can pipe strings and service objects (and objects with +properties that can be converted to string and service objects) to +`Start-Service`. -If the parameter binding component of Windows PowerShell cannot associate the piped objects -with a parameter of the receiving cmdlet, the command fails and Windows PowerShell prompts you -for the missing parameter values. +If the parameter binding component of PowerShell cannot associate the piped +objects with a parameter of the receiving cmdlet, the command fails and +PowerShell prompts you for the missing parameter values. -You cannot force the parameter binding component to associate the piped objects with a particular -parameter -- you cannot even suggest a parameter. Instead, the logic of the component manages -the piping as efficiently as possible. +You cannot force the parameter binding component to associate the piped +objects with a particular parameter. You cannot even suggest a parameter. +Instead, the logic of the component manages the piping as efficiently as +possible. ### One-At-A-Time Processing +Piping objects to a command is much like using a parameter of the command to +submit the objects. -Piping objects to a command is much like using a parameter of the command to submit the -objects. - -For example, piping objects representing the services on the computer to a `Format-Table` command, -such as: +For example, piping objects representing the services on the computer to a +`Format-Table` command, such as: ```powershell Get-Service | Format-Table -Property name, dependentservices ``` -is much like saving the service objects in a variable and using the InputObject parameter -of `Format-Table` to submit the service object. +is much like saving the service objects in a variable and using the +InputObject parameter of `Format-Table` to submit the service object. For example, + ```powershell $services = Get-Service Format-Table -InputObject $services -Property name, dependentservices @@ -236,51 +234,58 @@ Format-Table -InputObject $services -Property name, dependentservices or imbedding the command in the parameter value For example, + ```powershell -Format-Table -InputObject (Get-Service wmi) -Property name, dependentservices +Format-Table -InputObject (Get-Service wmi) -Property name,dependentservices ``` -However, there is an important difference. When you pipe multiple objects to a command, -Windows PowerShell sends the objects to the command one at a time. When you use a -command parameter, the objects are sent as a single array object. +However, there is an important difference. When you pipe multiple objects to a +command, PowerShell sends the objects to the command one at a time. When you +use a command parameter, the objects are sent as a single array object. + +This seemingly technical difference can have interesting, and sometimes +useful, consequences. -This seemingly technical difference can have interesting, and sometimes useful, consequences. +For example, if you pipe multiple process objects from the `Get-Process` +cmdlet to the `Get-Member` cmdlet, PowerShell sends each process object, one +at a time, to `Get-Member`. `Get-Member` displays the .NET class (type) of the +process objects, and their properties and methods. -For example, if you pipe multiple process objects from the `Get-Process` cmdlet to the -`Get-Member` cmdlet, Windows PowerShell sends each process object, one at a time, to `Get-Member`. -`Get-Member` displays the .NET class (type) of the process objects, and their properties and methods. -(`Get-Member` eliminates duplicates, so if the objects are all of the same type, it displays only -one object type.) +NOTE: `Get-Member` eliminates duplicates, so if the objects are all of the +same type, it displays only one object type. -In this case, `Get-Member` displays the properties and methods of each process object, that is, a -System.Diagnostics.Process object. +In this case, `Get-Member` displays the properties and methods of each process +object, that is, a System.Diagnostics.Process object. For example, + ```powershell Get-Process | Get-Member ``` -``` +```Output TypeName: System.Diagnostics.Process -Name MemberType Definition ----- ---------- ---------- -Handles AliasProperty Handles = Handlecount -Name AliasProperty Name = ProcessName -NPM AliasProperty NPM = NonpagedSystemMemorySize +Name MemberType Definition +---- ---------- ---------- +Handles AliasProperty Handles = Handlecount +Name AliasProperty Name = ProcessName +NPM AliasProperty NPM = NonpagedSystemMemorySize ... ``` -However, if you use the InputObject parameter of `Get-Member`, then `Get-Member` receives an -array of System.Diagnostics.Process objects as a single unit, and it displays the properties -of an array of objects. (Note the array symbol ([]) after the System.Object type name.) +However, if you use the InputObject parameter of `Get-Member`, then +`Get-Member` receives an array of System.Diagnostics.Process objects as a +single unit, and it displays the properties of an array of objects. (Note the +array symbol ([]) after the System.Object type name.) For example, + ```powershell Get-Member -InputObject (Get-Process) ``` -``` +```Output TypeName: System.Object[] Name MemberType Definition @@ -291,30 +296,32 @@ Clone Method System.Object Clone() ... ``` -This result might not be what you intended, but after you understand it, you can use it. For -example, an array of process objects has a Count property that you can use to count the number -of processes on the computer. +This result might not be what you intended, but after you understand it, you +can use it. For example, an array of process objects has a Count property that +you can use to count the number of processes on the computer. For example, + ```powershell (Get-Process).count ``` -This distinction can be important, so remember that when you pipe objects to a cmdlet, they -are delivered one at a time. +This distinction can be important, so remember that when you pipe objects to a +cmdlet, they are delivered one at a time. ### Accepts Pipeline Input -In order to receive objects in a pipeline, the receiving cmdlet must have a parameter -that accepts pipeline input. You can use a `Get-Help` command with the **Full** or **Parameter** -parameters to determine which, if any, of a cmdlet's parameters accepts pipeline input. +In order to receive objects in a pipeline, the receiving cmdlet must have a +parameter that accepts pipeline input. You can use a `Get-Help` command with +the **Full** or **Parameter** parameters to determine which, if any, of a +cmdlet's parameters accepts pipeline input. -In the `Get-Help` default display, the "Accept pipeline input?" item appears in a table -of parameter attributes. This table is displayed only when you use the **Full** or **Parameter** -parameters of the `Get-Help` cmdlet. +In the `Get-Help` default display, the "Accept pipeline input?" item appears +in a table of parameter attributes. This table is displayed only when you use +the **Full** or **Parameter** parameters of the `Get-Help` cmdlet. -For example, to determine which of the parameters of the `Start-Service` cmdlet accepts -pipeline input, type: +For example, to determine which of the parameters of the `Start-Service` +cmdlet accepts pipeline input, type: ```powershell Get-Help Start-Service -Full @@ -326,108 +333,115 @@ or Get-Help Start-Service -Parameter * ``` -For example, the help for the `Start-Service` cmdlet shows that the **InputObject** and **Name** -parameters accept pipeline input ("true"). All other parameters have a value of "false" -in the "Accept pipeline input?" row. +For example, the help for the `Start-Service` cmdlet shows that the +**InputObject** and **Name** parameters accept pipeline input ("true"). All +other parameters have a value of "false" in the "Accept pipeline input?" row. ``` -InputObject - Specifies ServiceController objects representing the services to be started. - Enter a variable that contains the objects, or type a command or expression - that gets the objects. +Specifies ServiceController objects representing the services to be started. +Enter a variable that contains the objects, or type a command or expression +that gets the objects. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByValue) +Accept wildcard characters? false -Name - Specifies the service names for the service to be started. +Specifies the service names for the service to be started. - The parameter name is optional. You can use Name or its alias, ServiceName, - or you can omit the parameter name. +The parameter name is optional. You can use Name or its alias, ServiceName, +or you can omit the parameter name. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByPropertyName, ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByPropertyName, ByValue) +Accept wildcard characters? false ``` This means that you can send objects (PsObjects) through the pipeline to the -`Where-Object` cmdlet and Windows PowerShell will associate the object with the +`Where-Object` cmdlet and PowerShell will associate the object with the **InputObject** and **Name** parameters. ### Methods Of Accepting Pipeline Input - Cmdlets parameters can accept pipeline input in one of two different ways: - ByValue: Parameters that accept input "by value" can accept piped objects -that have the same .NET type as their parameter value or objects that can be -converted to that type. - -For example, the Name parameter of `Start-Service` accepts pipeline input -by value. It can accept string objects or objects that can be converted to -strings. + that have the same .NET type as their parameter value or objects that can be + converted to that type. -- ByPropertyName: Parameters that accept input "by property name" can accept piped -objects only when a property of the object has the same name as the parameter. + For example, the Name parameter of `Start-Service` accepts pipeline input by + value. It can accept string objects or objects that can be converted to + strings. -For example, the Name parameter of `Start-Service` can accept objects that have -a Name property. +- ByPropertyName: Parameters that accept input "by property name" can accept + piped objects only when a property of the object has the same name as the + parameter. -(To list the properties of an object, pipe it to `Get-Member`.) + For example, the Name parameter of `Start-Service` can accept objects that + have a Name property. To list the properties of an object, pipe it to + `Get-Member`. -Some parameters can accept objects by value or by property name. These parameters are -designed to take input from the pipeline easily. +Some parameters can accept objects by value or by property name. These +parameters are designed to take input from the pipeline easily. ### Investigating Pipeline Errors - -If a command fails because of a pipeline error, you can investigate the failure and -rewrite the command. +If a command fails because of a pipeline error, you can investigate the +failure and rewrite the command. For example, the following command tries to move a registry entry from one -registry key to another by using the `Get-Item` cmdlet to get the destination path and -then piping the path to the `Move-ItemProperty` cmdlet. +registry key to another by using the `Get-Item` cmdlet to get the destination +path and then piping the path to the `Move-ItemProperty` cmdlet. -Specifically, the command uses the `Get-Item` cmdlet to get the destination path. It uses -a pipeline operator to send the result to the `Move-ItemProperty` cmdlet. The `Move-ItemProperty` -command specifies the current path and name of the registry entry to be moved. +Specifically, the command uses the `Get-Item` cmdlet to get the destination +path. It uses a pipeline operator to send the result to the +`Move-ItemProperty` cmdlet. The `Move-ItemProperty` command specifies the +current path and name of the registry entry to be moved. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product ``` -``` -The command fails and Windows PowerShell displays the following error +The command fails and PowerShell displays the following error message: -Move-ItemProperty : The input object cannot be bound to any parameters for the -command either because the command does not take pipeline input or the input -and its properties do not match any of the parameters that take pipeline input. +```output +Move-ItemProperty : The input object cannot be bound to any parameters for +the command either because the command does not take pipeline input or the +input and its properties do not match any of the parameters that take +pipeline input. At line:1 char:23 -+ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name product ++ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name p ``` -To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding component of -Windows PowerShell. The following command traces the Parameter Binding component while the -command is processing. It uses the `-PSHost` parameter to display the results at the console -and the `-filepath` command to send them to the debug.txt file for later reference. +To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding +component of PowerShell. The following command traces the Parameter Binding +component while the command is processing. It uses the `-PSHost` parameter to +display the results at the console and the `-filepath` command to send them to +the debug.txt file for later reference. For example, + ```powershell -Trace-Command -Name parameterbinding -Expression {Get-Item -Path HKLM:\software\mycompany\sales | -Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} -PSHost -FilePath debug.txt +Trace-Command -Name parameterbinding -Expression { + Get-Item -Path HKLM:\software\mycompany\sales | + Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} ` + -PSHost -FilePath debug.txt ``` -The results of the trace are lengthy, but they show the values being bound to the `Get-Item` cmdlet -and then the named values being bound to the `Move-ItemProperty` cmdlet. +The results of the trace are lengthy, but they show the values being bound to +the `Get-Item` cmdlet and then the named values being bound to the +`Move-ItemProperty` cmdlet. +``` ... BIND NAMED cmd line args [`Move-ItemProperty`] @@ -442,31 +456,35 @@ BIND arg [product] to parameter [Name] BIND POSITIONAL cmd line args [`Move-ItemProperty`] ... +``` -Finally, it shows that the attempt to bind the path to the Destination parameter -of `Move-ItemProperty` failed. +Finally, it shows that the attempt to bind the path to the **Destination** +parameter of `Move-ItemProperty` failed. +``` ... BIND PIPELINE object to parameters: [`Move-ItemProperty`] PIPELINE object TYPE = [Microsoft.Win32.RegistryKey] RESTORING pipeline parameter's original values -Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION -Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION +Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO CO +ERCION +Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COE +RCION ... +``` - -To investigate the failure, use the `Get-Help` cmdlet to view the attributes of the -**Destination** parameter. The following command gets detailed information about the -**Destination** parameter. +To investigate the failure, use the `Get-Help` cmdlet to view the attributes +of the **Destination** parameter. The following command gets detailed +information about the **Destination** parameter. ```powershell Get-Help Move-ItemProperty -Parameter Destination ``` -The results show that **Destination** takes pipeline input only "by property name". -That is, the piped object must have a property named Destination. +The results show that **Destination** takes pipeline input only "by property +name". That is, the piped object must have a property named Destination. ``` -Destination @@ -479,11 +497,12 @@ That is, the piped object must have a property named Destination. Accept wildcard characters? false ``` -To see the properties of the object being piped to the `Move-ItemProperty` cmdlet, -pipe it to the `Get-Member` cmdlet. The following command pipes the results of the -first part of the command to the `Get-Member` cmdlet. +To see the properties of the object being piped to the `Move-ItemProperty` +cmdlet, pipe it to the `Get-Member` cmdlet. The following command pipes the +results of the first part of the command to the `Get-Member` cmdlet. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Get-Member ``` @@ -491,11 +510,13 @@ Get-Item -Path HKLM:\software\mycompany\sales | Get-Member The output shows that the item is a Microsoft.Win32.RegistryKey that does not have a Destination property. That explains why the command failed. -To fix the command, we must specify the destination in the `Move-ItemProperty` cmdlet. We can -use a `Get-ItemProperty` command to get the path, but the name and destination must be specified -in the `Move-ItemProperty` part of the command. +To fix the command, we must specify the destination in the `Move-ItemProperty` +cmdlet. We can use a `Get-ItemProperty` command to get the path, but the name +and destination must be specified in the `Move-ItemProperty` part of the +command. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\design | Move-ItemProperty -Dest HKLM:\software\mycompany\design -Name product @@ -510,9 +531,11 @@ Get-Itemproperty HKLM:\software\mycompany\sales The results show that the Product registry entry was moved to the Sales key. -``` -PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany\sales -PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany +```Output +PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany\sales +PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany PSChildName : sales PSDrive : HKLM PSProvider : Microsoft.PowerShell.Core\Registry @@ -528,4 +551,3 @@ Product : 18 [about_command_syntax](about_command_syntax.md) [about_foreach](about_foreach.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_profiles.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_profiles.md index b7eabd81d0ce..eea0dd9f0d50 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_profiles.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_profiles.md @@ -1,104 +1,99 @@ --- -ms.date: 2017-06-25 +ms.date: 2017-11-30 schema: 2.0.0 keywords: powershell,cmdlet title: about_Profiles --- # About Profiles -## about_Profiles +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Describes how to create and use a PowerShell profile. -Describes how to create and use a Windows PowerShell profile. +## LONG DESCRIPTION -# LONG DESCRIPTION +You can create a PowerShell profile to customize your environment and to add +session-specific elements to every PowerShell session that you start. -You can create a Windows PowerShell profile to customize your environment -and to add session-specific elements to every Windows PowerShell session -that you start. +A PowerShell profile is a script that runs when PowerShell starts. You can use +the profile as a logon script to customize the environment. You can add +commands, aliases, functions, variables, snap-ins, modules, and PowerShell +drives. You can also add other session-specific elements to your profile so +they are available in every session without having to import or re-create +them. -A Windows PowerShell profile is a script that runs when Windows PowerShell -starts. You can use the profile as a logon script to customize the -environment. You can add commands, aliases, functions, variables, snap-ins, -modules, and Windows PowerShell drives. You can also add other -session-specific elements to your profile so they are available in every -session without having to import or re-create them. +PowerShell supports several profiles for users and host programs. However, it +does not create the profiles for you. This topic describes the profiles, and +it describes how to create and maintain profiles on your computer. -Windows PowerShell supports several profiles for users and host programs. -However, it does not create the profiles for you. This topic describes the -profiles, and it describes how to create and maintain profiles on your -computer. +It explains how to use the **NoProfile** parameter of the PowerShell console +(PowerShell.exe) to start PowerShell without any profiles. And, it explains +the effect of the PowerShell execution policy on profiles. -It explains how to use the **NoProfile** parameter of the Windows PowerShell -console (PowerShell.exe) to start Windows PowerShell without any profiles. -And, it explains the effect of the Windows PowerShell execution policy on -profiles. +## THE PROFILE FILES -# THE PROFILE FILES +PowerShell supports several profile files. Also, PowerShell host programs can +support their own host-specific profiles. - -Windows PowerShell supports several profile files. Also, Windows PowerShell -host programs can support their own host-specific profiles. - -For example, the Windows PowerShell console supports the following basic +For example, the PowerShell console supports the following basic profile files. The profiles are listed in precedence order. The first profile has the highest precedence. -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Profile.ps1 | -| Current User, All Hosts | $Home\\[My ]Documents\Profile.ps1 | -| All Users, Current Host | $PsHome\Microsoft.PowerShell_profile.ps1 | -| All Users, All Hosts | $PsHome\Profile.ps1 | +|Description | Path | +|--------------------------|------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Profile.ps1 | +|Current User, All Hosts |$Home\\[My ]Documents\\Profile.ps1 | +|All Users, Current Host |$PsHome\Microsoft.PowerShell_profile.ps1 | +|All Users, All Hosts |$PsHome\Profile.ps1 | The profile paths include the following variables: - The `$PsHome` variable, which stores the installation directory for -Windows PowerShell +PowerShell - The `$Home` variable, which stores the current user's home directory -In addition, other programs that host Windows PowerShell can support their -own profiles. For example, Windows PowerShell Integrated Scripting -Environment (ISE) supports the following host-specific profiles. - -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Microsoft.PowerShellISE_profile.ps1 | -| All users, Current Host | $PsHome\Microsoft.PowerShellISE_profile.ps1 | +In addition, other programs that host PowerShell can support their own +profiles. For example, PowerShell Integrated Scripting Environment (ISE) +supports the following host-specific profiles. -In Windows PowerShell Help, the "CurrentUser, Current Host" profile is the profile most -often referred to as "your Windows PowerShell profile". +|Description | Path | +|--------------------------|-------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Microsoft.PowerShellISE_profile.ps1 | +|All users, Current Host |$PsHome\Microsoft.PowerShellISE_profile.ps1| -# THE $PROFILE VARIABLE +In PowerShell Help, the "CurrentUser, Current Host" profile is the profile +most often referred to as "your PowerShell profile". +## THE $PROFILE VARIABLE -The `$Profile` automatic variable stores the paths to the Windows PowerShell -profiles that are available in the current session. +The `$Profile` automatic variable stores the paths to the PowerShell profiles +that are available in the current session. To view a profile path, display the value of the `$Profile` variable. You can also use the `$Profile` variable in a command to represent a path. -The `$Profile` variable stores the path to the "Current User, -Current Host" profile. The other profiles are saved in note properties of -the `$Profile` variable. +The `$Profile` variable stores the path to the "Current User, Current Host" +profile. The other profiles are saved in note properties of the `$Profile` +variable. For example, the `$Profile` variable has the following values in the Windows PowerShell console. -| Name | Description | -| ------------- | ------------- | -| $Profile | Current User, Current Host | -| $Profile.CurrentUserCurrentHost | Current User, Current Host | -| $Profile.CurrentUserAllHosts | Current User, All Hosts | -| $Profile.AllUsersCurrentHost | All Users, Current Host | -| $Profile.AllUsersAllHosts | All Users, All Hosts | +|Name |Description | +|--------------------------------|---------------------------| +|$Profile |Current User, Current Host | +|$Profile.CurrentUserCurrentHost |Current User, Current Host | +|$Profile.CurrentUserAllHosts |Current User, All Hosts | +|$Profile.AllUsersCurrentHost |All Users, Current Host | +|$Profile.AllUsersAllHosts |All Users, All Hosts | -Because the values of the `$Profile` variable change for each user and in -each host application, ensure that you display the values of the -profile variables in each Windows PowerShell host application that you use. +Because the values of the `$Profile` variable change for each user and in each +host application, ensure that you display the values of the profile variables +in each PowerShell host application that you use. To see the current values of the `$Profile` variable, type: @@ -107,24 +102,22 @@ $profile | Get-Member -Type NoteProperty ``` You can use the `$Profile` variable in many commands. For example, the -following command opens the "Current User, Current Host" profile in -Notepad: +following command opens the "Current User, Current Host" profile in Notepad: ```powershell notepad $profile ``` -The following command determines whether an "All Users, All Hosts" profile -has been created on the local computer: +The following command determines whether an "All Users, All Hosts" profile has +been created on the local computer: ```powershell Test-Path -Path $profile.AllUsersAllHosts ``` -# HOW TO CREATE A PROFILE +## HOW TO CREATE A PROFILE - -To create a Windows PowerShell profile, use the following command format: +To create a PowerShell profile, use the following command format: ```powershell if (!(Test-Path -Path )) @@ -132,7 +125,7 @@ if (!(Test-Path -Path )) ``` For example, to create a profile for the current user in the current -Windows PowerShell host application, use the following command: +PowerShell host application, use the following command: ```powershell if (!(Test-Path -Path $profile)) @@ -140,21 +133,18 @@ if (!(Test-Path -Path $profile)) ``` In this command, the If statement prevents you from overwriting an existing -profile. Replace the value of the placeholder with the path +profile. Replace the value of the \ placeholder with the path to the profile file that you want to create. ->Note: To create "All Users" profiles in Windows Vista and later versions ->of Windows, start Windows PowerShell with the "Run as administrator" ->option. - -# HOW TO EDIT A PROFILE +> Note: To create "All Users" profiles in Windows Vista and later versions of +> Windows, start PowerShell with the "Run as administrator" >option. +## HOW TO EDIT A PROFILE -You can open any Windows PowerShell profile in a text editor, such as -Notepad. +You can open any PowerShell profile in a text editor, such as Notepad. -To open the profile of the current user in the current Windows PowerShell -host application in Notepad, type: +To open the profile of the current user in the current PowerShell host +application in Notepad, type: ```powershell notepad $profile @@ -167,106 +157,99 @@ profile for all the users of all the host applications, type: notepad $profile.AllUsersAllHosts ``` -To apply the changes, save the profile file, and then restart Windows -PowerShell. +To apply the changes, save the profile file, and then restart PowerShell. -# HOW TO CHOOSE A PROFILE +## HOW TO CHOOSE A PROFILE +If you use multiple host applications, put the items that you use in all the +host applications into your `$Profile.CurrentUserAllHosts` profile. Put items +that are specific to a host application, such as a command that sets the +background color for a host application, in a profile that is specific to that +host application. -If you use multiple host applications, put the items that you use in all -the host applications into your `$Profile.CurrentUserAllHosts` profile. -Put items that are specific to a host application, such as a command that -sets the background color for a host application, in a profile that is -specific to that host application. - -If you are an administrator who is customizing Windows -PowerShell for many users, follow these guidelines: +If you are an administrator who is customizing Windows PowerShell for many +users, follow these guidelines: - Store the common items in the `$profile.AllUsersAllHosts` profile - - Store items that are specific to a host application in -`$profile.AllUsersCurrentHost` profiles that are specific to the host -application - + `$profile.AllUsersCurrentHost` profiles that are specific to the host + application - Store items for particular users in the user-specific profiles Be sure to check the host application documentation for any special -implementation of Windows PowerShell profiles. - -# HOW TO USE A PROFILE +implementation of PowerShell profiles. +## HOW TO USE A PROFILE -Many of the items that you create in Windows PowerShell and most commands -that you run affect only the current session. When you end the session, -the items are deleted. +Many of the items that you create in PowerShell and most commands that you run +affect only the current session. When you end the session, the items are +deleted. The session-specific commands and items include variables, preference -variables, aliases, functions, commands (except for [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), -and Windows PowerShell snap-ins that you add to the session. +variables, aliases, functions, commands (except for +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), +and PowerShell modules that you add to the session. -To save these items and make them available in all future sessions, add -them to a Windows PowerShell profile. +To save these items and make them available in all future sessions, add them +to a PowerShell profile. -Another common use for profiles is to save frequently-used functions, -aliases, and variables. When you save the items in a profile, you can -use them in any applicable session without re-creating them. +Another common use for profiles is to save frequently-used functions, aliases, +and variables. When you save the items in a profile, you can use them in any +applicable session without re-creating them. -# HOW TO START A PROFILE +## HOW TO START A PROFILE - -When you open the profile file, it is blank. However, you can fill it with -the variables, aliases, and commands that you use frequently. +When you open the profile file, it is blank. However, you can fill it with the +variables, aliases, and commands that you use frequently. Here are a few suggestions to get you started. -- Add commands that make it easy to open your profile. This is especially -useful if you use a profile other than the "Current User, Current Host" -profile. For example, add the following command: +### Add commands that make it easy to open your profile + +This is especially useful if you use a profile other than the "Current User, +Current Host" profile. For example, add the following command: ```powershell function Pro {notepad $profile.CurrentUserAllHosts} ``` -- Add a function that opens Windows PowerShell Help in a compiled HTML -Help file (.chm) +### Add a function that opens PowerShell Help in a compiled HTML + Help file (.chm) ```powershell -function Get-CHM -{ -Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" +function Get-CHM { + Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" } ``` -This function opens the English version of the .chm file. However, you -can replace the language code (0409) to open other versions of the .chm -file. +This function opens the English version of the .chm file. However, you can +replace the language code (0409) to open other versions of the .chm file. -- Add a function that lists the aliases for any cmdlet +### Add a function that lists the aliases for any cmdlet ```powershell -function Get-CmdletAlias ($cmdletname) -{ -Get-Alias | Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | Format-Table -Property Definition, Name -AutoSize +function Get-CmdletAlias ($cmdletname) { + Get-Alias | + Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | + Format-Table -Property Definition, Name -AutoSize } ``` -- Customize your console +### Customize your console ```powershell -function Color-Console -{ -$Host.ui.rawui.backgroundcolor = "white" -$Host.ui.rawui.foregroundcolor = "black" -$hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime -$hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" -$Host.UI.RawUI.WindowTitle = "Windows PowerShell $hostversion ($hosttime)" -Clear-Host +function Color-Console { + $Host.ui.rawui.backgroundcolor = "white" + $Host.ui.rawui.foregroundcolor = "black" + $hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime + $hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" + $Host.UI.RawUI.WindowTitle = "PowerShell $hostversion ($hosttime)" + Clear-Host } Color-Console ``` -- Add a customized Windows PowerShell prompt that includes the computer -name and the current path +### Add a customized PowerShell prompt ```powershell function Prompt @@ -275,18 +258,16 @@ $env:COMPUTERNAME + "\" + (Get-Location) + "> " } ``` -For more information about the Windows PowerShell prompt, see +For more information about the PowerShell prompt, see [about_Prompts](about_Prompts.md). -# THE NOPROFILE PARAMETER +## THE NOPROFILE PARAMETER +To start PowerShell without profiles, use the **NoProfile** parameter of +PowerShell.exe, the program that starts PowerShell. -To start Windows PowerShell without profiles, use the **NoProfile** parameter -of PowerShell.exe, the program that starts Windows PowerShell. - -To begin, open a program that can start Windows PowerShell, such as Cmd.exe -or Windows PowerShell itself. You can also use the Run dialog box in -Windows. +To begin, open a program that can start PowerShell, such as Cmd.exe or +PowerShell itself. You can also use the Run dialog box in Windows. Type: @@ -294,56 +275,58 @@ Type: PowerShell -NoProfile ``` -For a complete list of the parameters of PowerShell.exe, -type: +For a complete list of the parameters of PowerShell.exe, type: ``` PowerShell -? ``` -# PROFILES AND EXECUTION POLICY - +## PROFILES AND EXECUTION POLICY -The Windows PowerShell execution policy determines, in part, whether you -can run scripts and load configuration files, including the profiles. The -"Restricted" execution policy is the default. It prevents all scripts from -running, including the profiles. If you use the "Restricted" policy, the -profile does not run, and its contents are not applied. +The PowerShell execution policy determines, in part, whether you can run +scripts and load configuration files, including the profiles. The "Restricted" +execution policy is the default. It prevents all scripts from running, +including the profiles. If you use the "Restricted" policy, the profile does +not run, and its contents are not applied. A `Set-ExecutionPolicy` command sets and changes your execution policy. It is -one of the few commands that applies in all Windows PowerShell sessions -because the value is saved in the registry. You do not have to set it when -you open the console, and you do not have to store a `Set-ExecutionPolicy` -command in your profile. +one of the few commands that applies in all PowerShell sessions because the +value is saved in the registry. You do not have to set it when you open the +console, and you do not have to store a `Set-ExecutionPolicy` command in your +profile. -# PROFILES AND REMOTE SESSIONS +## PROFILES AND REMOTE SESSIONS +PowerShell profiles are not run automatically in remote sessions, so the +commands that the profiles add are not present in the remote session. In +addition, the `$Profile` automatic variable is not populated in remote +sessions. -Windows PowerShell profiles are not run automatically in remote sessions, -so the commands that the profiles add are not present in the remote session. -In addition, the `$Profile` automatic variable is not populated in remote sessions. +To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) +cmdlet. -To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) cmdlet. - -For example, the following command runs the "Current user, Current Host" profile from -the local computer in the session in $s. +For example, the following command runs the "Current user, Current Host" +profile from the local computer in the session in $s. ```powershell Invoke-Command -Session $s -FilePath $profile ``` -The following command runs the "Current user, Current Host" profile from the remote -computer in the session in $s. Because the `$Profile` variable is not populated, -the command uses the explicit path to the profile. +The following command runs the "Current user, Current Host" profile from the +remote computer in the session in $s. Because the `$Profile` variable is not +populated, the command uses the explicit path to the profile. ```powershell -Invoke-Command -SessionName $s -ScriptBlock {Invoke-Command -FilePath "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +Invoke-Command -SessionName $s -ScriptBlock { +$path = "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +Invoke-Command -FilePath $path +} ``` After running this command, the commands that the profile adds to the session are available in $s. -# SEE ALSO +## SEE ALSO [about_Automatic_Variables](about_Automatic_Variables.md) diff --git a/reference/5.0/Microsoft.PowerShell.Management/Get-Process.md b/reference/5.0/Microsoft.PowerShell.Management/Get-Process.md index ee08cc76c039..4d0e20a661b6 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Get-Process.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Get-Process.md @@ -103,22 +103,23 @@ The pipeline operator passes the objects to the **Format-Table** cmdlet, which f The Priority view, and other views, are defined in the PS1XML format files in the Windows PowerShell home directory ($pshome). ### Example 5: Add a property to the standard Get-Process output display -``` -PS C:\> Get-Process Powershell -ComputerName S1, localhost | ft @{Label="NPM(K)";Expression={[int]($_.NPM/1024)}}, @{Label="PM(K)";Expression={[int]($_.PM/1024)}},@{Label="WS(K)";Expression={[int]($_.WS/1024)}},@{Label="VM(M)";Expression={[int]($_.VM/1MB)}}, @{Label="CPU(s)";Expression={if ($_.CPU -ne $()) { $_.CPU.ToString("N")}}}, Id, MachineName, ProcessName -Auto - - - - - +```powershell +PS C:\> Get-Process powershell -ComputerName S1, localhost | + ft @{Label = "NPM(K)"; Expression = {[int]($_.NPM / 1024)}}, + @{Label = "PM(K)"; Expression = {[int]($_.PM / 1024)}}, + @{Label = "WS(K)"; Expression = {[int]($_.WS / 1024)}}, + @{Label = "VM(M)"; Expression = {[int]($_.VM / 1MB)}}, + @{Label = "CPU(s)"; Expression = {if ($_.CPU) {$_.CPU.ToString("N")}}}, + Id, MachineName, ProcessName -Auto NPM(K) PM(K) WS(K) VM(M) CPU(s) Id MachineName ProcessName ------ ----- ----- ----- ------ -- ----------- ----------- -6 23500 31340 142 1980 S1 powershell -6 23500 31348 142 4016 S1 powershell -27 54572 54520 576 4428 localhost powershell + 6 23500 31340 142 1.70 1980 S1 powershell + 6 23500 31348 142 2.75 4016 S1 powershell + 27 54572 54520 576 5.52 4428 localhost powershell ``` -This example provides a **Format-Table** (alias = ft) command that adds the **MachineName** property to the standard **Get-Process** output display. +This example provides a `Format-Table` (alias = ft) command that adds the MachineName property to the standard `Get-Process` output display. ### Example 6: Get version information for a process ``` diff --git a/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md b/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md index 6c02272f6752..b6239ee06ef7 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md @@ -15,9 +15,9 @@ Combines a path and a child path into a single path. ## SYNTAX -``` -Join-Path [-Path] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] - [] +```powershell +Join-Path [-Path] [-ChildPath] + [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Object_Creation.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Object_Creation.md index 65a910c9ccab..0f745ac3aa94 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Object_Creation.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Object_Creation.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,232 +7,246 @@ title: about_Object_Creation --- # About Object Creation -## about_Object_Creation - ## SHORT DESCRIPTION -Explains how to create objects in Windows PowerShell. +Explains how to create objects in PowerShell. ## LONG DESCRIPTION -You can create objects in Windows PowerShell and use the objects that you create in commands and scripts. - -There are several ways to create objects: - -New-Object: -The New-Object cmdlet creates an instance of a .NET Framework object or COM object. +You can create objects in PowerShell and use the objects that you create in +commands and scripts. -Hash tables: +There are several ways to create objects: -Beginning in Windows PowerShell 3.0, you can create objects from hash tables of property names and property values. +- `New-Object`: This cmdlet creates an instance of a .NET Framework object or + COM object. -Import-Csv: +- Hash tables: Beginning in PowerShell 3.0, you can create objects + from hash tables of property names and property values. -The Import-Csv cmdlet creates custom objects (PSCustomObject) from the items in a CSV file. Each row is an object instance and each column is an object property. +- `Import-Csv`: This cmdlet creates custom objects (PSCustomObject) from the + items in a CSV file. Each row is an object instance and each column is an + object property. This topic will demonstrate and discuss each of these methods. - ## NEW-OBJECT -The New-Object cmdlet provides a robust and consistent way to create new objects. The cmdlet works with almost all types and in all supported versions of Windows PowerShell. -To create a new object, specify either the type of a .NET Framework class or a ProgID of a COM object. +The `New-Object` cmdlet provides a robust and consistent way to create new +objects. The cmdlet works with almost all types and in all supported versions +of PowerShell. -For example, the following command creates a Version object. +To create a new object, specify either the type of a .NET Framework class or a +ProgID of a COM object. +For example, the following command creates a Version object. -``` -PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 +```powershell +PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 PS C:\> $v ``` - - -``` -Major Minor Build Revision ------ ----- ----- -------- +```Output +Major Minor Build Revision +----- ----- ----- -------- 2 0 0 1 ``` +```powershell +PS C:\> $v | Get-Member - -``` -PS C:\> $v | Get-Member - TypeName: System.Version ``` - For more information, see the help topic for the New-Object cmdlet. - ### CREATE 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: ``` -[]@{=;=} +[]@{ + = + = +} ``` - -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. ### CREATE CUSTOM OBJECTS FROM HASH TABLES -Custom objects are very useful and they are very easy to create by using the hash table method. To create a custom object, use the PSCustomObject class, a class designed specifically for this purpose. - -Custom objects are an excellent way to return customized output from a function or script; far more useful than returning formatted output that cannot be reformatted or piped to other commands. - -The commands in the Test-Object function set some variable values and then use those values to create a custom object. (You can see this object in use in the example section of the Update-Help cmdlet help topic.) - -``` -function Test-Object -{ $ModuleName = "PSScheduledJob" - $HelpCulture = "en-us" - $HelpVersion = "3.1.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} - - $ModuleName = "PSWorkflow" - $HelpCulture = "en-us" - $HelpVersion = "3.0.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} +Custom objects are very useful and they are very easy to create by using the +hash table method. To create a custom object, use the PSCustomObject class, a +class designed specifically for this purpose. + +Custom objects are an excellent way to return customized output from a +function or script; far more useful than returning formatted output that +cannot be reformatted or piped to other commands. + +The commands in the `Test-Object function` set some variable values and then +use those values to create a custom object. You can see this object in use in +the example section of the `Update-Help` cmdlet help topic. + +```powershell +function Test-Object { + $ModuleName = "PSScheduledJob" + $HelpCulture = "en-us" + $HelpVersion = "3.1.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } + $ModuleName = "PSWorkflow" + $HelpCulture = "en-us" + $HelpVersion = "3.0.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } } ``` +The output of this function is a collection of custom objects formatted as a +table by default. -The output of this function is a collection of custom objects formatted as a table by default. - +```powershell +PS C:\> Test-Object -``` -PS C:\> Test-Object - -ModuleName UICulture Version ---------- --------- ------- -PSScheduledJob en-us 3.1.0.0 +ModuleName UICulture Version +--------- --------- ------- +PSScheduledJob en-us 3.1.0.0 PSWorkflow en-us 3.0.0.0 ``` +Users can manage the properties of the custom objects just as they do with +standard objects. -Users can manage the properties of the custom objects just as they do with standard objects. - - -``` -PS C:\> (Test-Object).ModuleName - PSScheduledJob +```powershell +PS C:\> (Test-Object).ModuleName + PSScheduledJob PSWorkflow ``` - - #### CREATE NON-CUSTOM OBJECTS FROM HASH TABLES -You can also use hash tables to create objects for non-custom classes. When you create an object for a non-custom class, the full namespace name is required unless class is in the System namespace. Use only the properties of the class. -For example, the following command creates a session option object. +You can also use hash tables to create objects for non-custom classes. When +you create an object for a non-custom class, the full namespace name is +required unless class is in the System namespace. Use only the properties of +the class. +For example, the following command creates a session option object. +```powershell +[System.Management.Automation.Remoting.PSSessionOption]@{ + IdleTimeout=43200000 + SkipCnCheck=$True +} ``` -[System.Management.Automation.Remoting.PSSessionOption]@{IdleTimeout=43200000; SkipCnCheck=$True} -``` - -The requirements of the hash table feature, especially the null constructor requirement, eliminate many existing classes. However, most Windows PowerShell option classes are designed to work with this feature, as well as other very useful classes, such as the ScheduledJobTrigger class. +The requirements of the hash table feature, especially the null constructor +requirement, eliminate many existing classes. However, most PowerShell option +classes are designed to work with this feature, as well as other very useful +classes, such as the ScheduledJobTrigger class. +```powershell +[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{ + Frequency="Daily" + At="15:00" +} -``` -[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{Frequency="Daily";At="15:00"} - -Id Frequency Time DaysOfWeek Enabled --- --------- ---- ---------- ------- -0 Daily 6/6/2012 3:00:00 PM True +Id Frequency Time DaysOfWeek Enabled +-- --------- ---- ---------- ------- +0 Daily 6/6/2012 3:00:00 PM True ``` +You can also use the hash table feature when setting parameter values. For +example, the value of the **SessionOption** parameter of the New-PSSession +cmdlet and the value of the JobTrigger parameter of `Register-ScheduledJob` +can be a hash table. -You can also use the hash table feature when setting parameter values. For example, the value of the SessionOption parameter of the New-PSSession cmdlet and the value of the JobTrigger parameter of Register-ScheduledJob can be a hash table. - - -``` -New-PSSession -ComputerName Server01 -SessionOption @{IdleTimeout=43200000; SkipCnCheck=$True} -Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{Frequency="Daily";At="15:00"} +```powershell +New-PSSession -ComputerName Server01 -SessionOption @{ + IdleTimeout=43200000 + SkipCnCheck=$True +} +Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{ + Frequency="Daily" + At="15:00" +} ``` - - ### IMPORT-CSV -You can create custom objects from the items in a CSV file. When you use the Import-Csv cmdlet to import the CSV file, the cmdlet creates a custom object (PSCustomObject) for each item in the file. The column names are the object properties. -For example, if you import a CSV file of computer asset data, Import-CSV creates a collection of custom objects from the input. +You can create custom objects from the items in a CSV file. When you use the +`Import-Csv` cmdlet to import the CSV file, the cmdlet creates a custom object +(PSCustomObject) for each item in the file. The column names are the object +properties. +For example, if you import a CSV file of computer asset data, `Import-CSV` +creates a collection of custom objects from the input. ``` -#In Servers.csv -AssetID, Name, OS, Department -003, Server01, Windows Server 2012, IT -103, Server33, Windows 7, Marketing +#In Servers.csv +AssetID, Name, OS, Department +003, Server01, Windows Server 2012, IT +103, Server33, Windows 7, Marketing 212, Server35, Windows 8, Finance ``` +```powershell +PS C:\> $a = Import-Csv Servers.csv +PS C:\> $a - -``` -PS C:\> $a = Import-Csv Servers.csv -PS C:\> $a - -AssetID Name OS Department -------- ---- -- ---------- -003 Server01 Windows Server 2012 IT -103 Server33 Windows 7 Marketing +AssetID Name OS Department +------- ---- -- ---------- +003 Server01 Windows Server 2012 IT +103 Server33 Windows 7 Marketing 212 Server35 Windows 8 Finance ``` - Use the Get-Member cmdlet to confirm the object type. - -``` +```powershell PS C:\> $a | Get-Member ``` +```Output +TypeName: System.Management.Automation.PSCustomObject - -``` -TypeName: System.Management.Automation.PSCustomObject - -Name MemberType Definition ----- ---------- ---------- -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -AssetID NoteProperty System.String AssetID=003 -Department NoteProperty System.String Department=IT -Name NoteProperty System.String Name=Server01 +Name MemberType Definition +---- ---------- ---------- +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +AssetID NoteProperty System.String AssetID=003 +Department NoteProperty System.String Department=IT +Name NoteProperty System.String Name=Server01 OS NoteProperty System.String OS=Windows Server 2012 ``` - You can use the custom objects just as you would standard objects. - -``` +```powershell PS C:\> $a | where {$_.OS -eq "Windows 8"} ``` - - -``` -AssetID Name OS Department -------- ---- -- ---------- +```output +AssetID Name OS Department +------- ---- -- ---------- 212 Server35 Windows 8 Finance ``` - For more information, see the help topic for the Import-Csv cmdlet. - ## SEE ALSO [about_Objects](about_Objects.md) @@ -243,9 +257,8 @@ For more information, see the help topic for the Import-Csv cmdlet. [about_Pipelines](about_Pipelines.md) -Get-Member - -Import-Csv +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -New-Object +[Import-Csv](../../Microsoft.PowerShell.Utility/Import-Csv.md) +[New-Object](../../Microsoft.PowerShell.Utility/New-Object.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Objects.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Objects.md index 88ab499af532..58308cabd6d7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Objects.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Objects.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -58,20 +58,13 @@ directory objects are passed down the pipeline to the second command. The second command `where { $_.PsIsContainer -eq $false }` uses the PsIsContainer property of all file system objects to select only -files, which have a value of False ($false) in their PsIsContainer +files, which have a value of False (\$false) in their PsIsContainer property. Folders, which are containers and, thus, have a value of -True ($true) in their PsIsContainer property, are not selected. +True (\$true) in their PsIsContainer property, are not selected. The second command passes only the file objects to the third command `Format-List`, which displays the file objects in a list. -## For More Information - -Now that you understand a bit about objects, see the [about_Methods](about_Methods.md) -help topic to learn how to find and use object methods, the -[about_Properties](about_Properties.md) topic to learn how to find and use object properties, -and the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) topic, to learn how to find an object type. - ## See Also [about_Methods](about_Methods.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 6e83191b889c..01d129ccc4bb 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,84 +10,85 @@ title: about_Operator_Precedence ## SHORT DESCRIPTION -Lists the Windows PowerShell operators in precedence order. +Lists the PowerShell operators in precedence order. -[This topic was contributed by Kirk Munro, a Windows PowerShell MVP +[This topic was contributed by Kirk Munro, a PowerShell MVP from Ottawa, Ontario] ## LONG DESCRIPTION -Windows PowerShell operators let you construct simple, but powerful -expressions. This topic lists the operators in precedence order. -Precedence order is the order in which Windows PowerShell evaluates -the operators when multiple operators appear in the same expression. - -When operators have equal precedence, Windows PowerShell evaluates -them from left to right. The exceptions are the assignment operators, -the cast operators, and the negation operators (!, -not, -bnot), -which are evaluated from right to left. - -You can use enclosures, such as parentheses, to override the -standard precedence order and force Windows PowerShell to evaluate -the enclosed part of an expression before an unenclosed part. - -In the following list, operators are listed in the order that they -are evaluated. Operators on the same line, or in the same group, have -equal precedence. - -The Operator column lists the operators. The Reference column lists -the Windows PowerShell Help topic in which the operator is described. -To display the topic, type `get-help `. - -|OPERATOR|REFERENCE| -|--------|---------| -|`$() @()`|[about_Operators](#index-operator)| -|`.` (dereference) `::` (static)|[about_Operators](about_Operators.md)| -|`[0]` (index operator)|[about_Operators](about_Operators.md)| +PowerShell operators let you construct simple, but powerful +expressions. This topic lists the operators in precedence order. Precedence +order is the order in which PowerShell evaluates the operators when +multiple operators appear in the same expression. + +When operators have equal precedence, PowerShell evaluates them from +left to right. The exceptions are the assignment operators, the cast +operators, and the negation operators (!, -not, -bnot), which are evaluated +from right to left. + +You can use enclosures, such as parentheses, to override the standard +precedence order and force PowerShell to evaluate the enclosed part of +an expression before an unenclosed part. + +In the following list, operators are listed in the order that they are +evaluated. Operators on the same line, or in the same group, have equal +precedence. + +The Operator column lists the operators. The Reference column lists the +PowerShell Help topic in which the operator is described. To display +the topic, type `get-help `. + +|OPERATOR |REFERENCE| +|------------------------|---------| +|`$() @()` |[about_Operators](#index-operator)| +|`.` (dereference) |[about_Operators](about_Operators.md)| +|`::` (static) |[about_Operators](about_Operators.md)| +|`[0]` (index operator) |[about_Operators](about_Operators.md)| |`[int]` (cast operators)|[about_Operators](about_Operators.md)| -|`-split` (unary)
`-join` (unary)|[about_Split](about_Split.md)
[about_Join](about_Join.md)| -|`,` (comma operator)|[about_Operators](about_Operators.md)| -|`++ --`|[about_Assignment_Operators](about_Assignment_Operators.md)| -|`-not`
`! -bNot`|[about_Logical_Operators](about_logical_operators.md)
[about_Comparison_Operators](about_Comparison_Operators.md)| -|`..` (range operator)|[about_Operators](about_Operators.md)| -|`-f` (format operator)|[about_Operators](about_Operators.md)| -|`* / %`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`+ -`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| - - -The following group of operators have equal precedence. Their -case-sensitive and explicitly case-insensitive variants have -the same precedence. - -|OPERATOR|REFERENCE| -|--------|---------| -|`-split` (unary)|[about_Split](about_Split.md)| -|`-join` (unary)|[about_Join](about_Join.md)| -|`-is -isnot -as`|[about_Type_Operators](about_Type_Operators.md)| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`,` (comma operator) |[about_Operators](about_Operators.md)| +|`++ --` |[about_Assignment_Operators](about_Assignment_Operators.md)| +|`-not` |[about_Logical_Operators](about_logical_operators.md)| +|`! -bNot` |[about_Comparison_Operators](about_Comparison_Operators.md)| +|`..` (range operator) |[about_Operators](about_Operators.md)| +|`-f` (format operator) |[about_Operators](about_Operators.md)| +|`* / % + -` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| + +The following group of operators have equal precedence. Their case-sensitive +and explicitly case-insensitive variants have the same precedence. + +|OPERATOR |REFERENCE| +|-------------------------|---------| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`-is -isnot -as` |[about_Type_Operators](about_Type_Operators.md)| |`-eq -ne -gt -gt -lt -le`|[about_Comparison_Operators](about_Comparison_Operators.md)| -|`-like -notlike`|[about_comparison_operators](about_comparison_operators.md)| -|`-match -notmatch`|[about_comparison_operators](about_comparison_operators.md)| -|`-in -notIn`|[about_comparison_operators](about_comparison_operators.md)| -|`-contains -notContains`|[about_comparison_operators](about_comparison_operators.md)| -|`-replace`|[about_comparison_operators](about_comparison_operators.md)| +|`-like -notlike` |[about_comparison_operators](about_comparison_operators.md)| +|`-match -notmatch` |[about_comparison_operators](about_comparison_operators.md)| +|`-in -notIn` |[about_comparison_operators](about_comparison_operators.md)| +|`-contains -notContains` |[about_comparison_operators](about_comparison_operators.md)| +|`-replace` |[about_comparison_operators](about_comparison_operators.md)| The list resumes here with the following operators in precedence order: -|OPERATOR|REFERENCE| -|--------|---------| -|`-band -bor -bxor`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor`|[about_comparison_operators](about_comparison_operators.md)| -|`.` (dot-source)
`&` (call)|[about_Scopes](about_Scopes.md)
[about_Operators](about_Operators.md)| +|OPERATOR |REFERENCE| +|--------------------------|---------| +|`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| +|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`.` (dot-source) |[about_Scopes](about_Scopes.md)| +|`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| -|`> >> 2> 2>> 2>&1`|[about_Redirection](about_Redirection.md)| -|`= += -= *= /= %=`|[about_Assignment_Operators](about_Assignment_Operators.md)| +|`> >> 2> 2>> 2>&1` |[about_Redirection](about_Redirection.md)| +|`= += -= *= /= %=` |[about_Assignment_Operators](about_Assignment_Operators.md)| # EXAMPLES -The following two commands show the arithmetic operators and -the effect of using parentheses to force Windows PowerShell to -evaluate the enclosed part of the expression first. +The following two commands show the arithmetic operators and the effect of +using parentheses to force PowerShell to evaluate the enclosed part of +the expression first. ```powershell C:\PS> 2 + 3 * 4 @@ -97,8 +98,8 @@ C:\PS> (2 + 3) * 4 20 ``` -The following example gets the read-only text files from the local -directory and saves them in the `$read_only` variable. +The following example gets the read-only text files from the local directory +and saves them in the `$read_only` variable. ```powershell $read_only = get-childitem *.txt | where-object {$_.isReadOnly} @@ -109,37 +110,37 @@ It is equivalent to the following example. $read_only = ( get-childitem *.txt | where-object {$_.isReadOnly} ) ``` -Because the pipeline operator (|) has a higher precedence than the -assignment operator (=), the files that the Get-ChildItem cmdlet -gets are sent to the Where-Object cmdlet for filtering before they -are assigned to the $read_only variable. +Because the pipeline operator (|) has a higher precedence than the assignment +operator (=), the files that the Get-ChildItem cmdlet gets are sent to the +Where-Object cmdlet for filtering before they are assigned to the $read_only +variable. -The following example demonstrates that the index operator takes -precedence over the cast operator. +The following example demonstrates that the index operator takes precedence +over the cast operator. -The first expression creates an array of three strings. Then, it -uses the index operator with a value of 0 to select the first object -in the array, which is the first string. Finally, it casts the -selected object as a string. In this case, the cast has no effect. +The first expression creates an array of three strings. Then, it uses the +index operator with a value of 0 to select the first object in the array, +which is the first string. Finally, it casts the selected object as a string. +In this case, the cast has no effect. ```powershell C:\PS> [string]@('Windows','PowerShell','2.0')[0] Windows ``` -The second expression uses parentheses to force the cast operation -to occur before the index selection. As a result, the entire array -is cast as a (single) string. Then, the index operator selects -the first item in the string array, which is the first character. +The second expression uses parentheses to force the cast operation to occur +before the index selection. As a result, the entire array is cast as a +(single) string. Then, the index operator selects the first item in the string +array, which is the first character. ```powershell C:\PS> ([string]@('Windows','PowerShell','2.0'))[0] W ``` -In the following example, because the -gt (greater-than) operator -has a higher precedence than the -and (logical AND) operator, the -result of the expression is FALSE. +In the following example, because the -gt (greater-than) operator has a higher +precedence than the -and (logical AND) operator, the result of the expression +is FALSE. ```powershell C:\PS> 2 -gt 4 -and 1 @@ -160,11 +161,11 @@ C:\PS> 2 -gt (4 -and 1) True ``` -However, this example demonstrates an important principle of managing -operator precedence. When an expression is difficult for people to -interpret, use parentheses to force the evaluation order, even when it -forces the default operator precedence. The parentheses make your -intentions clear to people who are reading and maintaining your scripts. +However, this example demonstrates an important principle of managing operator +precedence. When an expression is difficult for people to interpret, use +parentheses to force the evaluation order, even when it forces the default +operator precedence. The parentheses make your intentions clear to people who +are reading and maintaining your scripts. ## SEE ALSO @@ -185,4 +186,3 @@ intentions clear to people who are reading and maintaining your scripts. [about_Split](about_Split.md) [about_Type_Operators](about_Type_Operators.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md index 86512bc2df24..7933f7f0a80e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,87 +7,81 @@ title: about_PackageManagement --- # About PackageManagement -## about_PackageManagement -# TOPIC -about_PackageManagement - -# SHORT DESCRIPTION +## SHORT DESCRIPTION PackageManagement is an aggregator for software package managers. -# LONG DESCRIPTION +## LONG DESCRIPTION PackageManagement functionality was introduced in Windows PowerShell 5.0. -PackageManagement is a unified interface for software package management systems; you -can run PackageManagement cmdlets to perform software discovery, installation, and -inventory (SDII) tasks. Regardless of the underlying installation technology, -you can run the common cmdlets in the PackageManagement module to search for, -install, or uninstall packages; add, remove, and query package repositories; and -run queries on a computer to determine which software packages are installed. - -PackageManagement supports a flexible plug-in model that enables support for other -software package management systems. - -The PackageManagement module is included with Windows PowerShell 5.0 and later releases -of Windows PowerShell, and works on three levels of package management -structure: package providers, package sources, and the packages themselves. - -Term Description ----------- ------------------------------ -Package manager Software package management system. In -PackageManagement terms, this is a package provider. -Package provider PackageManagement term for a package manager. Examples -can include Windows Installer, Chocolatey, -and others. -Package source A URL, local folder, or network shared folder that -you configure package providers to use as a -repository. -Package A piece of software that a package provider manages, -and that is stored in a specific package source. - -The PackageManagement module includes the following cmdlets. You can find the -Help for these cmdlets on TechNet starting on the following page: -http://technet.microsoft.com/library/dn890951(v=wps.640).aspx. - -Cmdlet Description ----------- ------------------------------ -Get-PackageProvider Returns a list of package providers that are -connected to PackageManagement. -Get-PackageSource Gets a list of package sources that are -registered for a package provider. -Register-PackageSource Adds a package source for a specified -package provider. -Set-PackageSource Sets properties on an existing package -source. -Unregister-PackageSource Removes a registered package source. -Get-Package Returns a list of installed software -packages. -Find-Package Finds software packages in available -package sources. -Install-Package Installs one or more software packages. -Save-Package Saves packages to the local computer -without installing them. -Uninstall-Package Uninstalls one or more software packages. - -PackageManagement Package Provider Bootstrapping and Dynamic Cmdlet Parameters - -By default, PackageManagement ships with a core bootstrap provider. You can install -additional package providers as you need them by bootstrapping the providers; -that is, responding to a prompt to install the provider automatically, from a -web service. You can specify a package provider with any PackageManagement cmdlet; -if the specified provider is not available, PackageManagement prompts you to bootstrap ---or automatically install--the provider. In the following examples, if the -Chocolatey provider is not already installed, PackageManagement bootstrapping installs -the provider. - +PackageManagement is a unified interface for software package management +systems; you can run PackageManagement cmdlets to perform software discovery, +installation, and inventory (SDII) tasks. Regardless of the underlying +installation technology, you can run the common cmdlets in the +PackageManagement module to search for, install, or uninstall packages; add, +remove, and query package repositories; and run queries on a computer to +determine which software packages are installed. + +PackageManagement supports a flexible plug-in model that enables support for +other software package management systems. + +The PackageManagement module is included with Windows PowerShell 5.0 and later +releases of Windows PowerShell, and works on three levels of package +management structure: package providers, package sources, and the packages +themselves. Let us define some terms: + +- Package manager: Software package management system. In PackageManagement + terms, this is a package provider. +- Package provider: PackageManagement term for a package manager. Examples can + include Windows Installer, Chocolatey, and others. +- Package source: A URL, local folder, or network shared folder that you + configure package providers to use as a repository. +- Package: A piece of software that a package provider manages, and that is + stored in a specific package source. + +The PackageManagement module includes the following cmdlets. For more +information, see the +[PackageManagement](/powershell/gallery/psget/oneget/packagemanagement_cmdlets) +help. + +- `Get-PackageProvider`: Returns a list of package providers that are + connected to PackageManagement. +- `Get-PackageSource`: Gets a list of package sources that are registered for + a package provider. +- `Register-PackageSource`: Adds a package source for a specified package + provider. +- `Set-PackageSource`: Sets properties on an existing package source. +- `Unregister-PackageSource`: Removes a registered package source. +- `Get-Package`: Returns a list of installed software packages. +- `Find-Package`: Finds software packages in available package sources. +- `Install-Package`: Installs one or more software packages. +- `Save-Package`: Saves packages to the local computer without installing + them. +- `Uninstall-Package`: Uninstalls one or more software packages. + +### Package Provider Bootstrapping and Dynamic Cmdlet Parameters + +By default, PackageManagement ships with a core bootstrap provider. You can +install additional package providers as you need them by bootstrapping the +providers; that is, responding to a prompt to install the provider +automatically, from a web service. You can specify a package provider with any +PackageManagement cmdlet; if the specified provider is not available, +PackageManagement prompts you to bootstrap (or automatically install) the +provider. In the following examples, if the Chocolatey provider is not already +installed, PackageManagement bootstrapping installs the provider. + +```powershell Find-Package -Provider Chocolatey +``` If the Chocolatey provider is not already installed, when you run the preceding command, you are prompted to install it. +```powershell Install-Package -ForceBootstrap +``` If the Chocolatey provider is not already installed, when you run the preceding command, the provider is installed; but because the ForceBootstrap @@ -99,10 +93,10 @@ provider installed, and you do not add the ForceBootstrap parameter to your command, PackageManagement prompts you to install the provider. Specifying a package provider in your PackageManagement command can make -dynamic parameters available that are specific to that package provider. -When you run Get-Help for a specific PackageManagement cmdlet, a list of -parameter sets are returned, grouping dynamic parameters for available -package providers in separate parameter sets. +dynamic parameters available that are specific to that package provider. When +you run Get-Help for a specific PackageManagement cmdlet, a list of parameter +sets are returned, grouping dynamic parameters for available package providers +in separate parameter sets. More Information About the PackageManagement Project @@ -131,4 +125,3 @@ Install-Package Save-Package Uninstall-Package - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 871bcb0dd4f2..e9c4ebaefa98 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,449 +7,409 @@ title: about_Parameters_Default_Values --- # About Parameters Default Values -## about_Parameters_Default_Values - ## SHORT DESCRIPTION -Describes how to set custom default values for the parameters of cmdlets and advanced functions. +Describes how to set custom default values for the parameters of cmdlets and +advanced functions. ## LONG DESCRIPTION -The $PSDefaultParameterValues preference variable lets you specify custom default values for any cmdlet or advanced function. Cmdlets and functions use the custom default value unless you specify another value in the command. -The authors of cmdlets and advanced functions set standard default values for their parameters. Typically, the standard default values are useful, but they might not be appropriate for all environments. +The \$PSDefaultParameterValues preference variable lets you specify custom +default values for any cmdlet or advanced function. Cmdlets and functions use +the custom default value unless you specify another value in the command. + +The authors of cmdlets and advanced functions set standard default values for +their parameters. Typically, the standard default values are useful, but they +might not be appropriate for all environments. -This feature is especially useful when you must specify the same alternate parameter value nearly every time you use the command or when a particular parameter value is difficult to remember, such as an e-mail server name or project GUID. +This feature is especially useful when you must specify the same alternate +parameter value nearly every time you use the command or when a particular +parameter value is difficult to remember, such as an e-mail server name or +project GUID. -If the desired default value varies predictably, you can specify a script block that provides different default values for a parameter under different conditions. +If the desired default value varies predictably, you can specify a script +block that provides different default values for a parameter under different +conditions. -$PSDefaultParameterValues was introduced in Windows PowerShell 3.0. +\$PSDefaultParameterValues was introduced in PowerShell 3.0. +## SYNTAX -### SYNTAX The syntax of the $PSDefaultParameterValues preference variable is as follows: +```powershell +$PSDefaultParameterValues=@{":"=""} + +$PSDefaultParameterValues=@{":"={}} -``` -$PSDefaultParameterValues=@{":"=""} - -$PSDefaultParameterValues=@{":"={}} - $PSDefaultParameterValues["Disabled"]=$true | $false ``` - Wildcard characters are permitted in the CmdletName and ParameterName values. -The value of $PSDefaultParameterValues is a System.Management.Automation.DefaultParameterDictionary, a type of hash table that validates the format of keys. Enter a hash table where the key consists of the cmdlet name and parameter name separated by a colon (:) and the value is the custom default value. - -To set, change, add, or remove entries from $PSDefaultParameterValues, use the methods that you would use to edit a standard hash table. +The value of \$PSDefaultParameterValues is a +System.Management.Automation.DefaultParameterDictionary, a type of hash table +that validates the format of keys. Enter a hash table where the key consists +of the cmdlet name and parameter name separated by a colon (:) and the value +is the custom default value. -The must be the name of a cmdlet or the name of an advanced function that uses the CmdletBinding attribute. You cannot use $PSDefaultParameterValues to specify default values for scripts or simple functions. +To set, change, add, or remove entries from \$PSDefaultParameterValues, use the +methods that you would use to edit a standard hash table. -The default value can be an object or a script block. If the value is a script block, Windows PowerShell evaluates the script block and uses the result as the parameter value. When the specified parameter takes a script block value, enclose the script block value in a second set of braces, such as: +The \ must be the name of a cmdlet or the name of an advanced +function that uses the CmdletBinding attribute. You cannot use +$PSDefaultParameterValues to specify default values for scripts or simple +functions. +The default value can be an object or a script block. If the value is a script +block, PowerShell evaluates the script block and uses the result as the +parameter value. When the specified parameter takes a script block value, +enclose the script block value in a second set of braces, such as: -``` +```powershell $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } ``` +For information about hash tables, see +[about_Hash_Tables](about_Hash_Tables.md). For information about script +blocks, see [about_Script_Blocks](about_Script_Blocks.md). For information +about preference variables, see +[about_Preference_Variables](about_Preference_Variables.md). -For information about hash tables, see about_Hash_Tables. For information about script blocks, see about_Script_Blocks. For information about preference variables, see about_Preference_Variables. - +## EXAMPLES -### EXAMPLES -The following command sets a custom default value for the SmtpServer parameter of the Send-MailMessage cmdlet. +The following command sets a custom default value for the SmtpServer parameter +of the Send-MailMessage cmdlet. - -``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"} +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" +} ``` +To set default values for multiple parameters, use a semi-colon (;) to +separate each Name\=Value pair. The following command adds a custom default +value for the LogName parameter of the `Get-WinEvent` cmdlet. -To set default values for multiple parameters, use a semi-colon (;) to separate each Name\=Value pair. The following command adds a custom default value for the LogName parameter of the Get-WinEvent cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5"; + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" +} ``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"} -``` - -You can use wildcard characters in the name of the cmdlet and parameter. The following command sets the Verbose common parameter to $true in all commands. Use $true and $false to set values for switch parameters, such as Verbose. +You can use wildcard characters in the name of the cmdlet and parameter. The +following command sets the Verbose common parameter to \$true in all commands. +Use \$true and \$false to set values for switch parameters, such as +**Verbose**. - -``` +```powershell $PSDefaultParameterValues = @{"*:Verbose"=$true} ``` +If a parameter takes multiple values (an array), you can set multiple values +as the default value. The following command sets the default value of the +**ComputerName** parameter of the Invoke-Command cmdlet to "Server01" and +"Server02". -If a parameter takes multiple values (an array), you can set multiple values as the default value. The following command sets the default value of the ComputerName parameter of the Invoke-Command cmdlet to "Server01" and "Server02". - - -``` -$PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"} -``` - - -You can use a script block to specify different default values for a parameter under different conditions. Windows PowerShell evaluates the script block and uses the result as the default parameter value. - -The following command sets the default value of the Autosize parameter of the Format-Table cmdlet to $true when the host program is the Windows PowerShell console. - - -``` -$PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}}} -``` - - -If a parameter takes a script block value, enclose the script block in an extra set of braces. When Windows PowerShell evaluates the outer script block, the result is the inner script block, which is set as the default parameter value. - -The following command sets the default value of the ScriptBlock parameter of Invoke-Command. Because the script block is enclosed in a second set of braces, the enclosed script block is passed to the Invoke-Command cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Invoke-Command:ComputerName"="Server01","Server02" +} ``` -$PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}} -``` - - - -### HOW TO SET $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. - -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues +You can use a script block to specify different default values for a parameter +under different conditions. PowerShell evaluates the script block and uses the +result as the default parameter value. -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. +The following command sets the default value of the Autosize parameter of the +Format-Table cmdlet to \$true when the host program is the PowerShell console. - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +$PSDefaultParameterValues=@{ + "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}} +} ``` +If a parameter takes a script block value, enclose the script block in an +extra set of braces. When PowerShell evaluates the outer script block, the +result is the inner script block, which is set as the default parameter value. +The following command sets the default value of the ScriptBlock parameter of +`Invoke-Command`. Because the script block is enclosed in a second set of +braces, the enclosed script block is passed to the `Invoke-Command` cmdlet. -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational -Get*:Verbose True +```powershell +$PSDefaultParameterValues=@{ + "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} +} ``` +### HOW TO SET \$PSDefaultParameterValues -To get the value of a key, use the following command syntax: +\$PSDefaultParameterValues is a preference variable, so it exists only in the +session in which it is set. It has no default value. +To set \$PSDefaultParameterValues, type the variable name and one or more +key-value pairs at the command line. -``` -$PSDefaultParameterValues[""] -``` +If you type another \$PSDefaultParameterValues command, its value replaces the +original value. The original is not retained. +To save \$PSDefaultParameterValues for future sessions, add a +\$PSDefaultParameterValues command to your PowerShell profile. For more +information, see [about_Profiles](about_Profiles.md). -For example: +### HOW TO GET \$PSDefaultParameterValues +To get the value of \$PSDefaultParameterValues, at the command prompt, type: +```powershell +$PSDefaultParameterValues ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] -Server01AB234x5 -``` - - - -### HOW TO ADD VALUES TO $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. +For example, the first command sets the value of \$PSDefaultParameterValues. +The second command gets the value of \$PSDefaultParameterValues. -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues - -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. - - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +PS C:\> $PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + "Get-*:Verbose"=$true +} ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To get the value of a \ key, use the following +command syntax: -To get the value of a key, use the following command syntax: - - -``` +```powershell $PSDefaultParameterValues[""] ``` - For example: - -``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] Server01AB234x5 ``` +### HOW TO ADD VALUES TO PSDefaultParameterValues +To add or remove values from \$PSDefaultParameterValues, use the methods that +you would use for a standard hash table. -### HOW TO ADD VALUES TO $PSDefaultParameterValues -To add or remove values from $PSDefaultParameterValues, use the methods that you would use for a standard hash table. - -For example, to add a value to $PSDefaultParameterValues without affecting the existing values, use the Add method of hash tables. +For example, to add a value to \$PSDefaultParameterValues without affecting the +existing values, use the Add method of hash tables. The syntax of the Add method is as follows: - ``` .Add(Key, Value) ``` +where the Key is ":" and the value is the parameter +value. -where the Key is ":" and the value is the parameter value. - -Use the following command format to call the Add method on $PSDefaultParameterValues. Be sure to use a comma (,) to separate the key from the value, instead of the equal sign (\=). - +Use the following command format to call the Add method on +\$PSDefaultParameterValues. Be sure to use a comma (,) to separate the key +from the value, instead of the equal sign (\=). +```powershell +$PSDefaultParameterValues.Add( + ":", "" +) ``` -$PSDefaultParameterValues.Add(":", "") -``` - -For example, the following command adds "PowerShell" as the default value of the Name parameter of the Get-Process cmdlet. +For example, the following command adds "PowerShell" as the default value of +the Name parameter of the Get-Process cmdlet. - -``` +```powershell $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO REMOVE VALUES FROM \$PSDefaultParameterValues - -### HOW TO REMOVE VALUES FROM $PSDefaultParameterValues -To remove a value from $PSDefaultParameterValues, use the Remove method of hash tables. +To remove a value from \$PSDefaultParameterValues, use the Remove method of +hash tables. The syntax of the Remove method is as follows: - -``` +```powershell .Remove(Key) ``` +Use the following command format to call the Remove method on +\$PSDefaultParameterValues. -Use the following command format to call the Remove method on $PSDefaultParameterValues. - - -``` +```powershell $PSDefaultParameterValues.Remove(":") ``` +For example, the following command removes the Name parameter of the +`Get-Process` cmdlet and its values. -For example, the following command removes the Name parameter of the Get-Process cmdlet and its values. - - -``` +```powershell $PSDefaultParameterValues.Remove("Get-Process:Name") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO CHANGE VALUES IN \$PSDefaultParameterValues +To change a value in $PSDefaultParameterValues, use the following command +format. -### HOW TO CHANGE VALUES IN $PSDefaultParameterValues -To change a value in $PSDefaultParameterValues, use the following command format. - - -``` +```powershell $PSDefaultParameterValues["CmdletName:ParameterName"]="" ``` - The following example shows the effect of this command. +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - +```powershell +$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" -``` - +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO DISABLE AND RE-ENABLE \$PSDefaultParameterValues +You can temporarily disable and then re-enable \$PSDefaultParameterValues. This +is very useful if you're running scripts that might assume different default +parameter values. -### HOW TO DISABLE AND RE-ENABLE $PSDefaultParameterValues -You can temporarily disable and then re-enable $PSDefaultParameterValues. This is very useful if you're running scripts that might assume different default parameter values. - -To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of $True. +To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of +\$True. For example, - -``` +```powershell $PSDefaultParameterValues.Add("Disabled", $true) ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$true ``` +The other values in \$PSDefaultParameterValues are preserved, but not +effective. -The other values in $PSDefaultParameterValues are preserved, but not effective. - +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Disabled True -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Disabled True +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To re-enable \$PSDefaultParameterValues, remove the Disabled key or change the +value of the Disabled key to \$False. -To re-enable $PSDefaultParameterValues, remove the Disabled key or change the value of the Disabled key to $False. - - -``` +```powershell $PSDefaultParameterValues.Remove("Disabled") ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$false ``` - -The previous value of $PSDefaultParameterValues is effective again. - +The previous value of \$PSDefaultParameterValues is effective again. ## KEYWORDS + about_PSDefaultParameterValues about_Parameters_DefaultValues about_DefaultValues - ## SEE ALSO [about_Hash_Tables](about_Hash_Tables.md) @@ -459,4 +419,3 @@ about_DefaultValues [about_Profiles](about_Profiles.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 886b4ed1dfc9..906dc159fb8a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-05 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -248,7 +248,7 @@ debug message is not displayed and processing continues. The final command uses the Debug parameter to override the preference for a single command. ```powershell -PS> $debugpreference # Get the current value of \$DebugPreference +PS> $debugpreference # Get the current value of $DebugPreference SilentlyContinue PS> write-debug "Hello, World" @@ -301,7 +301,7 @@ uses the Debug parameter with a value of \$false to suppress the message for a single command. ```powershell -PS> \$debugpreference = "Inquire" +PS> $debugpreference = "Inquire" PS> write-debug "Hello, World" DEBUG: Hello, World @@ -375,7 +375,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value of the preference. -PS> \$ErrorActionPreference = "SilentlyContinue" +PS> $ErrorActionPreference = "SilentlyContinue" PS> # Generate an error message. PS> write-error "Hello, World" @@ -393,14 +393,14 @@ a non-existent file, nofile.txt. The example also uses the ErrorAction common parameter to override the preference. ```powershell -PS> \$erroractionpreference +PS> $erroractionpreference SilentlyContinue # Display the value of the preference. PS> get-childitem -path nofile.txt PS> # Error message is suppressed. PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> get-childitem -path nofile.txt Get-ChildItem : Cannot find path 'C:\nofile.txt' because it does not exist. @@ -412,7 +412,7 @@ PS> get-childitem -path nofile.txt -erroraction SilentlyContinue PS> # Error message is suppressed. PS> # Change the value to Inquire. -PS> \$ErrorActionPreference = "Inquire" +PS> $ErrorActionPreference = "Inquire" PS> get-childitem -path nofile.txt Confirm @@ -425,7 +425,7 @@ At line:1 char:4 + get-childitem <<<< nofile.txt PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> Get-Childitem nofile.txt -erroraction "Inquire" PS> # Use the ErrorAction parameter to override the preference value. @@ -462,7 +462,7 @@ NormalView. In this case, the Get-ChildItem command is used to find a non-existent file. ```powershell -PS> \$ErrorView # Verify the value. +PS> $ErrorView # Verify the value. NormalView PS> get-childitem nofile.txt # Find a non-existent file. @@ -475,7 +475,7 @@ This example shows how the same error appears when the value of \$ErrorView is CategoryView. ```powershell -PS> \$ErrorView = "CategoryView" # Change the value to +PS> $ErrorView = "CategoryView" # Change the value to CategoryView PS> get-childitem nofile.txt @@ -493,7 +493,7 @@ error in the error array (element 0) and formats all of the properties of the error object in a list. ```powershell -PS> \$error[0] | format-list -property * -force +PS> $error[0] | format-list -property * -force Exception : System.Management.Automation.ItemNotFoundException: Cannot find path 'C:\nofile.txt' because it does not exist. @@ -546,10 +546,10 @@ In the resulting display, the list in the Group column is now limited by the line length. In the final command in the example, use the Wrap parameter of Format-Table to display all of the processes in each Status group. -PS> \$formatenumerationlimit # Find the current value +```powershell +PS> $formatenumerationlimit # Find the current value 4 -```powershell PS> # List all services grouped by status PS> get-service | group-object -property status @@ -560,7 +560,7 @@ Count Name Group PS> # The list is truncated after 4 items. PS> # Increase the limit to 1000. -PS> \$formatenumerationlimit = 1000 +PS> $formatenumerationlimit = 1000 PS> get-service | group-object -property status Count Name Group @@ -650,20 +650,20 @@ The Log*Event preference variables are as follows: To enable a Log*Event, type the variable with a value of \$true, for example: ```powershell -\$LogCommandLifeCycleEvent +$LogCommandLifeCycleEvent ``` - or - ```powershell -\$LogCommandLifeCycleEvent = \$true +$LogCommandLifeCycleEvent = $true ``` To disable an event type, type the variable with a value of \$false, for example: ```powershell -\$LogCommandLifeCycleEvent = \$false +$LogCommandLifeCycleEvent = $false ``` The events that you enable are effective only for the current PowerShell @@ -719,26 +719,26 @@ To count the errors on your system, use the Count property of the \$Error array. Type: ```powershell -\$Error.count +$Error.count ``` To display a specific error, use array notation to display the error. For example, to see the most recent error, type: ```powershell -\$Error[0] +$Error[0] ``` To display the oldest retained error, type: ```powershell -\$Error[(\$Error.Count -1] +$Error[($Error.Count -1] ``` To display the properties of the ErrorRecord object, type: ```powershell -\$Error[0] | format-list -property * -force +$Error[0] | format-list -property * -force ``` In this command, the Force parameter overrides the special formatting of @@ -748,11 +748,11 @@ To delete all errors from the error history, use the Clear method of the error array. ```powershell -PS> \$Error.count +PS> $Error.count 17 -PS> \$Error.clear() +PS> $Error.clear() PS> -PS> \$Error.count +PS> $Error.count 0 ``` @@ -844,9 +844,9 @@ is converted to a string. In this case, an array of integers is stored in a variable and then the variable is cast as a string. ```powershell -PS> \$array = 1,2,3 # Store an array of integers. +PS> $array = 1,2,3 # Store an array of integers. -PS> [string]\$array # Cast the array to a string. +PS> [string]$array # Cast the array to a string. 1 2 3 # Spaces separate the elements ``` @@ -854,9 +854,9 @@ To change the separator, add the \$OFS variable by assigning a value to it. To work correctly, the variable must be named \$OFS. ```powershell -PS> \$OFS = "+" # Create \$OFS and assign a "+" +PS> $OFS = "+" # Create $OFS and assign a "+" -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1+2+3 # Plus signs separate the elements ``` @@ -865,10 +865,10 @@ To restore the default behavior, you can assign a space (" ") to the value of verifies that the separator is a space. ```powershell -PS> Remove-Variable OFS # Delete \$OFS +PS> Remove-Variable OFS # Delete $OFS PS> -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1 2 3 # Spaces separate the elements ``` @@ -897,7 +897,7 @@ The first command finds the value of \$OutputEncoding. Because the value is an encoding object, display only its EncodingName property. ```powershell -PS> \$OutputEncoding.EncodingName # Find the current value US-ASCII +PS> $OutputEncoding.EncodingName # Find the current value US-ASCII ``` In this example, a FINDSTR command is used to search for two Chinese @@ -918,9 +918,9 @@ locale selected for Windows. Because OutputEncoding is a static property of the console, use double-colons (::) in the command. ```powershell -PS> \$OutputEncoding = [console]::outputencoding +PS> $OutputEncoding = [console]::outputencoding PS> # Set the value equal to the OutputEncoding property of the console. -PS> \$OutputEncoding.EncodingName +PS> $OutputEncoding.EncodingName OEM United States ``` As a result of this change, the FINDSTR command finds the characters. @@ -1100,7 +1100,7 @@ values you prefer. Save the output in a variable called \$PSSessionOption. For example, ```powershell -\$PSSessionOption = New-PSSessionOption -NoCompression +$PSSessionOption = New-PSSessionOption -NoCompression ``` To use the \$PSSessionOption preference variable in every PowerShell session, @@ -1202,7 +1202,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$VerbosePreference = "Inquire" +PS> $VerbosePreference = "Inquire" PS> Write-Verbose "Verbose message test." VERBOSE: Verbose message test. Confirm @@ -1249,7 +1249,7 @@ value. This example shows the effect of the Continue value, which is the default. ```powershell -PS> \$WarningPreference # Find the current value. +PS> $WarningPreference # Find the current value. Continue PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1263,7 +1263,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value to SilentlyContinue. -PS> \$WarningPreference = "SilentlyContinue" +PS> $WarningPreference = "SilentlyContinue" PS> Write-Warning "This action can delete data." PS> # Write a warning message. @@ -1280,7 +1280,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$WarningPreference = "Inquire" +PS> $WarningPreference = "Inquire" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1299,7 +1299,7 @@ This example shows the effect of the Stop value. ```powershell PS> # Change the value to Stop. -PS> \$WarningPreference = "Stop" +PS> $WarningPreference = "Stop" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1360,7 +1360,7 @@ This example shows the effect of the 0 (not enabled) value, which is the default. ```powershell -PS> \$whatifpreference +PS> $whatifpreference 0 # Check the current value. PS> # Verify that the file exists. @@ -1400,8 +1400,8 @@ Remove-Item to delete a cmdlet, Remove-Item displays the path to the file that it would delete, but it does not delete the file. ```powershell -PS> \$whatifpreference = 1 -PS> \$whatifpreference +PS> $whatifpreference = 1 +PS> $whatifpreference 1 # Change the value. PS> # Try to delete a file. @@ -1417,8 +1417,8 @@ This example shows how to delete a file when the value of \$WhatIfPreference is 1. It uses the WhatIf parameter with a value of \$false. ```powershell -PS> # Use the WhatIf parameter with \$false. -PS> remove-item test.txt -whatif:\$false +PS> # Use the WhatIf parameter with $false. +PS> remove-item test.txt -whatif:$false ``` This example demonstrates that some cmdlets support WhatIf behavior and others @@ -1430,7 +1430,7 @@ a value of \$false. ```powershell PS> # Change the value to 1. -PS> \$whatifpreference = 1 +PS> $whatifpreference = 1 PS> get-process winword A Get-Process command completes. @@ -1443,8 +1443,8 @@ PS> # A Stop-Process command uses WhatIf. PS> stop-process -name winword What if: Performing operation "Stop-Process" on Target "WINWORD (2312)". -PS> stop-process -name winword -whatif:\$false -PS> # WhatIf:\$false overrides the preference. +PS> stop-process -name winword -whatif:$false +PS> # WhatIf:$false overrides the preference. PS> # Verify that the process is stopped. PS> get-process winword diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Profiles.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Profiles.md index b7eabd81d0ce..eea0dd9f0d50 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Profiles.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Profiles.md @@ -1,104 +1,99 @@ --- -ms.date: 2017-06-25 +ms.date: 2017-11-30 schema: 2.0.0 keywords: powershell,cmdlet title: about_Profiles --- # About Profiles -## about_Profiles +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Describes how to create and use a PowerShell profile. -Describes how to create and use a Windows PowerShell profile. +## LONG DESCRIPTION -# LONG DESCRIPTION +You can create a PowerShell profile to customize your environment and to add +session-specific elements to every PowerShell session that you start. -You can create a Windows PowerShell profile to customize your environment -and to add session-specific elements to every Windows PowerShell session -that you start. +A PowerShell profile is a script that runs when PowerShell starts. You can use +the profile as a logon script to customize the environment. You can add +commands, aliases, functions, variables, snap-ins, modules, and PowerShell +drives. You can also add other session-specific elements to your profile so +they are available in every session without having to import or re-create +them. -A Windows PowerShell profile is a script that runs when Windows PowerShell -starts. You can use the profile as a logon script to customize the -environment. You can add commands, aliases, functions, variables, snap-ins, -modules, and Windows PowerShell drives. You can also add other -session-specific elements to your profile so they are available in every -session without having to import or re-create them. +PowerShell supports several profiles for users and host programs. However, it +does not create the profiles for you. This topic describes the profiles, and +it describes how to create and maintain profiles on your computer. -Windows PowerShell supports several profiles for users and host programs. -However, it does not create the profiles for you. This topic describes the -profiles, and it describes how to create and maintain profiles on your -computer. +It explains how to use the **NoProfile** parameter of the PowerShell console +(PowerShell.exe) to start PowerShell without any profiles. And, it explains +the effect of the PowerShell execution policy on profiles. -It explains how to use the **NoProfile** parameter of the Windows PowerShell -console (PowerShell.exe) to start Windows PowerShell without any profiles. -And, it explains the effect of the Windows PowerShell execution policy on -profiles. +## THE PROFILE FILES -# THE PROFILE FILES +PowerShell supports several profile files. Also, PowerShell host programs can +support their own host-specific profiles. - -Windows PowerShell supports several profile files. Also, Windows PowerShell -host programs can support their own host-specific profiles. - -For example, the Windows PowerShell console supports the following basic +For example, the PowerShell console supports the following basic profile files. The profiles are listed in precedence order. The first profile has the highest precedence. -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Profile.ps1 | -| Current User, All Hosts | $Home\\[My ]Documents\Profile.ps1 | -| All Users, Current Host | $PsHome\Microsoft.PowerShell_profile.ps1 | -| All Users, All Hosts | $PsHome\Profile.ps1 | +|Description | Path | +|--------------------------|------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Profile.ps1 | +|Current User, All Hosts |$Home\\[My ]Documents\\Profile.ps1 | +|All Users, Current Host |$PsHome\Microsoft.PowerShell_profile.ps1 | +|All Users, All Hosts |$PsHome\Profile.ps1 | The profile paths include the following variables: - The `$PsHome` variable, which stores the installation directory for -Windows PowerShell +PowerShell - The `$Home` variable, which stores the current user's home directory -In addition, other programs that host Windows PowerShell can support their -own profiles. For example, Windows PowerShell Integrated Scripting -Environment (ISE) supports the following host-specific profiles. - -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Microsoft.PowerShellISE_profile.ps1 | -| All users, Current Host | $PsHome\Microsoft.PowerShellISE_profile.ps1 | +In addition, other programs that host PowerShell can support their own +profiles. For example, PowerShell Integrated Scripting Environment (ISE) +supports the following host-specific profiles. -In Windows PowerShell Help, the "CurrentUser, Current Host" profile is the profile most -often referred to as "your Windows PowerShell profile". +|Description | Path | +|--------------------------|-------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Microsoft.PowerShellISE_profile.ps1 | +|All users, Current Host |$PsHome\Microsoft.PowerShellISE_profile.ps1| -# THE $PROFILE VARIABLE +In PowerShell Help, the "CurrentUser, Current Host" profile is the profile +most often referred to as "your PowerShell profile". +## THE $PROFILE VARIABLE -The `$Profile` automatic variable stores the paths to the Windows PowerShell -profiles that are available in the current session. +The `$Profile` automatic variable stores the paths to the PowerShell profiles +that are available in the current session. To view a profile path, display the value of the `$Profile` variable. You can also use the `$Profile` variable in a command to represent a path. -The `$Profile` variable stores the path to the "Current User, -Current Host" profile. The other profiles are saved in note properties of -the `$Profile` variable. +The `$Profile` variable stores the path to the "Current User, Current Host" +profile. The other profiles are saved in note properties of the `$Profile` +variable. For example, the `$Profile` variable has the following values in the Windows PowerShell console. -| Name | Description | -| ------------- | ------------- | -| $Profile | Current User, Current Host | -| $Profile.CurrentUserCurrentHost | Current User, Current Host | -| $Profile.CurrentUserAllHosts | Current User, All Hosts | -| $Profile.AllUsersCurrentHost | All Users, Current Host | -| $Profile.AllUsersAllHosts | All Users, All Hosts | +|Name |Description | +|--------------------------------|---------------------------| +|$Profile |Current User, Current Host | +|$Profile.CurrentUserCurrentHost |Current User, Current Host | +|$Profile.CurrentUserAllHosts |Current User, All Hosts | +|$Profile.AllUsersCurrentHost |All Users, Current Host | +|$Profile.AllUsersAllHosts |All Users, All Hosts | -Because the values of the `$Profile` variable change for each user and in -each host application, ensure that you display the values of the -profile variables in each Windows PowerShell host application that you use. +Because the values of the `$Profile` variable change for each user and in each +host application, ensure that you display the values of the profile variables +in each PowerShell host application that you use. To see the current values of the `$Profile` variable, type: @@ -107,24 +102,22 @@ $profile | Get-Member -Type NoteProperty ``` You can use the `$Profile` variable in many commands. For example, the -following command opens the "Current User, Current Host" profile in -Notepad: +following command opens the "Current User, Current Host" profile in Notepad: ```powershell notepad $profile ``` -The following command determines whether an "All Users, All Hosts" profile -has been created on the local computer: +The following command determines whether an "All Users, All Hosts" profile has +been created on the local computer: ```powershell Test-Path -Path $profile.AllUsersAllHosts ``` -# HOW TO CREATE A PROFILE +## HOW TO CREATE A PROFILE - -To create a Windows PowerShell profile, use the following command format: +To create a PowerShell profile, use the following command format: ```powershell if (!(Test-Path -Path )) @@ -132,7 +125,7 @@ if (!(Test-Path -Path )) ``` For example, to create a profile for the current user in the current -Windows PowerShell host application, use the following command: +PowerShell host application, use the following command: ```powershell if (!(Test-Path -Path $profile)) @@ -140,21 +133,18 @@ if (!(Test-Path -Path $profile)) ``` In this command, the If statement prevents you from overwriting an existing -profile. Replace the value of the placeholder with the path +profile. Replace the value of the \ placeholder with the path to the profile file that you want to create. ->Note: To create "All Users" profiles in Windows Vista and later versions ->of Windows, start Windows PowerShell with the "Run as administrator" ->option. - -# HOW TO EDIT A PROFILE +> Note: To create "All Users" profiles in Windows Vista and later versions of +> Windows, start PowerShell with the "Run as administrator" >option. +## HOW TO EDIT A PROFILE -You can open any Windows PowerShell profile in a text editor, such as -Notepad. +You can open any PowerShell profile in a text editor, such as Notepad. -To open the profile of the current user in the current Windows PowerShell -host application in Notepad, type: +To open the profile of the current user in the current PowerShell host +application in Notepad, type: ```powershell notepad $profile @@ -167,106 +157,99 @@ profile for all the users of all the host applications, type: notepad $profile.AllUsersAllHosts ``` -To apply the changes, save the profile file, and then restart Windows -PowerShell. +To apply the changes, save the profile file, and then restart PowerShell. -# HOW TO CHOOSE A PROFILE +## HOW TO CHOOSE A PROFILE +If you use multiple host applications, put the items that you use in all the +host applications into your `$Profile.CurrentUserAllHosts` profile. Put items +that are specific to a host application, such as a command that sets the +background color for a host application, in a profile that is specific to that +host application. -If you use multiple host applications, put the items that you use in all -the host applications into your `$Profile.CurrentUserAllHosts` profile. -Put items that are specific to a host application, such as a command that -sets the background color for a host application, in a profile that is -specific to that host application. - -If you are an administrator who is customizing Windows -PowerShell for many users, follow these guidelines: +If you are an administrator who is customizing Windows PowerShell for many +users, follow these guidelines: - Store the common items in the `$profile.AllUsersAllHosts` profile - - Store items that are specific to a host application in -`$profile.AllUsersCurrentHost` profiles that are specific to the host -application - + `$profile.AllUsersCurrentHost` profiles that are specific to the host + application - Store items for particular users in the user-specific profiles Be sure to check the host application documentation for any special -implementation of Windows PowerShell profiles. - -# HOW TO USE A PROFILE +implementation of PowerShell profiles. +## HOW TO USE A PROFILE -Many of the items that you create in Windows PowerShell and most commands -that you run affect only the current session. When you end the session, -the items are deleted. +Many of the items that you create in PowerShell and most commands that you run +affect only the current session. When you end the session, the items are +deleted. The session-specific commands and items include variables, preference -variables, aliases, functions, commands (except for [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), -and Windows PowerShell snap-ins that you add to the session. +variables, aliases, functions, commands (except for +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), +and PowerShell modules that you add to the session. -To save these items and make them available in all future sessions, add -them to a Windows PowerShell profile. +To save these items and make them available in all future sessions, add them +to a PowerShell profile. -Another common use for profiles is to save frequently-used functions, -aliases, and variables. When you save the items in a profile, you can -use them in any applicable session without re-creating them. +Another common use for profiles is to save frequently-used functions, aliases, +and variables. When you save the items in a profile, you can use them in any +applicable session without re-creating them. -# HOW TO START A PROFILE +## HOW TO START A PROFILE - -When you open the profile file, it is blank. However, you can fill it with -the variables, aliases, and commands that you use frequently. +When you open the profile file, it is blank. However, you can fill it with the +variables, aliases, and commands that you use frequently. Here are a few suggestions to get you started. -- Add commands that make it easy to open your profile. This is especially -useful if you use a profile other than the "Current User, Current Host" -profile. For example, add the following command: +### Add commands that make it easy to open your profile + +This is especially useful if you use a profile other than the "Current User, +Current Host" profile. For example, add the following command: ```powershell function Pro {notepad $profile.CurrentUserAllHosts} ``` -- Add a function that opens Windows PowerShell Help in a compiled HTML -Help file (.chm) +### Add a function that opens PowerShell Help in a compiled HTML + Help file (.chm) ```powershell -function Get-CHM -{ -Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" +function Get-CHM { + Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" } ``` -This function opens the English version of the .chm file. However, you -can replace the language code (0409) to open other versions of the .chm -file. +This function opens the English version of the .chm file. However, you can +replace the language code (0409) to open other versions of the .chm file. -- Add a function that lists the aliases for any cmdlet +### Add a function that lists the aliases for any cmdlet ```powershell -function Get-CmdletAlias ($cmdletname) -{ -Get-Alias | Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | Format-Table -Property Definition, Name -AutoSize +function Get-CmdletAlias ($cmdletname) { + Get-Alias | + Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | + Format-Table -Property Definition, Name -AutoSize } ``` -- Customize your console +### Customize your console ```powershell -function Color-Console -{ -$Host.ui.rawui.backgroundcolor = "white" -$Host.ui.rawui.foregroundcolor = "black" -$hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime -$hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" -$Host.UI.RawUI.WindowTitle = "Windows PowerShell $hostversion ($hosttime)" -Clear-Host +function Color-Console { + $Host.ui.rawui.backgroundcolor = "white" + $Host.ui.rawui.foregroundcolor = "black" + $hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime + $hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" + $Host.UI.RawUI.WindowTitle = "PowerShell $hostversion ($hosttime)" + Clear-Host } Color-Console ``` -- Add a customized Windows PowerShell prompt that includes the computer -name and the current path +### Add a customized PowerShell prompt ```powershell function Prompt @@ -275,18 +258,16 @@ $env:COMPUTERNAME + "\" + (Get-Location) + "> " } ``` -For more information about the Windows PowerShell prompt, see +For more information about the PowerShell prompt, see [about_Prompts](about_Prompts.md). -# THE NOPROFILE PARAMETER +## THE NOPROFILE PARAMETER +To start PowerShell without profiles, use the **NoProfile** parameter of +PowerShell.exe, the program that starts PowerShell. -To start Windows PowerShell without profiles, use the **NoProfile** parameter -of PowerShell.exe, the program that starts Windows PowerShell. - -To begin, open a program that can start Windows PowerShell, such as Cmd.exe -or Windows PowerShell itself. You can also use the Run dialog box in -Windows. +To begin, open a program that can start PowerShell, such as Cmd.exe or +PowerShell itself. You can also use the Run dialog box in Windows. Type: @@ -294,56 +275,58 @@ Type: PowerShell -NoProfile ``` -For a complete list of the parameters of PowerShell.exe, -type: +For a complete list of the parameters of PowerShell.exe, type: ``` PowerShell -? ``` -# PROFILES AND EXECUTION POLICY - +## PROFILES AND EXECUTION POLICY -The Windows PowerShell execution policy determines, in part, whether you -can run scripts and load configuration files, including the profiles. The -"Restricted" execution policy is the default. It prevents all scripts from -running, including the profiles. If you use the "Restricted" policy, the -profile does not run, and its contents are not applied. +The PowerShell execution policy determines, in part, whether you can run +scripts and load configuration files, including the profiles. The "Restricted" +execution policy is the default. It prevents all scripts from running, +including the profiles. If you use the "Restricted" policy, the profile does +not run, and its contents are not applied. A `Set-ExecutionPolicy` command sets and changes your execution policy. It is -one of the few commands that applies in all Windows PowerShell sessions -because the value is saved in the registry. You do not have to set it when -you open the console, and you do not have to store a `Set-ExecutionPolicy` -command in your profile. +one of the few commands that applies in all PowerShell sessions because the +value is saved in the registry. You do not have to set it when you open the +console, and you do not have to store a `Set-ExecutionPolicy` command in your +profile. -# PROFILES AND REMOTE SESSIONS +## PROFILES AND REMOTE SESSIONS +PowerShell profiles are not run automatically in remote sessions, so the +commands that the profiles add are not present in the remote session. In +addition, the `$Profile` automatic variable is not populated in remote +sessions. -Windows PowerShell profiles are not run automatically in remote sessions, -so the commands that the profiles add are not present in the remote session. -In addition, the `$Profile` automatic variable is not populated in remote sessions. +To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) +cmdlet. -To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) cmdlet. - -For example, the following command runs the "Current user, Current Host" profile from -the local computer in the session in $s. +For example, the following command runs the "Current user, Current Host" +profile from the local computer in the session in $s. ```powershell Invoke-Command -Session $s -FilePath $profile ``` -The following command runs the "Current user, Current Host" profile from the remote -computer in the session in $s. Because the `$Profile` variable is not populated, -the command uses the explicit path to the profile. +The following command runs the "Current user, Current Host" profile from the +remote computer in the session in $s. Because the `$Profile` variable is not +populated, the command uses the explicit path to the profile. ```powershell -Invoke-Command -SessionName $s -ScriptBlock {Invoke-Command -FilePath "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +Invoke-Command -SessionName $s -ScriptBlock { +$path = "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +Invoke-Command -FilePath $path +} ``` After running this command, the commands that the profile adds to the session are available in $s. -# SEE ALSO +## SEE ALSO [about_Automatic_Variables](about_Automatic_Variables.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Prompts.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Prompts.md index bc2e78b01d08..6f1820bea646 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Prompts.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Prompts.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,308 +7,284 @@ title: about_Prompts --- # About Prompts -## about_Prompts - ## SHORT DESCRIPTION -Describes the Prompt function and demonstrates how to create a custom Prompt function. +Describes the Prompt function and demonstrates how to create a custom Prompt +function. ## LONG DESCRIPTION -The Windows PowerShell command prompt indicates that Windows PowerShell is ready to run a command: +The PowerShell command prompt indicates that PowerShell is ready to run a +command: ``` PS C:\> ``` +The PowerShell prompt is determined by the built-in Prompt function. You can +customize the prompt by creating your own Prompt function and saving it in +your PowerShell profile. -The Windows PowerShell prompt is determined by the built-in Prompt function. You can customize the prompt by creating your own Prompt function and saving it in your Windows PowerShell profile. - +## ABOUT THE PROMPT FUNCTION -### ABOUT THE PROMPT FUNCTION -The Prompt function determines the appearance of the Windows PowerShell prompt. Windows PowerShell comes with a built-in Prompt function, but you can override it by defining your own Prompt function. +The Prompt function determines the appearance of the PowerShell prompt. +PowerShell comes with a built-in Prompt function, but you can override it by +defining your own Prompt function. The Prompt function has the following syntax: - -``` +```powershell function Prompt { } ``` +The Prompt function must return an object. As a best practice, return a string +or an object that is formatted as a string. The maximum recommended length is +80 characters. -The Prompt function must return an object. As a best practice, return a string or an object that is formatted as a string. The maximum recommended length is 80 characters. - -For example, the following prompt function returns a "Hello, World" string followed by a caret (>). +For example, the following prompt function returns a "Hello, World" string +followed by a caret (>). - -``` -PS C:\> function prompt {"Hello, World > "} +```powershell +PS C:\> function prompt {"Hello, World > "} Hello, World > ``` - - ### GETTING THE PROMPT FUNCTION -To get the Prompt function, use the Get-Command cmdlet or use the Get-Item cmdlet in the Function drive. -Functions are commands. So, you can use the Get-Command cmdlet to get functions, including the Prompt function. +To get the Prompt function, use the `Get-Command` cmdlet or use the `Get-Item` +cmdlet in the Function drive. For example: +```powershell +PS C:\> Get-Command Prompt -``` -PS C:\> Get-Command Prompt - -CommandType Name ModuleName ------------ ---- ---------- +CommandType Name ModuleName +----------- ---- ---------- Function prompt ``` - -To get the script that sets the value of the prompt, use the dot method to get the ScriptBlock property of the Prompt function. +To get the script that sets the value of the prompt, use the dot method to get +the ScriptBlock property of the Prompt function. For example: +```powershell +PS C:\> (Get-Command Prompt).ScriptBlock -``` -PS C:\> (Get-Command Prompt).ScriptBlock - -"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -# .Link -# http://go.microsoft.com/fwlink/?LinkID=225750 +"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPr +omptLevel + 1)) " +# .Link +# http://go.microsoft.com/fwlink/?LinkID=225750 # .ExternalHelp System.Management.Automation.dll-help.xml ``` +Like all functions, the Prompt function is stored in the Function: drive. To +display the script that creates the current Prompt function, type: -Like all functions, the Prompt function is stored in the Function: drive. To display the script that creates the current Prompt function, type: - - -``` +```powershell (Get-Item function:prompt).ScriptBlock ``` - ### THE DEFAULT PROMPT -The default prompt appears only when the Prompt function generates an error or does not return an object. -The default Windows PowerShell prompt is: +The default prompt appears only when the Prompt function generates an error or +does not return an object. +The default PowerShell prompt is: ``` PS> ``` +For example, the following command sets the Prompt function to $null, which is +invalid. As a result, the default prompt appears. -For example, the following command sets the Prompt function to $null, which is invalid. As a result, the default prompt appears. - - -``` -PS C:\> function prompt {$null} +```powershell +PS C:\> function prompt {$null} PS> ``` - -Because Windows PowerShell comes with a built-in prompt, you usually do not see the default prompt. - +Because PowerShell comes with a built-in prompt, you usually do not see the +default prompt. ### BUILT-IN PROMPT -Windows PowerShell includes a built-in prompt function. - -In Windows PowerShell 3.0, the built-in prompt function is: - - -``` -function prompt -{ - "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -} -``` - -This simplified prompt starts with "PS" followed by the current location, and one ">" for each nested prompt level. +PowerShell includes a built-in prompt function. -In Windows PowerShell 2.0, the built-in prompt function is: - - -``` -function prompt -{ - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - else { '' }) + 'PS ' + $(Get-Location) ` - + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +```powershell +function prompt { + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + else { '' }) + 'PS ' + $(Get-Location) ` + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +The function uses the Test-Path cmdlet to determine whether the +\$PSDebugContext automatic variable is populated. If \$PSDebugContext is +populated, you are in debugging mode, and "[DBG]" is added to the prompt, as +follows: -The function uses the Test-Path cmdlet to determine whether the $PSDebugContext automatic variable is populated. If $PSDebugContext is populated, you are in debugging mode, and "[DBG]" is added to the prompt, as follows: - - -``` +```Output [DBG] PS C:\ps-test> ``` +If \$PSDebugContext is not populated, the function adds "PS" to the prompt. +And, the function uses the `Get-Location` cmdlet to get the current file +system directory location. Then, it adds a right angle bracket (>). -If $PSDebugContext is not populated, the function adds "PS" to the prompt. And, the function uses the Get-Location cmdlet to get the current file system directory location. Then, it adds a right angle bracket (>). - +For example: -``` -For example: - PS C:\ps-test> +```Output +PS C:\ps-test> ``` +If you are in a nested prompt, the function adds two angle brackets (>>) to +the prompt. (You are in a nested prompt if the value of the +\$NestedPromptLevel automatic variable is greater than 1.) -If you are in a nested prompt, the function adds two angle brackets (>>) to the prompt. (You are in a nested prompt if the value of the $NestedPromptLevel automatic variable is greater than 1.) +For example, when you are debugging in a nested prompt, the prompt resembles +the following prompt: -For example, when you are debugging in a nested prompt, the prompt resembles the following prompt: - - -``` +```Output [DBG] PS C:\ps-test>>> ``` - - ### CHANGES TO THE PROMPT -The Enter-PSSession cmdlet prepends the name of the remote computer to the current Prompt function. When you use the Enter-PSSession cmdlet to start a session with a remote computer, the command prompt changes to include the name of the remote computer. For example: +The Enter-PSSession cmdlet prepends the name of the remote computer to the +current Prompt function. When you use the Enter-PSSession cmdlet to start a +session with a remote computer, the command prompt changes to include the name +of the remote computer. For example: -``` -PS Hello, World> Enter-PSSession Server01 +```Output +PS Hello, World> Enter-PSSession Server01 [Server01]: PS Hello, World> ``` +Other PowerShell host applications and alternate shells might have their own +custom command prompts. -Other Windows PowerShell host applications and alternate shells might have their own custom command prompts. - -For more information about the $PSDebugContext and $NestedPromptLevel automatic variables, see about_Automatic_Variables. - +For more information about the \$PSDebugContext and $NestedPromptLevel +automatic variables, see [about_Automatic_Variables](about_Automatic_Variables.md). ### HOW TO CUSTOMIZE THE PROMPT -To customize the prompt, write a new Prompt function. The function is not protected, so you can overwrite it. -To write a prompt function, type the following: +To customize the prompt, write a new Prompt function. The function is not +protected, so you can overwrite it. +To write a prompt function, type the following: -``` +```powershell function prompt { } ``` - -Then, between the braces, enter the commands or the string that creates your prompt. +Then, between the braces, enter the commands or the string that creates your +prompt. For example, the following prompt includes your computer name: - -``` +```powershell function prompt {"PS [$env:COMPUTERNAME]> "} ``` - On the Server01 computer, the prompt resembles the following prompt: - -``` +```Output PS [Server01] > ``` - The following prompt function includes the current date and time: - -``` +```powershell function prompt {"$(get-date)> "} ``` - The prompt resembles the following prompt: - -``` +```Output 03/15/2012 17:49:47> ``` - You can also change the default Prompt function: -For example, the following modified Prompt function adds "[ADMIN]:" to the built-in Windows PowerShell prompt when Windows PowerShell is opened by using the "Run as administrator" option: - - -``` -function prompt -{ - $identity = [Security.Principal.WindowsIdentity]::GetCurrent() - $principal = [Security.Principal.WindowsPrincipal] $identity - - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - - elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) - { "[ADMIN]: " } - - else { '' }) + 'PS ' + $(Get-Location) + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +For example, the following modified Prompt function adds "[ADMIN]:" to the +built-in PowerShell prompt when PowerShell is opened by using the "Run as +administrator" option: + +```powershell +function prompt { + $identity = [Security.Principal.WindowsIdentity]::GetCurrent() + $principal = [Security.Principal.WindowsPrincipal] $identity + + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] + "Administrator")) { "[ADMIN]: " } + else { '' } + ) + 'PS ' + $(Get-Location) + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +When you start PowerShell by using the "Run as administrator" option, a prompt +that resembles the following prompt appears: -When you start Windows PowerShell by using the "Run as administrator" option, a prompt that resembles the following prompt appears: - - -``` +```Output [ADMIN]: PS C:\ps-test> ``` +The following Prompt function displays the history ID of the next command. To +view the command history, use the `Get-History` cmdlet. -The following Prompt function displays the history ID of the next command. To view the command history, use the Get-History cmdlet. - +```powershell +function prompt { + # The at sign creates an array in case only one history item exists. + $history = @(get-history) + if($history.Count -gt 0) + { + $lastItem = $history[$history.Count - 1] + $lastId = $lastItem.Id + } -``` -function prompt -{ - # The at sign creates an array in case only one history item exists. - $history = @(get-history) - if($history.Count -gt 0) - { - $lastItem = $history[$history.Count - 1] - $lastId = $lastItem.Id - } - - $nextCommand = $lastId + 1 - $currentDirectory = get-location - "PS: $nextCommand $currentDirectory >" + $nextCommand = $lastId + 1 + $currentDirectory = get-location + "PS: $nextCommand $currentDirectory >" } ``` +The following prompt uses the Write-Host and Get-Random cmdlets to create a +prompt that changes color randomly. Because `Write-Host` writes to the current +host application but does not return an object, this function includes a +Return statement. Without it, PowerShell uses the default prompt, "PS>". -The following prompt uses the Write-Host and Get-Random cmdlets to create a prompt that changes color randomly. Because Write-Host writes to the current host application but does not return an object, this function includes a Return statement. Without it, Windows PowerShell uses the default prompt, "PS>". - - -``` -function prompt -{ - $color = Get-Random -Min 1 -Max 16 - Write-Host ("PS " + $(Get-Location) +">") -NoNewLine -ForegroundColor $Color - return " " +```powershell +function prompt { + $color = Get-Random -Min 1 -Max 16 + Write-Host ("PS " + $(Get-Location) +">") -NoNewLine ` + -ForegroundColor $Color + return " " } ``` - - ### SAVING THE PROMPT FUNCTION -Like any function, the Prompt function exists only in the current session. To save the Prompt function for future sessions, add it to your Windows PowerShell profiles. For more information about profiles, see about_Profiles. +Like any function, the Prompt function exists only in the current session. To +save the Prompt function for future sessions, add it to your PowerShell +profiles. For more information about profiles, see about_Profiles. ## SEE ALSO -Get-Location +[Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) -Enter-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Get-History +[Get-History](../Get-History.md) -Get-Random +[Get-Random](../../Microsoft.PowerShell.Utility/Get-Random.md) -Write-Host +[Write-Host](../../Microsoft.PowerShell.Utility/Write-Host.md) [about_Profiles](about_Profiles.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_pipelines.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_pipelines.md index ec7b65c085af..97cd9535c505 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_pipelines.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_pipelines.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,41 +7,39 @@ title: about_pipelines --- # About Pipelines -## about_Pipelines - - ### Short Description -Combining commands into pipelines in the Windows PowerShell +Combining commands into pipelines in the PowerShell ### Long Description -A pipeline is a series of commands connected by pipeline operators -(`|`)(ASCII 124). Each pipeline operator sends the results of the preceding -command to the next command. +A pipeline is a series of commands connected by pipeline operators (`|`) +(ASCII 124). Each pipeline operator sends the results of the preceding command +to the next command. -You can use pipelines to send the objects that are output by one command -to be used as input to another command for processing. And you can send the -output of that command to yet another command. The result is a very powerful -command chain or "pipeline" that is comprised of a series of simple commands. +You can use pipelines to send the objects that are output by one command to be +used as input to another command for processing. And you can send the output +of that command to yet another command. The result is a very powerful command +chain or "pipeline" that is comprised of a series of simple commands. For example, + ```powershell Command-1 | Command-2 | Command-3 ``` In this example, the objects that `Command-1` emits are sent to `Command-2`. -`Command-2` processes the objects and sends them to `Command-3`. `Command-3` processes -the objects and send them down the pipeline. Because there are no more commands in -the pipeline, the results are displayed at the console. +`Command-2` processes the objects and sends them to `Command-3`. `Command-3` +processes the objects and send them down the pipeline. Because there are no +more commands in the pipeline, the results are displayed at the console. -In a pipeline, the commands are processed from left to right in the order -that they appear. The processing is handled as a single operation and -output is displayed as it is generated. +In a pipeline, the commands are processed from left to right in the order that +they appear. The processing is handled as a single operation and output is +displayed as it is generated. -Here is a simple example. The following command gets the Notepad process -and then stops it. +Here is a simple example. The following command gets the Notepad process and +then stops it. For example, ```powershell @@ -49,77 +47,69 @@ Get-Process notepad | Stop-Process ``` The first command uses the `Get-Process` cmdlet to get an object representing -the Notepad process. It uses a pipeline operator (`|`) to send the process object -to the `Stop-Process` cmdlet, which stops the Notepad process. Notice that the -`Stop-Process` command does not have a Name or ID parameter to specify the process, -because the specified process is submitted through the pipeline. +the Notepad process. It uses a pipeline operator (`|`) to send the process +object to the `Stop-Process` cmdlet, which stops the Notepad process. Notice +that the `Stop-Process` command does not have a Name or ID parameter to +specify the process, because the specified process is submitted through the +pipeline. Here is a practical example. This command pipeline gets the text files in the -current directory, selects only the files that are more than 10,000 bytes long, -sorts them by length, and displays the name and length of each file in a table. +current directory, selects only the files that are more than 10,000 bytes +long, sorts them by length, and displays the name and length of each file in a +table. ```powershell Get-ChildItem -Path *.txt | Where-Object {$_.length -gt 10000} | Sort-Object -Property length | Format-Table -Property name, length ``` -This pipeline is comprised of four commands in the specified order. The command -is written horizontally, but we will show the process vertically in the following -graphic. +This pipeline is comprised of four commands in the specified order. The +command is written horizontally, but we will show the process vertically in +the following graphic. `Get-ChildItem` `-Path` *.txt - **|** - -| (FileInfo objects ) -| ( .txt ) - - **|** - - **V** +``` +| +| (FileInfo objects for *.txt) +| +V +``` `Where-Object` {$_.length `-gt` 10000} - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| +V +``` `Sort-Object` `-Property` Length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| +V +``` `Format-Table` `-Property` name, length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) -| (Formatted in a table ) - - **|** - - **V** - ``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| ( Formatted in a table ) +| +V +``` + +```output Name Length ---- ------ tmp1.txt 82920 @@ -129,13 +119,13 @@ tmp3.txt 114000 ### Using Pipelines +The PowerShell cmdlets were designed to be used in pipelines. For example, you +can usually pipe the results of a Get cmdlet to an action cmdlet (such as a +Set, Start, Stop, or Rename cmdlet) for the same noun. -The Windows PowerShell cmdlets were designed to be used in pipelines. For example, -you can usually pipe the results of a Get cmdlet to an action cmdlet (such as a Set, -Start, Stop, or Rename cmdlet) for the same noun. - -For example, you can pipe any service from the `Get-Service` cmdlet to the `Start-Service` -or `Stop-Service` cmdlets (although disabled services cannot be restarted in this way). +For example, you can pipe any service from the `Get-Service` cmdlet to the +`Start-Service` or `Stop-Service` cmdlets (although disabled services cannot +be restarted in this way). This command pipeline starts the WMI service on the computer: @@ -144,90 +134,98 @@ For example, Get-Service wmi | Start-Service ``` -The cmdlets that get and set objects of the Windows PowerShell providers, such as the +The cmdlets that get and set objects of the PowerShell providers, such as the Item and ItemProperty cmdlets, are also designed to be used in pipelines. -For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` command in the -Windows PowerShell registry provider to the `New-ItemProperty` cmdlet. This command adds -a new registry entry, NoOfEmployees, with a value of 8124, to the MyCompany registry key. +For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` +command in the PowerShell registry provider to the `New-ItemProperty` cmdlet. +This command adds a new registry entry, NoOfEmployees, with a value of 8124, +to the MyCompany registry key. For example, ```powershell -Get-Item -Path HKLM:\Software\MyCompany | New-ItemProperty -Name NoOfEmployees -Value 8124 +Get-Item -Path HKLM:\Software\MyCompany | + New-ItemProperty -Name NoOfEmployees -Value 8124 ``` -Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, `Sort-Object`, `Group-Object`, -and `Measure-Object` are used almost exclusively in pipelines. You can pipe any objects to -these cmdlets. +Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, +`Sort-Object`, `Group-Object`, and `Measure-Object` are used almost +exclusively in pipelines. You can pipe any objects to these cmdlets. -For example, you can pipe all of the processes on the computer to the `Sort-Object` command -and have them sorted by the number of handles in the process. +For example, you can pipe all of the processes on the computer to the +`Sort-Object` command and have them sorted by the number of handles in the +process. For example, + ```powershell Get-Process | Sort-Object -Property handles ``` -Also, you can pipe any objects to the formatting cmdlets, such as `Format-List` and -`Format-Table`, the Export cmdlets, such as `Export-Clixml` and `Export-CSV`, and the Out -cmdlets, such as `Out-Printer`. +Also, you can pipe any objects to the formatting cmdlets, such as +`Format-List` and `Format-Table`, the Export cmdlets, such as `Export-Clixml` +and `Export-CSV`, and the Out cmdlets, such as `Out-Printer`. -For example, you can pipe the Winlogon process to the `Format-List` cmdlet to display all -of the properties of the process in a list. +For example, you can pipe the Winlogon process to the `Format-List` cmdlet to +display all of the properties of the process in a list. For example, + ```powershell Get-Process winlogon | Format-List -Property * ``` -With a bit of practice, you'll find that combining simple commands into pipelines -saves time and typing, and makes your scripting more efficient. +With a bit of practice, you'll find that combining simple commands into +pipelines saves time and typing, and makes your scripting more efficient. ### How Pipelines Work +When you "pipe" objects, that is send the objects in the output of one command +to another command, PowerShell tries to associate the piped objects with one +of the parameters of the receiving cmdlet. -When you "pipe" objects, that is send the objects in the output of one command to another -command, Windows PowerShell tries to associate the piped objects with one of the parameters -of the receiving cmdlet. - -To do so, the Windows PowerShell "parameter binding" component, which associates input objects -with cmdlet parameters, tries to find a parameter that meets the following criteria: +To do so, the PowerShell "parameter binding" component, which associates input +objects with cmdlet parameters, tries to find a parameter that meets the +following criteria: - The parameter must accept input from a pipeline (not all do) -- The parameter must accept the type of object being sent or a type that the object -can be converted to. +- The parameter must accept the type of object being sent or a type that the + object can be converted to. - The parameter must not already be used in the command. -For example, the `Start-Service` cmdlet has many parameters, but only two of them, `-Name` and `-InputObject` -accept pipeline input. The `-Name` parameter takes strings and the `-InputObject` parameter takes -service objects. Therefore, you can pipe strings and service objects (and objects with properties -that can be converted to string and service objects) to `Start-Service`. +For example, the `Start-Service` cmdlet has many parameters, but only two of +them, `-Name` and `-InputObject` accept pipeline input. The `-Name` parameter +takes strings and the `-InputObject` parameter takes service objects. +Therefore, you can pipe strings and service objects (and objects with +properties that can be converted to string and service objects) to +`Start-Service`. -If the parameter binding component of Windows PowerShell cannot associate the piped objects -with a parameter of the receiving cmdlet, the command fails and Windows PowerShell prompts you -for the missing parameter values. +If the parameter binding component of PowerShell cannot associate the piped +objects with a parameter of the receiving cmdlet, the command fails and +PowerShell prompts you for the missing parameter values. -You cannot force the parameter binding component to associate the piped objects with a particular -parameter -- you cannot even suggest a parameter. Instead, the logic of the component manages -the piping as efficiently as possible. +You cannot force the parameter binding component to associate the piped +objects with a particular parameter. You cannot even suggest a parameter. +Instead, the logic of the component manages the piping as efficiently as +possible. ### One-At-A-Time Processing +Piping objects to a command is much like using a parameter of the command to +submit the objects. -Piping objects to a command is much like using a parameter of the command to submit the -objects. - -For example, piping objects representing the services on the computer to a `Format-Table` command, -such as: +For example, piping objects representing the services on the computer to a +`Format-Table` command, such as: ```powershell Get-Service | Format-Table -Property name, dependentservices ``` -is much like saving the service objects in a variable and using the InputObject parameter -of `Format-Table` to submit the service object. +is much like saving the service objects in a variable and using the +InputObject parameter of `Format-Table` to submit the service object. For example, + ```powershell $services = Get-Service Format-Table -InputObject $services -Property name, dependentservices @@ -236,51 +234,58 @@ Format-Table -InputObject $services -Property name, dependentservices or imbedding the command in the parameter value For example, + ```powershell -Format-Table -InputObject (Get-Service wmi) -Property name, dependentservices +Format-Table -InputObject (Get-Service wmi) -Property name,dependentservices ``` -However, there is an important difference. When you pipe multiple objects to a command, -Windows PowerShell sends the objects to the command one at a time. When you use a -command parameter, the objects are sent as a single array object. +However, there is an important difference. When you pipe multiple objects to a +command, PowerShell sends the objects to the command one at a time. When you +use a command parameter, the objects are sent as a single array object. + +This seemingly technical difference can have interesting, and sometimes +useful, consequences. -This seemingly technical difference can have interesting, and sometimes useful, consequences. +For example, if you pipe multiple process objects from the `Get-Process` +cmdlet to the `Get-Member` cmdlet, PowerShell sends each process object, one +at a time, to `Get-Member`. `Get-Member` displays the .NET class (type) of the +process objects, and their properties and methods. -For example, if you pipe multiple process objects from the `Get-Process` cmdlet to the -`Get-Member` cmdlet, Windows PowerShell sends each process object, one at a time, to `Get-Member`. -`Get-Member` displays the .NET class (type) of the process objects, and their properties and methods. -(`Get-Member` eliminates duplicates, so if the objects are all of the same type, it displays only -one object type.) +NOTE: `Get-Member` eliminates duplicates, so if the objects are all of the +same type, it displays only one object type. -In this case, `Get-Member` displays the properties and methods of each process object, that is, a -System.Diagnostics.Process object. +In this case, `Get-Member` displays the properties and methods of each process +object, that is, a System.Diagnostics.Process object. For example, + ```powershell Get-Process | Get-Member ``` -``` +```Output TypeName: System.Diagnostics.Process -Name MemberType Definition ----- ---------- ---------- -Handles AliasProperty Handles = Handlecount -Name AliasProperty Name = ProcessName -NPM AliasProperty NPM = NonpagedSystemMemorySize +Name MemberType Definition +---- ---------- ---------- +Handles AliasProperty Handles = Handlecount +Name AliasProperty Name = ProcessName +NPM AliasProperty NPM = NonpagedSystemMemorySize ... ``` -However, if you use the InputObject parameter of `Get-Member`, then `Get-Member` receives an -array of System.Diagnostics.Process objects as a single unit, and it displays the properties -of an array of objects. (Note the array symbol ([]) after the System.Object type name.) +However, if you use the InputObject parameter of `Get-Member`, then +`Get-Member` receives an array of System.Diagnostics.Process objects as a +single unit, and it displays the properties of an array of objects. (Note the +array symbol ([]) after the System.Object type name.) For example, + ```powershell Get-Member -InputObject (Get-Process) ``` -``` +```Output TypeName: System.Object[] Name MemberType Definition @@ -291,30 +296,32 @@ Clone Method System.Object Clone() ... ``` -This result might not be what you intended, but after you understand it, you can use it. For -example, an array of process objects has a Count property that you can use to count the number -of processes on the computer. +This result might not be what you intended, but after you understand it, you +can use it. For example, an array of process objects has a Count property that +you can use to count the number of processes on the computer. For example, + ```powershell (Get-Process).count ``` -This distinction can be important, so remember that when you pipe objects to a cmdlet, they -are delivered one at a time. +This distinction can be important, so remember that when you pipe objects to a +cmdlet, they are delivered one at a time. ### Accepts Pipeline Input -In order to receive objects in a pipeline, the receiving cmdlet must have a parameter -that accepts pipeline input. You can use a `Get-Help` command with the **Full** or **Parameter** -parameters to determine which, if any, of a cmdlet's parameters accepts pipeline input. +In order to receive objects in a pipeline, the receiving cmdlet must have a +parameter that accepts pipeline input. You can use a `Get-Help` command with +the **Full** or **Parameter** parameters to determine which, if any, of a +cmdlet's parameters accepts pipeline input. -In the `Get-Help` default display, the "Accept pipeline input?" item appears in a table -of parameter attributes. This table is displayed only when you use the **Full** or **Parameter** -parameters of the `Get-Help` cmdlet. +In the `Get-Help` default display, the "Accept pipeline input?" item appears +in a table of parameter attributes. This table is displayed only when you use +the **Full** or **Parameter** parameters of the `Get-Help` cmdlet. -For example, to determine which of the parameters of the `Start-Service` cmdlet accepts -pipeline input, type: +For example, to determine which of the parameters of the `Start-Service` +cmdlet accepts pipeline input, type: ```powershell Get-Help Start-Service -Full @@ -326,108 +333,115 @@ or Get-Help Start-Service -Parameter * ``` -For example, the help for the `Start-Service` cmdlet shows that the **InputObject** and **Name** -parameters accept pipeline input ("true"). All other parameters have a value of "false" -in the "Accept pipeline input?" row. +For example, the help for the `Start-Service` cmdlet shows that the +**InputObject** and **Name** parameters accept pipeline input ("true"). All +other parameters have a value of "false" in the "Accept pipeline input?" row. ``` -InputObject - Specifies ServiceController objects representing the services to be started. - Enter a variable that contains the objects, or type a command or expression - that gets the objects. +Specifies ServiceController objects representing the services to be started. +Enter a variable that contains the objects, or type a command or expression +that gets the objects. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByValue) +Accept wildcard characters? false -Name - Specifies the service names for the service to be started. +Specifies the service names for the service to be started. - The parameter name is optional. You can use Name or its alias, ServiceName, - or you can omit the parameter name. +The parameter name is optional. You can use Name or its alias, ServiceName, +or you can omit the parameter name. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByPropertyName, ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByPropertyName, ByValue) +Accept wildcard characters? false ``` This means that you can send objects (PsObjects) through the pipeline to the -`Where-Object` cmdlet and Windows PowerShell will associate the object with the +`Where-Object` cmdlet and PowerShell will associate the object with the **InputObject** and **Name** parameters. ### Methods Of Accepting Pipeline Input - Cmdlets parameters can accept pipeline input in one of two different ways: - ByValue: Parameters that accept input "by value" can accept piped objects -that have the same .NET type as their parameter value or objects that can be -converted to that type. - -For example, the Name parameter of `Start-Service` accepts pipeline input -by value. It can accept string objects or objects that can be converted to -strings. + that have the same .NET type as their parameter value or objects that can be + converted to that type. -- ByPropertyName: Parameters that accept input "by property name" can accept piped -objects only when a property of the object has the same name as the parameter. + For example, the Name parameter of `Start-Service` accepts pipeline input by + value. It can accept string objects or objects that can be converted to + strings. -For example, the Name parameter of `Start-Service` can accept objects that have -a Name property. +- ByPropertyName: Parameters that accept input "by property name" can accept + piped objects only when a property of the object has the same name as the + parameter. -(To list the properties of an object, pipe it to `Get-Member`.) + For example, the Name parameter of `Start-Service` can accept objects that + have a Name property. To list the properties of an object, pipe it to + `Get-Member`. -Some parameters can accept objects by value or by property name. These parameters are -designed to take input from the pipeline easily. +Some parameters can accept objects by value or by property name. These +parameters are designed to take input from the pipeline easily. ### Investigating Pipeline Errors - -If a command fails because of a pipeline error, you can investigate the failure and -rewrite the command. +If a command fails because of a pipeline error, you can investigate the +failure and rewrite the command. For example, the following command tries to move a registry entry from one -registry key to another by using the `Get-Item` cmdlet to get the destination path and -then piping the path to the `Move-ItemProperty` cmdlet. +registry key to another by using the `Get-Item` cmdlet to get the destination +path and then piping the path to the `Move-ItemProperty` cmdlet. -Specifically, the command uses the `Get-Item` cmdlet to get the destination path. It uses -a pipeline operator to send the result to the `Move-ItemProperty` cmdlet. The `Move-ItemProperty` -command specifies the current path and name of the registry entry to be moved. +Specifically, the command uses the `Get-Item` cmdlet to get the destination +path. It uses a pipeline operator to send the result to the +`Move-ItemProperty` cmdlet. The `Move-ItemProperty` command specifies the +current path and name of the registry entry to be moved. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product ``` -``` -The command fails and Windows PowerShell displays the following error +The command fails and PowerShell displays the following error message: -Move-ItemProperty : The input object cannot be bound to any parameters for the -command either because the command does not take pipeline input or the input -and its properties do not match any of the parameters that take pipeline input. +```output +Move-ItemProperty : The input object cannot be bound to any parameters for +the command either because the command does not take pipeline input or the +input and its properties do not match any of the parameters that take +pipeline input. At line:1 char:23 -+ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name product ++ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name p ``` -To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding component of -Windows PowerShell. The following command traces the Parameter Binding component while the -command is processing. It uses the `-PSHost` parameter to display the results at the console -and the `-filepath` command to send them to the debug.txt file for later reference. +To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding +component of PowerShell. The following command traces the Parameter Binding +component while the command is processing. It uses the `-PSHost` parameter to +display the results at the console and the `-filepath` command to send them to +the debug.txt file for later reference. For example, + ```powershell -Trace-Command -Name parameterbinding -Expression {Get-Item -Path HKLM:\software\mycompany\sales | -Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} -PSHost -FilePath debug.txt +Trace-Command -Name parameterbinding -Expression { + Get-Item -Path HKLM:\software\mycompany\sales | + Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} ` + -PSHost -FilePath debug.txt ``` -The results of the trace are lengthy, but they show the values being bound to the `Get-Item` cmdlet -and then the named values being bound to the `Move-ItemProperty` cmdlet. +The results of the trace are lengthy, but they show the values being bound to +the `Get-Item` cmdlet and then the named values being bound to the +`Move-ItemProperty` cmdlet. +``` ... BIND NAMED cmd line args [`Move-ItemProperty`] @@ -442,31 +456,35 @@ BIND arg [product] to parameter [Name] BIND POSITIONAL cmd line args [`Move-ItemProperty`] ... +``` -Finally, it shows that the attempt to bind the path to the Destination parameter -of `Move-ItemProperty` failed. +Finally, it shows that the attempt to bind the path to the **Destination** +parameter of `Move-ItemProperty` failed. +``` ... BIND PIPELINE object to parameters: [`Move-ItemProperty`] PIPELINE object TYPE = [Microsoft.Win32.RegistryKey] RESTORING pipeline parameter's original values -Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION -Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION +Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO CO +ERCION +Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COE +RCION ... +``` - -To investigate the failure, use the `Get-Help` cmdlet to view the attributes of the -**Destination** parameter. The following command gets detailed information about the -**Destination** parameter. +To investigate the failure, use the `Get-Help` cmdlet to view the attributes +of the **Destination** parameter. The following command gets detailed +information about the **Destination** parameter. ```powershell Get-Help Move-ItemProperty -Parameter Destination ``` -The results show that **Destination** takes pipeline input only "by property name". -That is, the piped object must have a property named Destination. +The results show that **Destination** takes pipeline input only "by property +name". That is, the piped object must have a property named Destination. ``` -Destination @@ -479,11 +497,12 @@ That is, the piped object must have a property named Destination. Accept wildcard characters? false ``` -To see the properties of the object being piped to the `Move-ItemProperty` cmdlet, -pipe it to the `Get-Member` cmdlet. The following command pipes the results of the -first part of the command to the `Get-Member` cmdlet. +To see the properties of the object being piped to the `Move-ItemProperty` +cmdlet, pipe it to the `Get-Member` cmdlet. The following command pipes the +results of the first part of the command to the `Get-Member` cmdlet. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Get-Member ``` @@ -491,11 +510,13 @@ Get-Item -Path HKLM:\software\mycompany\sales | Get-Member The output shows that the item is a Microsoft.Win32.RegistryKey that does not have a Destination property. That explains why the command failed. -To fix the command, we must specify the destination in the `Move-ItemProperty` cmdlet. We can -use a `Get-ItemProperty` command to get the path, but the name and destination must be specified -in the `Move-ItemProperty` part of the command. +To fix the command, we must specify the destination in the `Move-ItemProperty` +cmdlet. We can use a `Get-ItemProperty` command to get the path, but the name +and destination must be specified in the `Move-ItemProperty` part of the +command. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\design | Move-ItemProperty -Dest HKLM:\software\mycompany\design -Name product @@ -510,9 +531,11 @@ Get-Itemproperty HKLM:\software\mycompany\sales The results show that the Product registry entry was moved to the Sales key. -``` -PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany\sales -PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany +```Output +PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany\sales +PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany PSChildName : sales PSDrive : HKLM PSProvider : Microsoft.PowerShell.Core\Registry diff --git a/reference/5.1/Microsoft.PowerShell.Management/Get-Process.md b/reference/5.1/Microsoft.PowerShell.Management/Get-Process.md index ef6667752ed2..a9eb47e22aff 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Get-Process.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Get-Process.md @@ -103,22 +103,23 @@ The pipeline operator passes the objects to the **Format-Table** cmdlet, which f The Priority view, and other views, are defined in the PS1XML format files in the Windows PowerShell home directory ($pshome). ### Example 5: Add a property to the standard Get-Process output display -``` -PS C:\> Get-Process Powershell -ComputerName S1, localhost | ft @{Label="NPM(K)";Expression={[int]($_.NPM/1024)}}, @{Label="PM(K)";Expression={[int]($_.PM/1024)}},@{Label="WS(K)";Expression={[int]($_.WS/1024)}},@{Label="VM(M)";Expression={[int]($_.VM/1MB)}}, @{Label="CPU(s)";Expression={if ($_.CPU -ne $()) { $_.CPU.ToString("N")}}}, Id, MachineName, ProcessName -Auto - - - - - +```powershell +PS C:\> Get-Process powershell -ComputerName S1, localhost | + ft @{Label = "NPM(K)"; Expression = {[int]($_.NPM / 1024)}}, + @{Label = "PM(K)"; Expression = {[int]($_.PM / 1024)}}, + @{Label = "WS(K)"; Expression = {[int]($_.WS / 1024)}}, + @{Label = "VM(M)"; Expression = {[int]($_.VM / 1MB)}}, + @{Label = "CPU(s)"; Expression = {if ($_.CPU) {$_.CPU.ToString("N")}}}, + Id, MachineName, ProcessName -Auto NPM(K) PM(K) WS(K) VM(M) CPU(s) Id MachineName ProcessName ------ ----- ----- ----- ------ -- ----------- ----------- -6 23500 31340 142 1980 S1 powershell -6 23500 31348 142 4016 S1 powershell -27 54572 54520 576 4428 localhost powershell + 6 23500 31340 142 1.70 1980 S1 powershell + 6 23500 31348 142 2.75 4016 S1 powershell + 27 54572 54520 576 5.52 4428 localhost powershell ``` -This example provides a **Format-Table** (alias = ft) command that adds the **MachineName** property to the standard **Get-Process** output display. +This example provides a `Format-Table` (alias = ft) command that adds the MachineName property to the standard `Get-Process` output display. ### Example 6: Get version information for a process ``` diff --git a/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md b/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md index fa5760965827..f13fac95f272 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md @@ -15,9 +15,9 @@ Combines a path and a child path into a single path. ## SYNTAX -``` -Join-Path [-Path] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] - [] +```powershell +Join-Path [-Path] [-ChildPath] + [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Object_Creation.md b/reference/6/Microsoft.PowerShell.Core/About/about_Object_Creation.md index 65a910c9ccab..0f745ac3aa94 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Object_Creation.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Object_Creation.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,232 +7,246 @@ title: about_Object_Creation --- # About Object Creation -## about_Object_Creation - ## SHORT DESCRIPTION -Explains how to create objects in Windows PowerShell. +Explains how to create objects in PowerShell. ## LONG DESCRIPTION -You can create objects in Windows PowerShell and use the objects that you create in commands and scripts. - -There are several ways to create objects: - -New-Object: -The New-Object cmdlet creates an instance of a .NET Framework object or COM object. +You can create objects in PowerShell and use the objects that you create in +commands and scripts. -Hash tables: +There are several ways to create objects: -Beginning in Windows PowerShell 3.0, you can create objects from hash tables of property names and property values. +- `New-Object`: This cmdlet creates an instance of a .NET Framework object or + COM object. -Import-Csv: +- Hash tables: Beginning in PowerShell 3.0, you can create objects + from hash tables of property names and property values. -The Import-Csv cmdlet creates custom objects (PSCustomObject) from the items in a CSV file. Each row is an object instance and each column is an object property. +- `Import-Csv`: This cmdlet creates custom objects (PSCustomObject) from the + items in a CSV file. Each row is an object instance and each column is an + object property. This topic will demonstrate and discuss each of these methods. - ## NEW-OBJECT -The New-Object cmdlet provides a robust and consistent way to create new objects. The cmdlet works with almost all types and in all supported versions of Windows PowerShell. -To create a new object, specify either the type of a .NET Framework class or a ProgID of a COM object. +The `New-Object` cmdlet provides a robust and consistent way to create new +objects. The cmdlet works with almost all types and in all supported versions +of PowerShell. -For example, the following command creates a Version object. +To create a new object, specify either the type of a .NET Framework class or a +ProgID of a COM object. +For example, the following command creates a Version object. -``` -PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 +```powershell +PS C:\> $v = New-Object -TypeName System.Version -ArgumentList 2.0.0.1 PS C:\> $v ``` - - -``` -Major Minor Build Revision ------ ----- ----- -------- +```Output +Major Minor Build Revision +----- ----- ----- -------- 2 0 0 1 ``` +```powershell +PS C:\> $v | Get-Member - -``` -PS C:\> $v | Get-Member - TypeName: System.Version ``` - For more information, see the help topic for the New-Object cmdlet. - ### CREATE 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: ``` -[]@{=;=} +[]@{ + = + = +} ``` - -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. ### CREATE CUSTOM OBJECTS FROM HASH TABLES -Custom objects are very useful and they are very easy to create by using the hash table method. To create a custom object, use the PSCustomObject class, a class designed specifically for this purpose. - -Custom objects are an excellent way to return customized output from a function or script; far more useful than returning formatted output that cannot be reformatted or piped to other commands. - -The commands in the Test-Object function set some variable values and then use those values to create a custom object. (You can see this object in use in the example section of the Update-Help cmdlet help topic.) - -``` -function Test-Object -{ $ModuleName = "PSScheduledJob" - $HelpCulture = "en-us" - $HelpVersion = "3.1.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} - - $ModuleName = "PSWorkflow" - $HelpCulture = "en-us" - $HelpVersion = "3.0.0.0" - [PSCustomObject]@{"ModuleName"=$ModuleName; "UICulture"=$HelpCulture; "Version"=$HelpVersion} +Custom objects are very useful and they are very easy to create by using the +hash table method. To create a custom object, use the PSCustomObject class, a +class designed specifically for this purpose. + +Custom objects are an excellent way to return customized output from a +function or script; far more useful than returning formatted output that +cannot be reformatted or piped to other commands. + +The commands in the `Test-Object function` set some variable values and then +use those values to create a custom object. You can see this object in use in +the example section of the `Update-Help` cmdlet help topic. + +```powershell +function Test-Object { + $ModuleName = "PSScheduledJob" + $HelpCulture = "en-us" + $HelpVersion = "3.1.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } + $ModuleName = "PSWorkflow" + $HelpCulture = "en-us" + $HelpVersion = "3.0.0.0" + [PSCustomObject]@{ + "ModuleName"=$ModuleName + "UICulture"=$HelpCulture + "Version"=$HelpVersion + } } ``` +The output of this function is a collection of custom objects formatted as a +table by default. -The output of this function is a collection of custom objects formatted as a table by default. - +```powershell +PS C:\> Test-Object -``` -PS C:\> Test-Object - -ModuleName UICulture Version ---------- --------- ------- -PSScheduledJob en-us 3.1.0.0 +ModuleName UICulture Version +--------- --------- ------- +PSScheduledJob en-us 3.1.0.0 PSWorkflow en-us 3.0.0.0 ``` +Users can manage the properties of the custom objects just as they do with +standard objects. -Users can manage the properties of the custom objects just as they do with standard objects. - - -``` -PS C:\> (Test-Object).ModuleName - PSScheduledJob +```powershell +PS C:\> (Test-Object).ModuleName + PSScheduledJob PSWorkflow ``` - - #### CREATE NON-CUSTOM OBJECTS FROM HASH TABLES -You can also use hash tables to create objects for non-custom classes. When you create an object for a non-custom class, the full namespace name is required unless class is in the System namespace. Use only the properties of the class. -For example, the following command creates a session option object. +You can also use hash tables to create objects for non-custom classes. When +you create an object for a non-custom class, the full namespace name is +required unless class is in the System namespace. Use only the properties of +the class. +For example, the following command creates a session option object. +```powershell +[System.Management.Automation.Remoting.PSSessionOption]@{ + IdleTimeout=43200000 + SkipCnCheck=$True +} ``` -[System.Management.Automation.Remoting.PSSessionOption]@{IdleTimeout=43200000; SkipCnCheck=$True} -``` - -The requirements of the hash table feature, especially the null constructor requirement, eliminate many existing classes. However, most Windows PowerShell option classes are designed to work with this feature, as well as other very useful classes, such as the ScheduledJobTrigger class. +The requirements of the hash table feature, especially the null constructor +requirement, eliminate many existing classes. However, most PowerShell option +classes are designed to work with this feature, as well as other very useful +classes, such as the ScheduledJobTrigger class. +```powershell +[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{ + Frequency="Daily" + At="15:00" +} -``` -[Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger]@{Frequency="Daily";At="15:00"} - -Id Frequency Time DaysOfWeek Enabled --- --------- ---- ---------- ------- -0 Daily 6/6/2012 3:00:00 PM True +Id Frequency Time DaysOfWeek Enabled +-- --------- ---- ---------- ------- +0 Daily 6/6/2012 3:00:00 PM True ``` +You can also use the hash table feature when setting parameter values. For +example, the value of the **SessionOption** parameter of the New-PSSession +cmdlet and the value of the JobTrigger parameter of `Register-ScheduledJob` +can be a hash table. -You can also use the hash table feature when setting parameter values. For example, the value of the SessionOption parameter of the New-PSSession cmdlet and the value of the JobTrigger parameter of Register-ScheduledJob can be a hash table. - - -``` -New-PSSession -ComputerName Server01 -SessionOption @{IdleTimeout=43200000; SkipCnCheck=$True} -Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{Frequency="Daily";At="15:00"} +```powershell +New-PSSession -ComputerName Server01 -SessionOption @{ + IdleTimeout=43200000 + SkipCnCheck=$True +} +Register-ScheduledJob Name Test -FilePath .\Get-Inventory.ps1 -Trigger @{ + Frequency="Daily" + At="15:00" +} ``` - - ### IMPORT-CSV -You can create custom objects from the items in a CSV file. When you use the Import-Csv cmdlet to import the CSV file, the cmdlet creates a custom object (PSCustomObject) for each item in the file. The column names are the object properties. -For example, if you import a CSV file of computer asset data, Import-CSV creates a collection of custom objects from the input. +You can create custom objects from the items in a CSV file. When you use the +`Import-Csv` cmdlet to import the CSV file, the cmdlet creates a custom object +(PSCustomObject) for each item in the file. The column names are the object +properties. +For example, if you import a CSV file of computer asset data, `Import-CSV` +creates a collection of custom objects from the input. ``` -#In Servers.csv -AssetID, Name, OS, Department -003, Server01, Windows Server 2012, IT -103, Server33, Windows 7, Marketing +#In Servers.csv +AssetID, Name, OS, Department +003, Server01, Windows Server 2012, IT +103, Server33, Windows 7, Marketing 212, Server35, Windows 8, Finance ``` +```powershell +PS C:\> $a = Import-Csv Servers.csv +PS C:\> $a - -``` -PS C:\> $a = Import-Csv Servers.csv -PS C:\> $a - -AssetID Name OS Department -------- ---- -- ---------- -003 Server01 Windows Server 2012 IT -103 Server33 Windows 7 Marketing +AssetID Name OS Department +------- ---- -- ---------- +003 Server01 Windows Server 2012 IT +103 Server33 Windows 7 Marketing 212 Server35 Windows 8 Finance ``` - Use the Get-Member cmdlet to confirm the object type. - -``` +```powershell PS C:\> $a | Get-Member ``` +```Output +TypeName: System.Management.Automation.PSCustomObject - -``` -TypeName: System.Management.Automation.PSCustomObject - -Name MemberType Definition ----- ---------- ---------- -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -AssetID NoteProperty System.String AssetID=003 -Department NoteProperty System.String Department=IT -Name NoteProperty System.String Name=Server01 +Name MemberType Definition +---- ---------- ---------- +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +AssetID NoteProperty System.String AssetID=003 +Department NoteProperty System.String Department=IT +Name NoteProperty System.String Name=Server01 OS NoteProperty System.String OS=Windows Server 2012 ``` - You can use the custom objects just as you would standard objects. - -``` +```powershell PS C:\> $a | where {$_.OS -eq "Windows 8"} ``` - - -``` -AssetID Name OS Department -------- ---- -- ---------- +```output +AssetID Name OS Department +------- ---- -- ---------- 212 Server35 Windows 8 Finance ``` - For more information, see the help topic for the Import-Csv cmdlet. - ## SEE ALSO [about_Objects](about_Objects.md) @@ -243,9 +257,8 @@ For more information, see the help topic for the Import-Csv cmdlet. [about_Pipelines](about_Pipelines.md) -Get-Member - -Import-Csv +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -New-Object +[Import-Csv](../../Microsoft.PowerShell.Utility/Import-Csv.md) +[New-Object](../../Microsoft.PowerShell.Utility/New-Object.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Objects.md b/reference/6/Microsoft.PowerShell.Core/About/about_Objects.md index 88ab499af532..58308cabd6d7 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Objects.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Objects.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -58,20 +58,13 @@ directory objects are passed down the pipeline to the second command. The second command `where { $_.PsIsContainer -eq $false }` uses the PsIsContainer property of all file system objects to select only -files, which have a value of False ($false) in their PsIsContainer +files, which have a value of False (\$false) in their PsIsContainer property. Folders, which are containers and, thus, have a value of -True ($true) in their PsIsContainer property, are not selected. +True (\$true) in their PsIsContainer property, are not selected. The second command passes only the file objects to the third command `Format-List`, which displays the file objects in a list. -## For More Information - -Now that you understand a bit about objects, see the [about_Methods](about_Methods.md) -help topic to learn how to find and use object methods, the -[about_Properties](about_Properties.md) topic to learn how to find and use object properties, -and the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) topic, to learn how to find an object type. - ## See Also [about_Methods](about_Methods.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 6e83191b889c..01d129ccc4bb 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,84 +10,85 @@ title: about_Operator_Precedence ## SHORT DESCRIPTION -Lists the Windows PowerShell operators in precedence order. +Lists the PowerShell operators in precedence order. -[This topic was contributed by Kirk Munro, a Windows PowerShell MVP +[This topic was contributed by Kirk Munro, a PowerShell MVP from Ottawa, Ontario] ## LONG DESCRIPTION -Windows PowerShell operators let you construct simple, but powerful -expressions. This topic lists the operators in precedence order. -Precedence order is the order in which Windows PowerShell evaluates -the operators when multiple operators appear in the same expression. - -When operators have equal precedence, Windows PowerShell evaluates -them from left to right. The exceptions are the assignment operators, -the cast operators, and the negation operators (!, -not, -bnot), -which are evaluated from right to left. - -You can use enclosures, such as parentheses, to override the -standard precedence order and force Windows PowerShell to evaluate -the enclosed part of an expression before an unenclosed part. - -In the following list, operators are listed in the order that they -are evaluated. Operators on the same line, or in the same group, have -equal precedence. - -The Operator column lists the operators. The Reference column lists -the Windows PowerShell Help topic in which the operator is described. -To display the topic, type `get-help `. - -|OPERATOR|REFERENCE| -|--------|---------| -|`$() @()`|[about_Operators](#index-operator)| -|`.` (dereference) `::` (static)|[about_Operators](about_Operators.md)| -|`[0]` (index operator)|[about_Operators](about_Operators.md)| +PowerShell operators let you construct simple, but powerful +expressions. This topic lists the operators in precedence order. Precedence +order is the order in which PowerShell evaluates the operators when +multiple operators appear in the same expression. + +When operators have equal precedence, PowerShell evaluates them from +left to right. The exceptions are the assignment operators, the cast +operators, and the negation operators (!, -not, -bnot), which are evaluated +from right to left. + +You can use enclosures, such as parentheses, to override the standard +precedence order and force PowerShell to evaluate the enclosed part of +an expression before an unenclosed part. + +In the following list, operators are listed in the order that they are +evaluated. Operators on the same line, or in the same group, have equal +precedence. + +The Operator column lists the operators. The Reference column lists the +PowerShell Help topic in which the operator is described. To display +the topic, type `get-help `. + +|OPERATOR |REFERENCE| +|------------------------|---------| +|`$() @()` |[about_Operators](#index-operator)| +|`.` (dereference) |[about_Operators](about_Operators.md)| +|`::` (static) |[about_Operators](about_Operators.md)| +|`[0]` (index operator) |[about_Operators](about_Operators.md)| |`[int]` (cast operators)|[about_Operators](about_Operators.md)| -|`-split` (unary)
`-join` (unary)|[about_Split](about_Split.md)
[about_Join](about_Join.md)| -|`,` (comma operator)|[about_Operators](about_Operators.md)| -|`++ --`|[about_Assignment_Operators](about_Assignment_Operators.md)| -|`-not`
`! -bNot`|[about_Logical_Operators](about_logical_operators.md)
[about_Comparison_Operators](about_Comparison_Operators.md)| -|`..` (range operator)|[about_Operators](about_Operators.md)| -|`-f` (format operator)|[about_Operators](about_Operators.md)| -|`* / %`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`+ -`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| - - -The following group of operators have equal precedence. Their -case-sensitive and explicitly case-insensitive variants have -the same precedence. - -|OPERATOR|REFERENCE| -|--------|---------| -|`-split` (unary)|[about_Split](about_Split.md)| -|`-join` (unary)|[about_Join](about_Join.md)| -|`-is -isnot -as`|[about_Type_Operators](about_Type_Operators.md)| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`,` (comma operator) |[about_Operators](about_Operators.md)| +|`++ --` |[about_Assignment_Operators](about_Assignment_Operators.md)| +|`-not` |[about_Logical_Operators](about_logical_operators.md)| +|`! -bNot` |[about_Comparison_Operators](about_Comparison_Operators.md)| +|`..` (range operator) |[about_Operators](about_Operators.md)| +|`-f` (format operator) |[about_Operators](about_Operators.md)| +|`* / % + -` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| + +The following group of operators have equal precedence. Their case-sensitive +and explicitly case-insensitive variants have the same precedence. + +|OPERATOR |REFERENCE| +|-------------------------|---------| +|`-split` (unary) |[about_Split](about_Split.md)| +|`-join` (unary) |[about_Join](about_Join.md)| +|`-is -isnot -as` |[about_Type_Operators](about_Type_Operators.md)| |`-eq -ne -gt -gt -lt -le`|[about_Comparison_Operators](about_Comparison_Operators.md)| -|`-like -notlike`|[about_comparison_operators](about_comparison_operators.md)| -|`-match -notmatch`|[about_comparison_operators](about_comparison_operators.md)| -|`-in -notIn`|[about_comparison_operators](about_comparison_operators.md)| -|`-contains -notContains`|[about_comparison_operators](about_comparison_operators.md)| -|`-replace`|[about_comparison_operators](about_comparison_operators.md)| +|`-like -notlike` |[about_comparison_operators](about_comparison_operators.md)| +|`-match -notmatch` |[about_comparison_operators](about_comparison_operators.md)| +|`-in -notIn` |[about_comparison_operators](about_comparison_operators.md)| +|`-contains -notContains` |[about_comparison_operators](about_comparison_operators.md)| +|`-replace` |[about_comparison_operators](about_comparison_operators.md)| The list resumes here with the following operators in precedence order: -|OPERATOR|REFERENCE| -|--------|---------| -|`-band -bor -bxor`|[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor`|[about_comparison_operators](about_comparison_operators.md)| -|`.` (dot-source)
`&` (call)|[about_Scopes](about_Scopes.md)
[about_Operators](about_Operators.md)| +|OPERATOR |REFERENCE| +|--------------------------|---------| +|`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| +|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`.` (dot-source) |[about_Scopes](about_Scopes.md)| +|`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| -|`> >> 2> 2>> 2>&1`|[about_Redirection](about_Redirection.md)| -|`= += -= *= /= %=`|[about_Assignment_Operators](about_Assignment_Operators.md)| +|`> >> 2> 2>> 2>&1` |[about_Redirection](about_Redirection.md)| +|`= += -= *= /= %=` |[about_Assignment_Operators](about_Assignment_Operators.md)| # EXAMPLES -The following two commands show the arithmetic operators and -the effect of using parentheses to force Windows PowerShell to -evaluate the enclosed part of the expression first. +The following two commands show the arithmetic operators and the effect of +using parentheses to force PowerShell to evaluate the enclosed part of +the expression first. ```powershell C:\PS> 2 + 3 * 4 @@ -97,8 +98,8 @@ C:\PS> (2 + 3) * 4 20 ``` -The following example gets the read-only text files from the local -directory and saves them in the `$read_only` variable. +The following example gets the read-only text files from the local directory +and saves them in the `$read_only` variable. ```powershell $read_only = get-childitem *.txt | where-object {$_.isReadOnly} @@ -109,37 +110,37 @@ It is equivalent to the following example. $read_only = ( get-childitem *.txt | where-object {$_.isReadOnly} ) ``` -Because the pipeline operator (|) has a higher precedence than the -assignment operator (=), the files that the Get-ChildItem cmdlet -gets are sent to the Where-Object cmdlet for filtering before they -are assigned to the $read_only variable. +Because the pipeline operator (|) has a higher precedence than the assignment +operator (=), the files that the Get-ChildItem cmdlet gets are sent to the +Where-Object cmdlet for filtering before they are assigned to the $read_only +variable. -The following example demonstrates that the index operator takes -precedence over the cast operator. +The following example demonstrates that the index operator takes precedence +over the cast operator. -The first expression creates an array of three strings. Then, it -uses the index operator with a value of 0 to select the first object -in the array, which is the first string. Finally, it casts the -selected object as a string. In this case, the cast has no effect. +The first expression creates an array of three strings. Then, it uses the +index operator with a value of 0 to select the first object in the array, +which is the first string. Finally, it casts the selected object as a string. +In this case, the cast has no effect. ```powershell C:\PS> [string]@('Windows','PowerShell','2.0')[0] Windows ``` -The second expression uses parentheses to force the cast operation -to occur before the index selection. As a result, the entire array -is cast as a (single) string. Then, the index operator selects -the first item in the string array, which is the first character. +The second expression uses parentheses to force the cast operation to occur +before the index selection. As a result, the entire array is cast as a +(single) string. Then, the index operator selects the first item in the string +array, which is the first character. ```powershell C:\PS> ([string]@('Windows','PowerShell','2.0'))[0] W ``` -In the following example, because the -gt (greater-than) operator -has a higher precedence than the -and (logical AND) operator, the -result of the expression is FALSE. +In the following example, because the -gt (greater-than) operator has a higher +precedence than the -and (logical AND) operator, the result of the expression +is FALSE. ```powershell C:\PS> 2 -gt 4 -and 1 @@ -160,11 +161,11 @@ C:\PS> 2 -gt (4 -and 1) True ``` -However, this example demonstrates an important principle of managing -operator precedence. When an expression is difficult for people to -interpret, use parentheses to force the evaluation order, even when it -forces the default operator precedence. The parentheses make your -intentions clear to people who are reading and maintaining your scripts. +However, this example demonstrates an important principle of managing operator +precedence. When an expression is difficult for people to interpret, use +parentheses to force the evaluation order, even when it forces the default +operator precedence. The parentheses make your intentions clear to people who +are reading and maintaining your scripts. ## SEE ALSO @@ -185,4 +186,3 @@ intentions clear to people who are reading and maintaining your scripts. [about_Split](about_Split.md) [about_Type_Operators](about_Type_Operators.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md b/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md index 86512bc2df24..7933f7f0a80e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,87 +7,81 @@ title: about_PackageManagement --- # About PackageManagement -## about_PackageManagement -# TOPIC -about_PackageManagement - -# SHORT DESCRIPTION +## SHORT DESCRIPTION PackageManagement is an aggregator for software package managers. -# LONG DESCRIPTION +## LONG DESCRIPTION PackageManagement functionality was introduced in Windows PowerShell 5.0. -PackageManagement is a unified interface for software package management systems; you -can run PackageManagement cmdlets to perform software discovery, installation, and -inventory (SDII) tasks. Regardless of the underlying installation technology, -you can run the common cmdlets in the PackageManagement module to search for, -install, or uninstall packages; add, remove, and query package repositories; and -run queries on a computer to determine which software packages are installed. - -PackageManagement supports a flexible plug-in model that enables support for other -software package management systems. - -The PackageManagement module is included with Windows PowerShell 5.0 and later releases -of Windows PowerShell, and works on three levels of package management -structure: package providers, package sources, and the packages themselves. - -Term Description ----------- ------------------------------ -Package manager Software package management system. In -PackageManagement terms, this is a package provider. -Package provider PackageManagement term for a package manager. Examples -can include Windows Installer, Chocolatey, -and others. -Package source A URL, local folder, or network shared folder that -you configure package providers to use as a -repository. -Package A piece of software that a package provider manages, -and that is stored in a specific package source. - -The PackageManagement module includes the following cmdlets. You can find the -Help for these cmdlets on TechNet starting on the following page: -http://technet.microsoft.com/library/dn890951(v=wps.640).aspx. - -Cmdlet Description ----------- ------------------------------ -Get-PackageProvider Returns a list of package providers that are -connected to PackageManagement. -Get-PackageSource Gets a list of package sources that are -registered for a package provider. -Register-PackageSource Adds a package source for a specified -package provider. -Set-PackageSource Sets properties on an existing package -source. -Unregister-PackageSource Removes a registered package source. -Get-Package Returns a list of installed software -packages. -Find-Package Finds software packages in available -package sources. -Install-Package Installs one or more software packages. -Save-Package Saves packages to the local computer -without installing them. -Uninstall-Package Uninstalls one or more software packages. - -PackageManagement Package Provider Bootstrapping and Dynamic Cmdlet Parameters - -By default, PackageManagement ships with a core bootstrap provider. You can install -additional package providers as you need them by bootstrapping the providers; -that is, responding to a prompt to install the provider automatically, from a -web service. You can specify a package provider with any PackageManagement cmdlet; -if the specified provider is not available, PackageManagement prompts you to bootstrap ---or automatically install--the provider. In the following examples, if the -Chocolatey provider is not already installed, PackageManagement bootstrapping installs -the provider. - +PackageManagement is a unified interface for software package management +systems; you can run PackageManagement cmdlets to perform software discovery, +installation, and inventory (SDII) tasks. Regardless of the underlying +installation technology, you can run the common cmdlets in the +PackageManagement module to search for, install, or uninstall packages; add, +remove, and query package repositories; and run queries on a computer to +determine which software packages are installed. + +PackageManagement supports a flexible plug-in model that enables support for +other software package management systems. + +The PackageManagement module is included with Windows PowerShell 5.0 and later +releases of Windows PowerShell, and works on three levels of package +management structure: package providers, package sources, and the packages +themselves. Let us define some terms: + +- Package manager: Software package management system. In PackageManagement + terms, this is a package provider. +- Package provider: PackageManagement term for a package manager. Examples can + include Windows Installer, Chocolatey, and others. +- Package source: A URL, local folder, or network shared folder that you + configure package providers to use as a repository. +- Package: A piece of software that a package provider manages, and that is + stored in a specific package source. + +The PackageManagement module includes the following cmdlets. For more +information, see the +[PackageManagement](/powershell/gallery/psget/oneget/packagemanagement_cmdlets) +help. + +- `Get-PackageProvider`: Returns a list of package providers that are + connected to PackageManagement. +- `Get-PackageSource`: Gets a list of package sources that are registered for + a package provider. +- `Register-PackageSource`: Adds a package source for a specified package + provider. +- `Set-PackageSource`: Sets properties on an existing package source. +- `Unregister-PackageSource`: Removes a registered package source. +- `Get-Package`: Returns a list of installed software packages. +- `Find-Package`: Finds software packages in available package sources. +- `Install-Package`: Installs one or more software packages. +- `Save-Package`: Saves packages to the local computer without installing + them. +- `Uninstall-Package`: Uninstalls one or more software packages. + +### Package Provider Bootstrapping and Dynamic Cmdlet Parameters + +By default, PackageManagement ships with a core bootstrap provider. You can +install additional package providers as you need them by bootstrapping the +providers; that is, responding to a prompt to install the provider +automatically, from a web service. You can specify a package provider with any +PackageManagement cmdlet; if the specified provider is not available, +PackageManagement prompts you to bootstrap (or automatically install) the +provider. In the following examples, if the Chocolatey provider is not already +installed, PackageManagement bootstrapping installs the provider. + +```powershell Find-Package -Provider Chocolatey +``` If the Chocolatey provider is not already installed, when you run the preceding command, you are prompted to install it. +```powershell Install-Package -ForceBootstrap +``` If the Chocolatey provider is not already installed, when you run the preceding command, the provider is installed; but because the ForceBootstrap @@ -99,10 +93,10 @@ provider installed, and you do not add the ForceBootstrap parameter to your command, PackageManagement prompts you to install the provider. Specifying a package provider in your PackageManagement command can make -dynamic parameters available that are specific to that package provider. -When you run Get-Help for a specific PackageManagement cmdlet, a list of -parameter sets are returned, grouping dynamic parameters for available -package providers in separate parameter sets. +dynamic parameters available that are specific to that package provider. When +you run Get-Help for a specific PackageManagement cmdlet, a list of parameter +sets are returned, grouping dynamic parameters for available package providers +in separate parameter sets. More Information About the PackageManagement Project @@ -131,4 +125,3 @@ Install-Package Save-Package Uninstall-Package - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 871bcb0dd4f2..e9c4ebaefa98 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,449 +7,409 @@ title: about_Parameters_Default_Values --- # About Parameters Default Values -## about_Parameters_Default_Values - ## SHORT DESCRIPTION -Describes how to set custom default values for the parameters of cmdlets and advanced functions. +Describes how to set custom default values for the parameters of cmdlets and +advanced functions. ## LONG DESCRIPTION -The $PSDefaultParameterValues preference variable lets you specify custom default values for any cmdlet or advanced function. Cmdlets and functions use the custom default value unless you specify another value in the command. -The authors of cmdlets and advanced functions set standard default values for their parameters. Typically, the standard default values are useful, but they might not be appropriate for all environments. +The \$PSDefaultParameterValues preference variable lets you specify custom +default values for any cmdlet or advanced function. Cmdlets and functions use +the custom default value unless you specify another value in the command. + +The authors of cmdlets and advanced functions set standard default values for +their parameters. Typically, the standard default values are useful, but they +might not be appropriate for all environments. -This feature is especially useful when you must specify the same alternate parameter value nearly every time you use the command or when a particular parameter value is difficult to remember, such as an e-mail server name or project GUID. +This feature is especially useful when you must specify the same alternate +parameter value nearly every time you use the command or when a particular +parameter value is difficult to remember, such as an e-mail server name or +project GUID. -If the desired default value varies predictably, you can specify a script block that provides different default values for a parameter under different conditions. +If the desired default value varies predictably, you can specify a script +block that provides different default values for a parameter under different +conditions. -$PSDefaultParameterValues was introduced in Windows PowerShell 3.0. +\$PSDefaultParameterValues was introduced in PowerShell 3.0. +## SYNTAX -### SYNTAX The syntax of the $PSDefaultParameterValues preference variable is as follows: +```powershell +$PSDefaultParameterValues=@{":"=""} + +$PSDefaultParameterValues=@{":"={}} -``` -$PSDefaultParameterValues=@{":"=""} - -$PSDefaultParameterValues=@{":"={}} - $PSDefaultParameterValues["Disabled"]=$true | $false ``` - Wildcard characters are permitted in the CmdletName and ParameterName values. -The value of $PSDefaultParameterValues is a System.Management.Automation.DefaultParameterDictionary, a type of hash table that validates the format of keys. Enter a hash table where the key consists of the cmdlet name and parameter name separated by a colon (:) and the value is the custom default value. - -To set, change, add, or remove entries from $PSDefaultParameterValues, use the methods that you would use to edit a standard hash table. +The value of \$PSDefaultParameterValues is a +System.Management.Automation.DefaultParameterDictionary, a type of hash table +that validates the format of keys. Enter a hash table where the key consists +of the cmdlet name and parameter name separated by a colon (:) and the value +is the custom default value. -The must be the name of a cmdlet or the name of an advanced function that uses the CmdletBinding attribute. You cannot use $PSDefaultParameterValues to specify default values for scripts or simple functions. +To set, change, add, or remove entries from \$PSDefaultParameterValues, use the +methods that you would use to edit a standard hash table. -The default value can be an object or a script block. If the value is a script block, Windows PowerShell evaluates the script block and uses the result as the parameter value. When the specified parameter takes a script block value, enclose the script block value in a second set of braces, such as: +The \ must be the name of a cmdlet or the name of an advanced +function that uses the CmdletBinding attribute. You cannot use +$PSDefaultParameterValues to specify default values for scripts or simple +functions. +The default value can be an object or a script block. If the value is a script +block, PowerShell evaluates the script block and uses the result as the +parameter value. When the specified parameter takes a script block value, +enclose the script block value in a second set of braces, such as: -``` +```powershell $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } ``` +For information about hash tables, see +[about_Hash_Tables](about_Hash_Tables.md). For information about script +blocks, see [about_Script_Blocks](about_Script_Blocks.md). For information +about preference variables, see +[about_Preference_Variables](about_Preference_Variables.md). -For information about hash tables, see about_Hash_Tables. For information about script blocks, see about_Script_Blocks. For information about preference variables, see about_Preference_Variables. - +## EXAMPLES -### EXAMPLES -The following command sets a custom default value for the SmtpServer parameter of the Send-MailMessage cmdlet. +The following command sets a custom default value for the SmtpServer parameter +of the Send-MailMessage cmdlet. - -``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"} +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" +} ``` +To set default values for multiple parameters, use a semi-colon (;) to +separate each Name\=Value pair. The following command adds a custom default +value for the LogName parameter of the `Get-WinEvent` cmdlet. -To set default values for multiple parameters, use a semi-colon (;) to separate each Name\=Value pair. The following command adds a custom default value for the LogName parameter of the Get-WinEvent cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5"; + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" +} ``` -$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"} -``` - -You can use wildcard characters in the name of the cmdlet and parameter. The following command sets the Verbose common parameter to $true in all commands. Use $true and $false to set values for switch parameters, such as Verbose. +You can use wildcard characters in the name of the cmdlet and parameter. The +following command sets the Verbose common parameter to \$true in all commands. +Use \$true and \$false to set values for switch parameters, such as +**Verbose**. - -``` +```powershell $PSDefaultParameterValues = @{"*:Verbose"=$true} ``` +If a parameter takes multiple values (an array), you can set multiple values +as the default value. The following command sets the default value of the +**ComputerName** parameter of the Invoke-Command cmdlet to "Server01" and +"Server02". -If a parameter takes multiple values (an array), you can set multiple values as the default value. The following command sets the default value of the ComputerName parameter of the Invoke-Command cmdlet to "Server01" and "Server02". - - -``` -$PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"} -``` - - -You can use a script block to specify different default values for a parameter under different conditions. Windows PowerShell evaluates the script block and uses the result as the default parameter value. - -The following command sets the default value of the Autosize parameter of the Format-Table cmdlet to $true when the host program is the Windows PowerShell console. - - -``` -$PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}}} -``` - - -If a parameter takes a script block value, enclose the script block in an extra set of braces. When Windows PowerShell evaluates the outer script block, the result is the inner script block, which is set as the default parameter value. - -The following command sets the default value of the ScriptBlock parameter of Invoke-Command. Because the script block is enclosed in a second set of braces, the enclosed script block is passed to the Invoke-Command cmdlet. - - +```powershell +$PSDefaultParameterValues = @{ + "Invoke-Command:ComputerName"="Server01","Server02" +} ``` -$PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}} -``` - - - -### HOW TO SET $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. - -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues +You can use a script block to specify different default values for a parameter +under different conditions. PowerShell evaluates the script block and uses the +result as the default parameter value. -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. +The following command sets the default value of the Autosize parameter of the +Format-Table cmdlet to \$true when the host program is the PowerShell console. - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +$PSDefaultParameterValues=@{ + "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$true}} +} ``` +If a parameter takes a script block value, enclose the script block in an +extra set of braces. When PowerShell evaluates the outer script block, the +result is the inner script block, which is set as the default parameter value. +The following command sets the default value of the ScriptBlock parameter of +`Invoke-Command`. Because the script block is enclosed in a second set of +braces, the enclosed script block is passed to the `Invoke-Command` cmdlet. -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational -Get*:Verbose True +```powershell +$PSDefaultParameterValues=@{ + "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} +} ``` +### HOW TO SET \$PSDefaultParameterValues -To get the value of a key, use the following command syntax: +\$PSDefaultParameterValues is a preference variable, so it exists only in the +session in which it is set. It has no default value. +To set \$PSDefaultParameterValues, type the variable name and one or more +key-value pairs at the command line. -``` -$PSDefaultParameterValues[""] -``` +If you type another \$PSDefaultParameterValues command, its value replaces the +original value. The original is not retained. +To save \$PSDefaultParameterValues for future sessions, add a +\$PSDefaultParameterValues command to your PowerShell profile. For more +information, see [about_Profiles](about_Profiles.md). -For example: +### HOW TO GET \$PSDefaultParameterValues +To get the value of \$PSDefaultParameterValues, at the command prompt, type: +```powershell +$PSDefaultParameterValues ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] -Server01AB234x5 -``` - - - -### HOW TO ADD VALUES TO $PSDefaultParameterValues -$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it is set. It has no default value. - -To set $PSDefaultParameterValues, type the variable name and one or more key-value pairs at the command line. - -If you type another $PSDefaultParameterValues command, its value replaces the original value. The original is not retained. - -To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your Windows PowerShell profile. For more information, see about_Profiles. +For example, the first command sets the value of \$PSDefaultParameterValues. +The second command gets the value of \$PSDefaultParameterValues. -### HOW TO GET $PSDefaultParameterValues -To get the value of $PSDefaultParameterValues, at the command prompt, type: $PSDefaultParameterValues - -For example, the first command sets the value of $PSDefaultParameterValues. The second command gets the value of $PSDefaultParameterValues. - - -``` -PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"; - "Get-*:Verbose"=$true} +```powershell +PS C:\> $PSDefaultParameterValues = @{ + "Send-MailMessage:SmtpServer"="Server01AB234x5" + "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + "Get-*:Verbose"=$true +} ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To get the value of a \ key, use the following +command syntax: -To get the value of a key, use the following command syntax: - - -``` +```powershell $PSDefaultParameterValues[""] ``` - For example: - -``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] Server01AB234x5 ``` +### HOW TO ADD VALUES TO PSDefaultParameterValues +To add or remove values from \$PSDefaultParameterValues, use the methods that +you would use for a standard hash table. -### HOW TO ADD VALUES TO $PSDefaultParameterValues -To add or remove values from $PSDefaultParameterValues, use the methods that you would use for a standard hash table. - -For example, to add a value to $PSDefaultParameterValues without affecting the existing values, use the Add method of hash tables. +For example, to add a value to \$PSDefaultParameterValues without affecting the +existing values, use the Add method of hash tables. The syntax of the Add method is as follows: - ``` .Add(Key, Value) ``` +where the Key is ":" and the value is the parameter +value. -where the Key is ":" and the value is the parameter value. - -Use the following command format to call the Add method on $PSDefaultParameterValues. Be sure to use a comma (,) to separate the key from the value, instead of the equal sign (\=). - +Use the following command format to call the Add method on +\$PSDefaultParameterValues. Be sure to use a comma (,) to separate the key +from the value, instead of the equal sign (\=). +```powershell +$PSDefaultParameterValues.Add( + ":", "" +) ``` -$PSDefaultParameterValues.Add(":", "") -``` - -For example, the following command adds "PowerShell" as the default value of the Name parameter of the Get-Process cmdlet. +For example, the following command adds "PowerShell" as the default value of +the Name parameter of the Get-Process cmdlet. - -``` +```powershell $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO REMOVE VALUES FROM \$PSDefaultParameterValues - -### HOW TO REMOVE VALUES FROM $PSDefaultParameterValues -To remove a value from $PSDefaultParameterValues, use the Remove method of hash tables. +To remove a value from \$PSDefaultParameterValues, use the Remove method of +hash tables. The syntax of the Remove method is as follows: - -``` +```powershell .Remove(Key) ``` +Use the following command format to call the Remove method on +\$PSDefaultParameterValues. -Use the following command format to call the Remove method on $PSDefaultParameterValues. - - -``` +```powershell $PSDefaultParameterValues.Remove(":") ``` +For example, the following command removes the Name parameter of the +`Get-Process` cmdlet and its values. -For example, the following command removes the Name parameter of the Get-Process cmdlet and its values. - - -``` +```powershell $PSDefaultParameterValues.Remove("Get-Process:Name") ``` - The following example shows the effect of this command. +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Get-Process:Name PowerShell -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Get-Process:Name PowerShell +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - -``` +```powershell PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name") ``` +```powershell +PS C:\> $PSDefaultParameterValues - -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO CHANGE VALUES IN \$PSDefaultParameterValues +To change a value in $PSDefaultParameterValues, use the following command +format. -### HOW TO CHANGE VALUES IN $PSDefaultParameterValues -To change a value in $PSDefaultParameterValues, use the following command format. - - -``` +```powershell $PSDefaultParameterValues["CmdletName:ParameterName"]="" ``` - The following example shows the effect of this command. +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server01AB234x5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server01AB234x5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` - - +```powershell +$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" ``` -PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5" -``` - +```powershell +$PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +### HOW TO DISABLE AND RE-ENABLE \$PSDefaultParameterValues +You can temporarily disable and then re-enable \$PSDefaultParameterValues. This +is very useful if you're running scripts that might assume different default +parameter values. -### HOW TO DISABLE AND RE-ENABLE $PSDefaultParameterValues -You can temporarily disable and then re-enable $PSDefaultParameterValues. This is very useful if you're running scripts that might assume different default parameter values. - -To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of $True. +To disable $PSDefaultParameterValues, add a key of "Disabled" with a value of +\$True. For example, - -``` +```powershell $PSDefaultParameterValues.Add("Disabled", $true) ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$true ``` +The other values in \$PSDefaultParameterValues are preserved, but not +effective. -The other values in $PSDefaultParameterValues are preserved, but not effective. - +```powershell +PS C:\> $PSDefaultParameterValues -``` -PS C:\> $PSDefaultParameterValues - -Name Value ----- ----- -Disabled True -Send-MailMessage:SmtpServer Server0000cabx5 -Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational +Name Value +---- ----- +Disabled True +Send-MailMessage:SmtpServer Server0000cabx5 +Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational Get*:Verbose True ``` +To re-enable \$PSDefaultParameterValues, remove the Disabled key or change the +value of the Disabled key to \$False. -To re-enable $PSDefaultParameterValues, remove the Disabled key or change the value of the Disabled key to $False. - - -``` +```powershell $PSDefaultParameterValues.Remove("Disabled") ``` - - or - - -``` +```powershell $PSDefaultParameterValues[Disabled]=$false ``` - -The previous value of $PSDefaultParameterValues is effective again. - +The previous value of \$PSDefaultParameterValues is effective again. ## KEYWORDS + about_PSDefaultParameterValues about_Parameters_DefaultValues about_DefaultValues - ## SEE ALSO [about_Hash_Tables](about_Hash_Tables.md) @@ -459,4 +419,3 @@ about_DefaultValues [about_Profiles](about_Profiles.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 886b4ed1dfc9..906dc159fb8a 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-05 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -248,7 +248,7 @@ debug message is not displayed and processing continues. The final command uses the Debug parameter to override the preference for a single command. ```powershell -PS> $debugpreference # Get the current value of \$DebugPreference +PS> $debugpreference # Get the current value of $DebugPreference SilentlyContinue PS> write-debug "Hello, World" @@ -301,7 +301,7 @@ uses the Debug parameter with a value of \$false to suppress the message for a single command. ```powershell -PS> \$debugpreference = "Inquire" +PS> $debugpreference = "Inquire" PS> write-debug "Hello, World" DEBUG: Hello, World @@ -375,7 +375,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value of the preference. -PS> \$ErrorActionPreference = "SilentlyContinue" +PS> $ErrorActionPreference = "SilentlyContinue" PS> # Generate an error message. PS> write-error "Hello, World" @@ -393,14 +393,14 @@ a non-existent file, nofile.txt. The example also uses the ErrorAction common parameter to override the preference. ```powershell -PS> \$erroractionpreference +PS> $erroractionpreference SilentlyContinue # Display the value of the preference. PS> get-childitem -path nofile.txt PS> # Error message is suppressed. PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> get-childitem -path nofile.txt Get-ChildItem : Cannot find path 'C:\nofile.txt' because it does not exist. @@ -412,7 +412,7 @@ PS> get-childitem -path nofile.txt -erroraction SilentlyContinue PS> # Error message is suppressed. PS> # Change the value to Inquire. -PS> \$ErrorActionPreference = "Inquire" +PS> $ErrorActionPreference = "Inquire" PS> get-childitem -path nofile.txt Confirm @@ -425,7 +425,7 @@ At line:1 char:4 + get-childitem <<<< nofile.txt PS> # Change the value to Continue. -PS> \$ErrorActionPreference = "Continue" +PS> $ErrorActionPreference = "Continue" PS> Get-Childitem nofile.txt -erroraction "Inquire" PS> # Use the ErrorAction parameter to override the preference value. @@ -462,7 +462,7 @@ NormalView. In this case, the Get-ChildItem command is used to find a non-existent file. ```powershell -PS> \$ErrorView # Verify the value. +PS> $ErrorView # Verify the value. NormalView PS> get-childitem nofile.txt # Find a non-existent file. @@ -475,7 +475,7 @@ This example shows how the same error appears when the value of \$ErrorView is CategoryView. ```powershell -PS> \$ErrorView = "CategoryView" # Change the value to +PS> $ErrorView = "CategoryView" # Change the value to CategoryView PS> get-childitem nofile.txt @@ -493,7 +493,7 @@ error in the error array (element 0) and formats all of the properties of the error object in a list. ```powershell -PS> \$error[0] | format-list -property * -force +PS> $error[0] | format-list -property * -force Exception : System.Management.Automation.ItemNotFoundException: Cannot find path 'C:\nofile.txt' because it does not exist. @@ -546,10 +546,10 @@ In the resulting display, the list in the Group column is now limited by the line length. In the final command in the example, use the Wrap parameter of Format-Table to display all of the processes in each Status group. -PS> \$formatenumerationlimit # Find the current value +```powershell +PS> $formatenumerationlimit # Find the current value 4 -```powershell PS> # List all services grouped by status PS> get-service | group-object -property status @@ -560,7 +560,7 @@ Count Name Group PS> # The list is truncated after 4 items. PS> # Increase the limit to 1000. -PS> \$formatenumerationlimit = 1000 +PS> $formatenumerationlimit = 1000 PS> get-service | group-object -property status Count Name Group @@ -650,20 +650,20 @@ The Log*Event preference variables are as follows: To enable a Log*Event, type the variable with a value of \$true, for example: ```powershell -\$LogCommandLifeCycleEvent +$LogCommandLifeCycleEvent ``` - or - ```powershell -\$LogCommandLifeCycleEvent = \$true +$LogCommandLifeCycleEvent = $true ``` To disable an event type, type the variable with a value of \$false, for example: ```powershell -\$LogCommandLifeCycleEvent = \$false +$LogCommandLifeCycleEvent = $false ``` The events that you enable are effective only for the current PowerShell @@ -719,26 +719,26 @@ To count the errors on your system, use the Count property of the \$Error array. Type: ```powershell -\$Error.count +$Error.count ``` To display a specific error, use array notation to display the error. For example, to see the most recent error, type: ```powershell -\$Error[0] +$Error[0] ``` To display the oldest retained error, type: ```powershell -\$Error[(\$Error.Count -1] +$Error[($Error.Count -1] ``` To display the properties of the ErrorRecord object, type: ```powershell -\$Error[0] | format-list -property * -force +$Error[0] | format-list -property * -force ``` In this command, the Force parameter overrides the special formatting of @@ -748,11 +748,11 @@ To delete all errors from the error history, use the Clear method of the error array. ```powershell -PS> \$Error.count +PS> $Error.count 17 -PS> \$Error.clear() +PS> $Error.clear() PS> -PS> \$Error.count +PS> $Error.count 0 ``` @@ -844,9 +844,9 @@ is converted to a string. In this case, an array of integers is stored in a variable and then the variable is cast as a string. ```powershell -PS> \$array = 1,2,3 # Store an array of integers. +PS> $array = 1,2,3 # Store an array of integers. -PS> [string]\$array # Cast the array to a string. +PS> [string]$array # Cast the array to a string. 1 2 3 # Spaces separate the elements ``` @@ -854,9 +854,9 @@ To change the separator, add the \$OFS variable by assigning a value to it. To work correctly, the variable must be named \$OFS. ```powershell -PS> \$OFS = "+" # Create \$OFS and assign a "+" +PS> $OFS = "+" # Create $OFS and assign a "+" -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1+2+3 # Plus signs separate the elements ``` @@ -865,10 +865,10 @@ To restore the default behavior, you can assign a space (" ") to the value of verifies that the separator is a space. ```powershell -PS> Remove-Variable OFS # Delete \$OFS +PS> Remove-Variable OFS # Delete $OFS PS> -PS> [string]\$array # Repeat the command +PS> [string]$array # Repeat the command 1 2 3 # Spaces separate the elements ``` @@ -897,7 +897,7 @@ The first command finds the value of \$OutputEncoding. Because the value is an encoding object, display only its EncodingName property. ```powershell -PS> \$OutputEncoding.EncodingName # Find the current value US-ASCII +PS> $OutputEncoding.EncodingName # Find the current value US-ASCII ``` In this example, a FINDSTR command is used to search for two Chinese @@ -918,9 +918,9 @@ locale selected for Windows. Because OutputEncoding is a static property of the console, use double-colons (::) in the command. ```powershell -PS> \$OutputEncoding = [console]::outputencoding +PS> $OutputEncoding = [console]::outputencoding PS> # Set the value equal to the OutputEncoding property of the console. -PS> \$OutputEncoding.EncodingName +PS> $OutputEncoding.EncodingName OEM United States ``` As a result of this change, the FINDSTR command finds the characters. @@ -1100,7 +1100,7 @@ values you prefer. Save the output in a variable called \$PSSessionOption. For example, ```powershell -\$PSSessionOption = New-PSSessionOption -NoCompression +$PSSessionOption = New-PSSessionOption -NoCompression ``` To use the \$PSSessionOption preference variable in every PowerShell session, @@ -1202,7 +1202,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$VerbosePreference = "Inquire" +PS> $VerbosePreference = "Inquire" PS> Write-Verbose "Verbose message test." VERBOSE: Verbose message test. Confirm @@ -1249,7 +1249,7 @@ value. This example shows the effect of the Continue value, which is the default. ```powershell -PS> \$WarningPreference # Find the current value. +PS> $WarningPreference # Find the current value. Continue PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1263,7 +1263,7 @@ This example shows the effect of the SilentlyContinue value. ```powershell PS> # Change the value to SilentlyContinue. -PS> \$WarningPreference = "SilentlyContinue" +PS> $WarningPreference = "SilentlyContinue" PS> Write-Warning "This action can delete data." PS> # Write a warning message. @@ -1280,7 +1280,7 @@ This example shows the effect of the Inquire value. ```powershell PS> # Change the value to Inquire. -PS> \$WarningPreference = "Inquire" +PS> $WarningPreference = "Inquire" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1299,7 +1299,7 @@ This example shows the effect of the Stop value. ```powershell PS> # Change the value to Stop. -PS> \$WarningPreference = "Stop" +PS> $WarningPreference = "Stop" PS> Write-Warning "This action can delete data." WARNING: This action can delete data. @@ -1360,7 +1360,7 @@ This example shows the effect of the 0 (not enabled) value, which is the default. ```powershell -PS> \$whatifpreference +PS> $whatifpreference 0 # Check the current value. PS> # Verify that the file exists. @@ -1400,8 +1400,8 @@ Remove-Item to delete a cmdlet, Remove-Item displays the path to the file that it would delete, but it does not delete the file. ```powershell -PS> \$whatifpreference = 1 -PS> \$whatifpreference +PS> $whatifpreference = 1 +PS> $whatifpreference 1 # Change the value. PS> # Try to delete a file. @@ -1417,8 +1417,8 @@ This example shows how to delete a file when the value of \$WhatIfPreference is 1. It uses the WhatIf parameter with a value of \$false. ```powershell -PS> # Use the WhatIf parameter with \$false. -PS> remove-item test.txt -whatif:\$false +PS> # Use the WhatIf parameter with $false. +PS> remove-item test.txt -whatif:$false ``` This example demonstrates that some cmdlets support WhatIf behavior and others @@ -1430,7 +1430,7 @@ a value of \$false. ```powershell PS> # Change the value to 1. -PS> \$whatifpreference = 1 +PS> $whatifpreference = 1 PS> get-process winword A Get-Process command completes. @@ -1443,8 +1443,8 @@ PS> # A Stop-Process command uses WhatIf. PS> stop-process -name winword What if: Performing operation "Stop-Process" on Target "WINWORD (2312)". -PS> stop-process -name winword -whatif:\$false -PS> # WhatIf:\$false overrides the preference. +PS> stop-process -name winword -whatif:$false +PS> # WhatIf:$false overrides the preference. PS> # Verify that the process is stopped. PS> get-process winword diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Profiles.md b/reference/6/Microsoft.PowerShell.Core/About/about_Profiles.md index b7eabd81d0ce..eea0dd9f0d50 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Profiles.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Profiles.md @@ -1,104 +1,99 @@ --- -ms.date: 2017-06-25 +ms.date: 2017-11-30 schema: 2.0.0 keywords: powershell,cmdlet title: about_Profiles --- # About Profiles -## about_Profiles +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Describes how to create and use a PowerShell profile. -Describes how to create and use a Windows PowerShell profile. +## LONG DESCRIPTION -# LONG DESCRIPTION +You can create a PowerShell profile to customize your environment and to add +session-specific elements to every PowerShell session that you start. -You can create a Windows PowerShell profile to customize your environment -and to add session-specific elements to every Windows PowerShell session -that you start. +A PowerShell profile is a script that runs when PowerShell starts. You can use +the profile as a logon script to customize the environment. You can add +commands, aliases, functions, variables, snap-ins, modules, and PowerShell +drives. You can also add other session-specific elements to your profile so +they are available in every session without having to import or re-create +them. -A Windows PowerShell profile is a script that runs when Windows PowerShell -starts. You can use the profile as a logon script to customize the -environment. You can add commands, aliases, functions, variables, snap-ins, -modules, and Windows PowerShell drives. You can also add other -session-specific elements to your profile so they are available in every -session without having to import or re-create them. +PowerShell supports several profiles for users and host programs. However, it +does not create the profiles for you. This topic describes the profiles, and +it describes how to create and maintain profiles on your computer. -Windows PowerShell supports several profiles for users and host programs. -However, it does not create the profiles for you. This topic describes the -profiles, and it describes how to create and maintain profiles on your -computer. +It explains how to use the **NoProfile** parameter of the PowerShell console +(PowerShell.exe) to start PowerShell without any profiles. And, it explains +the effect of the PowerShell execution policy on profiles. -It explains how to use the **NoProfile** parameter of the Windows PowerShell -console (PowerShell.exe) to start Windows PowerShell without any profiles. -And, it explains the effect of the Windows PowerShell execution policy on -profiles. +## THE PROFILE FILES -# THE PROFILE FILES +PowerShell supports several profile files. Also, PowerShell host programs can +support their own host-specific profiles. - -Windows PowerShell supports several profile files. Also, Windows PowerShell -host programs can support their own host-specific profiles. - -For example, the Windows PowerShell console supports the following basic +For example, the PowerShell console supports the following basic profile files. The profiles are listed in precedence order. The first profile has the highest precedence. -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Profile.ps1 | -| Current User, All Hosts | $Home\\[My ]Documents\Profile.ps1 | -| All Users, Current Host | $PsHome\Microsoft.PowerShell_profile.ps1 | -| All Users, All Hosts | $PsHome\Profile.ps1 | +|Description | Path | +|--------------------------|------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Profile.ps1 | +|Current User, All Hosts |$Home\\[My ]Documents\\Profile.ps1 | +|All Users, Current Host |$PsHome\Microsoft.PowerShell_profile.ps1 | +|All Users, All Hosts |$PsHome\Profile.ps1 | The profile paths include the following variables: - The `$PsHome` variable, which stores the installation directory for -Windows PowerShell +PowerShell - The `$Home` variable, which stores the current user's home directory -In addition, other programs that host Windows PowerShell can support their -own profiles. For example, Windows PowerShell Integrated Scripting -Environment (ISE) supports the following host-specific profiles. - -| Description | Path | -| ------------- | ------------- | -| Current user, Current Host | $Home\\[My ]Documents\WindowsPowerShell\Microsoft.PowerShellISE_profile.ps1 | -| All users, Current Host | $PsHome\Microsoft.PowerShellISE_profile.ps1 | +In addition, other programs that host PowerShell can support their own +profiles. For example, PowerShell Integrated Scripting Environment (ISE) +supports the following host-specific profiles. -In Windows PowerShell Help, the "CurrentUser, Current Host" profile is the profile most -often referred to as "your Windows PowerShell profile". +|Description | Path | +|--------------------------|-------------------------------------------| +|Current user, Current Host|$Home\\[My ]Documents\\WindowsPowerShell | +| | \\Microsoft.PowerShellISE_profile.ps1 | +|All users, Current Host |$PsHome\Microsoft.PowerShellISE_profile.ps1| -# THE $PROFILE VARIABLE +In PowerShell Help, the "CurrentUser, Current Host" profile is the profile +most often referred to as "your PowerShell profile". +## THE $PROFILE VARIABLE -The `$Profile` automatic variable stores the paths to the Windows PowerShell -profiles that are available in the current session. +The `$Profile` automatic variable stores the paths to the PowerShell profiles +that are available in the current session. To view a profile path, display the value of the `$Profile` variable. You can also use the `$Profile` variable in a command to represent a path. -The `$Profile` variable stores the path to the "Current User, -Current Host" profile. The other profiles are saved in note properties of -the `$Profile` variable. +The `$Profile` variable stores the path to the "Current User, Current Host" +profile. The other profiles are saved in note properties of the `$Profile` +variable. For example, the `$Profile` variable has the following values in the Windows PowerShell console. -| Name | Description | -| ------------- | ------------- | -| $Profile | Current User, Current Host | -| $Profile.CurrentUserCurrentHost | Current User, Current Host | -| $Profile.CurrentUserAllHosts | Current User, All Hosts | -| $Profile.AllUsersCurrentHost | All Users, Current Host | -| $Profile.AllUsersAllHosts | All Users, All Hosts | +|Name |Description | +|--------------------------------|---------------------------| +|$Profile |Current User, Current Host | +|$Profile.CurrentUserCurrentHost |Current User, Current Host | +|$Profile.CurrentUserAllHosts |Current User, All Hosts | +|$Profile.AllUsersCurrentHost |All Users, Current Host | +|$Profile.AllUsersAllHosts |All Users, All Hosts | -Because the values of the `$Profile` variable change for each user and in -each host application, ensure that you display the values of the -profile variables in each Windows PowerShell host application that you use. +Because the values of the `$Profile` variable change for each user and in each +host application, ensure that you display the values of the profile variables +in each PowerShell host application that you use. To see the current values of the `$Profile` variable, type: @@ -107,24 +102,22 @@ $profile | Get-Member -Type NoteProperty ``` You can use the `$Profile` variable in many commands. For example, the -following command opens the "Current User, Current Host" profile in -Notepad: +following command opens the "Current User, Current Host" profile in Notepad: ```powershell notepad $profile ``` -The following command determines whether an "All Users, All Hosts" profile -has been created on the local computer: +The following command determines whether an "All Users, All Hosts" profile has +been created on the local computer: ```powershell Test-Path -Path $profile.AllUsersAllHosts ``` -# HOW TO CREATE A PROFILE +## HOW TO CREATE A PROFILE - -To create a Windows PowerShell profile, use the following command format: +To create a PowerShell profile, use the following command format: ```powershell if (!(Test-Path -Path )) @@ -132,7 +125,7 @@ if (!(Test-Path -Path )) ``` For example, to create a profile for the current user in the current -Windows PowerShell host application, use the following command: +PowerShell host application, use the following command: ```powershell if (!(Test-Path -Path $profile)) @@ -140,21 +133,18 @@ if (!(Test-Path -Path $profile)) ``` In this command, the If statement prevents you from overwriting an existing -profile. Replace the value of the placeholder with the path +profile. Replace the value of the \ placeholder with the path to the profile file that you want to create. ->Note: To create "All Users" profiles in Windows Vista and later versions ->of Windows, start Windows PowerShell with the "Run as administrator" ->option. - -# HOW TO EDIT A PROFILE +> Note: To create "All Users" profiles in Windows Vista and later versions of +> Windows, start PowerShell with the "Run as administrator" >option. +## HOW TO EDIT A PROFILE -You can open any Windows PowerShell profile in a text editor, such as -Notepad. +You can open any PowerShell profile in a text editor, such as Notepad. -To open the profile of the current user in the current Windows PowerShell -host application in Notepad, type: +To open the profile of the current user in the current PowerShell host +application in Notepad, type: ```powershell notepad $profile @@ -167,106 +157,99 @@ profile for all the users of all the host applications, type: notepad $profile.AllUsersAllHosts ``` -To apply the changes, save the profile file, and then restart Windows -PowerShell. +To apply the changes, save the profile file, and then restart PowerShell. -# HOW TO CHOOSE A PROFILE +## HOW TO CHOOSE A PROFILE +If you use multiple host applications, put the items that you use in all the +host applications into your `$Profile.CurrentUserAllHosts` profile. Put items +that are specific to a host application, such as a command that sets the +background color for a host application, in a profile that is specific to that +host application. -If you use multiple host applications, put the items that you use in all -the host applications into your `$Profile.CurrentUserAllHosts` profile. -Put items that are specific to a host application, such as a command that -sets the background color for a host application, in a profile that is -specific to that host application. - -If you are an administrator who is customizing Windows -PowerShell for many users, follow these guidelines: +If you are an administrator who is customizing Windows PowerShell for many +users, follow these guidelines: - Store the common items in the `$profile.AllUsersAllHosts` profile - - Store items that are specific to a host application in -`$profile.AllUsersCurrentHost` profiles that are specific to the host -application - + `$profile.AllUsersCurrentHost` profiles that are specific to the host + application - Store items for particular users in the user-specific profiles Be sure to check the host application documentation for any special -implementation of Windows PowerShell profiles. - -# HOW TO USE A PROFILE +implementation of PowerShell profiles. +## HOW TO USE A PROFILE -Many of the items that you create in Windows PowerShell and most commands -that you run affect only the current session. When you end the session, -the items are deleted. +Many of the items that you create in PowerShell and most commands that you run +affect only the current session. When you end the session, the items are +deleted. The session-specific commands and items include variables, preference -variables, aliases, functions, commands (except for [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), -and Windows PowerShell snap-ins that you add to the session. +variables, aliases, functions, commands (except for +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)), +and PowerShell modules that you add to the session. -To save these items and make them available in all future sessions, add -them to a Windows PowerShell profile. +To save these items and make them available in all future sessions, add them +to a PowerShell profile. -Another common use for profiles is to save frequently-used functions, -aliases, and variables. When you save the items in a profile, you can -use them in any applicable session without re-creating them. +Another common use for profiles is to save frequently-used functions, aliases, +and variables. When you save the items in a profile, you can use them in any +applicable session without re-creating them. -# HOW TO START A PROFILE +## HOW TO START A PROFILE - -When you open the profile file, it is blank. However, you can fill it with -the variables, aliases, and commands that you use frequently. +When you open the profile file, it is blank. However, you can fill it with the +variables, aliases, and commands that you use frequently. Here are a few suggestions to get you started. -- Add commands that make it easy to open your profile. This is especially -useful if you use a profile other than the "Current User, Current Host" -profile. For example, add the following command: +### Add commands that make it easy to open your profile + +This is especially useful if you use a profile other than the "Current User, +Current Host" profile. For example, add the following command: ```powershell function Pro {notepad $profile.CurrentUserAllHosts} ``` -- Add a function that opens Windows PowerShell Help in a compiled HTML -Help file (.chm) +### Add a function that opens PowerShell Help in a compiled HTML + Help file (.chm) ```powershell -function Get-CHM -{ -Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" +function Get-CHM { + Invoke-Item -Path "$env:windir\help\mui\0409\WindowsPowerShellHelp.chm" } ``` -This function opens the English version of the .chm file. However, you -can replace the language code (0409) to open other versions of the .chm -file. +This function opens the English version of the .chm file. However, you can +replace the language code (0409) to open other versions of the .chm file. -- Add a function that lists the aliases for any cmdlet +### Add a function that lists the aliases for any cmdlet ```powershell -function Get-CmdletAlias ($cmdletname) -{ -Get-Alias | Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | Format-Table -Property Definition, Name -AutoSize +function Get-CmdletAlias ($cmdletname) { + Get-Alias | + Where-Object -FilterScript {$_.Definition -like "$cmdletname"} | + Format-Table -Property Definition, Name -AutoSize } ``` -- Customize your console +### Customize your console ```powershell -function Color-Console -{ -$Host.ui.rawui.backgroundcolor = "white" -$Host.ui.rawui.foregroundcolor = "black" -$hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime -$hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" -$Host.UI.RawUI.WindowTitle = "Windows PowerShell $hostversion ($hosttime)" -Clear-Host +function Color-Console { + $Host.ui.rawui.backgroundcolor = "white" + $Host.ui.rawui.foregroundcolor = "black" + $hosttime = (Get-ChildItem -Path $pshome\PowerShell.exe).CreationTime + $hostversion="$($Host.Version.Major)`.$($Host.Version.Minor)" + $Host.UI.RawUI.WindowTitle = "PowerShell $hostversion ($hosttime)" + Clear-Host } Color-Console ``` -- Add a customized Windows PowerShell prompt that includes the computer -name and the current path +### Add a customized PowerShell prompt ```powershell function Prompt @@ -275,18 +258,16 @@ $env:COMPUTERNAME + "\" + (Get-Location) + "> " } ``` -For more information about the Windows PowerShell prompt, see +For more information about the PowerShell prompt, see [about_Prompts](about_Prompts.md). -# THE NOPROFILE PARAMETER +## THE NOPROFILE PARAMETER +To start PowerShell without profiles, use the **NoProfile** parameter of +PowerShell.exe, the program that starts PowerShell. -To start Windows PowerShell without profiles, use the **NoProfile** parameter -of PowerShell.exe, the program that starts Windows PowerShell. - -To begin, open a program that can start Windows PowerShell, such as Cmd.exe -or Windows PowerShell itself. You can also use the Run dialog box in -Windows. +To begin, open a program that can start PowerShell, such as Cmd.exe or +PowerShell itself. You can also use the Run dialog box in Windows. Type: @@ -294,56 +275,58 @@ Type: PowerShell -NoProfile ``` -For a complete list of the parameters of PowerShell.exe, -type: +For a complete list of the parameters of PowerShell.exe, type: ``` PowerShell -? ``` -# PROFILES AND EXECUTION POLICY - +## PROFILES AND EXECUTION POLICY -The Windows PowerShell execution policy determines, in part, whether you -can run scripts and load configuration files, including the profiles. The -"Restricted" execution policy is the default. It prevents all scripts from -running, including the profiles. If you use the "Restricted" policy, the -profile does not run, and its contents are not applied. +The PowerShell execution policy determines, in part, whether you can run +scripts and load configuration files, including the profiles. The "Restricted" +execution policy is the default. It prevents all scripts from running, +including the profiles. If you use the "Restricted" policy, the profile does +not run, and its contents are not applied. A `Set-ExecutionPolicy` command sets and changes your execution policy. It is -one of the few commands that applies in all Windows PowerShell sessions -because the value is saved in the registry. You do not have to set it when -you open the console, and you do not have to store a `Set-ExecutionPolicy` -command in your profile. +one of the few commands that applies in all PowerShell sessions because the +value is saved in the registry. You do not have to set it when you open the +console, and you do not have to store a `Set-ExecutionPolicy` command in your +profile. -# PROFILES AND REMOTE SESSIONS +## PROFILES AND REMOTE SESSIONS +PowerShell profiles are not run automatically in remote sessions, so the +commands that the profiles add are not present in the remote session. In +addition, the `$Profile` automatic variable is not populated in remote +sessions. -Windows PowerShell profiles are not run automatically in remote sessions, -so the commands that the profiles add are not present in the remote session. -In addition, the `$Profile` automatic variable is not populated in remote sessions. +To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) +cmdlet. -To run a profile in a session, use the [Invoke-Command](../Invoke-Command.md) cmdlet. - -For example, the following command runs the "Current user, Current Host" profile from -the local computer in the session in $s. +For example, the following command runs the "Current user, Current Host" +profile from the local computer in the session in $s. ```powershell Invoke-Command -Session $s -FilePath $profile ``` -The following command runs the "Current user, Current Host" profile from the remote -computer in the session in $s. Because the `$Profile` variable is not populated, -the command uses the explicit path to the profile. +The following command runs the "Current user, Current Host" profile from the +remote computer in the session in $s. Because the `$Profile` variable is not +populated, the command uses the explicit path to the profile. ```powershell -Invoke-Command -SessionName $s -ScriptBlock {Invoke-Command -FilePath "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +Invoke-Command -SessionName $s -ScriptBlock { +$path = "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +Invoke-Command -FilePath $path +} ``` After running this command, the commands that the profile adds to the session are available in $s. -# SEE ALSO +## SEE ALSO [about_Automatic_Variables](about_Automatic_Variables.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Prompts.md b/reference/6/Microsoft.PowerShell.Core/About/about_Prompts.md index bc2e78b01d08..6f1820bea646 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Prompts.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Prompts.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,308 +7,284 @@ title: about_Prompts --- # About Prompts -## about_Prompts - ## SHORT DESCRIPTION -Describes the Prompt function and demonstrates how to create a custom Prompt function. +Describes the Prompt function and demonstrates how to create a custom Prompt +function. ## LONG DESCRIPTION -The Windows PowerShell command prompt indicates that Windows PowerShell is ready to run a command: +The PowerShell command prompt indicates that PowerShell is ready to run a +command: ``` PS C:\> ``` +The PowerShell prompt is determined by the built-in Prompt function. You can +customize the prompt by creating your own Prompt function and saving it in +your PowerShell profile. -The Windows PowerShell prompt is determined by the built-in Prompt function. You can customize the prompt by creating your own Prompt function and saving it in your Windows PowerShell profile. - +## ABOUT THE PROMPT FUNCTION -### ABOUT THE PROMPT FUNCTION -The Prompt function determines the appearance of the Windows PowerShell prompt. Windows PowerShell comes with a built-in Prompt function, but you can override it by defining your own Prompt function. +The Prompt function determines the appearance of the PowerShell prompt. +PowerShell comes with a built-in Prompt function, but you can override it by +defining your own Prompt function. The Prompt function has the following syntax: - -``` +```powershell function Prompt { } ``` +The Prompt function must return an object. As a best practice, return a string +or an object that is formatted as a string. The maximum recommended length is +80 characters. -The Prompt function must return an object. As a best practice, return a string or an object that is formatted as a string. The maximum recommended length is 80 characters. - -For example, the following prompt function returns a "Hello, World" string followed by a caret (>). +For example, the following prompt function returns a "Hello, World" string +followed by a caret (>). - -``` -PS C:\> function prompt {"Hello, World > "} +```powershell +PS C:\> function prompt {"Hello, World > "} Hello, World > ``` - - ### GETTING THE PROMPT FUNCTION -To get the Prompt function, use the Get-Command cmdlet or use the Get-Item cmdlet in the Function drive. -Functions are commands. So, you can use the Get-Command cmdlet to get functions, including the Prompt function. +To get the Prompt function, use the `Get-Command` cmdlet or use the `Get-Item` +cmdlet in the Function drive. For example: +```powershell +PS C:\> Get-Command Prompt -``` -PS C:\> Get-Command Prompt - -CommandType Name ModuleName ------------ ---- ---------- +CommandType Name ModuleName +----------- ---- ---------- Function prompt ``` - -To get the script that sets the value of the prompt, use the dot method to get the ScriptBlock property of the Prompt function. +To get the script that sets the value of the prompt, use the dot method to get +the ScriptBlock property of the Prompt function. For example: +```powershell +PS C:\> (Get-Command Prompt).ScriptBlock -``` -PS C:\> (Get-Command Prompt).ScriptBlock - -"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -# .Link -# http://go.microsoft.com/fwlink/?LinkID=225750 +"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPr +omptLevel + 1)) " +# .Link +# http://go.microsoft.com/fwlink/?LinkID=225750 # .ExternalHelp System.Management.Automation.dll-help.xml ``` +Like all functions, the Prompt function is stored in the Function: drive. To +display the script that creates the current Prompt function, type: -Like all functions, the Prompt function is stored in the Function: drive. To display the script that creates the current Prompt function, type: - - -``` +```powershell (Get-Item function:prompt).ScriptBlock ``` - ### THE DEFAULT PROMPT -The default prompt appears only when the Prompt function generates an error or does not return an object. -The default Windows PowerShell prompt is: +The default prompt appears only when the Prompt function generates an error or +does not return an object. +The default PowerShell prompt is: ``` PS> ``` +For example, the following command sets the Prompt function to $null, which is +invalid. As a result, the default prompt appears. -For example, the following command sets the Prompt function to $null, which is invalid. As a result, the default prompt appears. - - -``` -PS C:\> function prompt {$null} +```powershell +PS C:\> function prompt {$null} PS> ``` - -Because Windows PowerShell comes with a built-in prompt, you usually do not see the default prompt. - +Because PowerShell comes with a built-in prompt, you usually do not see the +default prompt. ### BUILT-IN PROMPT -Windows PowerShell includes a built-in prompt function. - -In Windows PowerShell 3.0, the built-in prompt function is: - - -``` -function prompt -{ - "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " -} -``` - -This simplified prompt starts with "PS" followed by the current location, and one ">" for each nested prompt level. +PowerShell includes a built-in prompt function. -In Windows PowerShell 2.0, the built-in prompt function is: - - -``` -function prompt -{ - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - else { '' }) + 'PS ' + $(Get-Location) ` - + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +```powershell +function prompt { + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + else { '' }) + 'PS ' + $(Get-Location) ` + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +The function uses the Test-Path cmdlet to determine whether the +\$PSDebugContext automatic variable is populated. If \$PSDebugContext is +populated, you are in debugging mode, and "[DBG]" is added to the prompt, as +follows: -The function uses the Test-Path cmdlet to determine whether the $PSDebugContext automatic variable is populated. If $PSDebugContext is populated, you are in debugging mode, and "[DBG]" is added to the prompt, as follows: - - -``` +```Output [DBG] PS C:\ps-test> ``` +If \$PSDebugContext is not populated, the function adds "PS" to the prompt. +And, the function uses the `Get-Location` cmdlet to get the current file +system directory location. Then, it adds a right angle bracket (>). -If $PSDebugContext is not populated, the function adds "PS" to the prompt. And, the function uses the Get-Location cmdlet to get the current file system directory location. Then, it adds a right angle bracket (>). - +For example: -``` -For example: - PS C:\ps-test> +```Output +PS C:\ps-test> ``` +If you are in a nested prompt, the function adds two angle brackets (>>) to +the prompt. (You are in a nested prompt if the value of the +\$NestedPromptLevel automatic variable is greater than 1.) -If you are in a nested prompt, the function adds two angle brackets (>>) to the prompt. (You are in a nested prompt if the value of the $NestedPromptLevel automatic variable is greater than 1.) +For example, when you are debugging in a nested prompt, the prompt resembles +the following prompt: -For example, when you are debugging in a nested prompt, the prompt resembles the following prompt: - - -``` +```Output [DBG] PS C:\ps-test>>> ``` - - ### CHANGES TO THE PROMPT -The Enter-PSSession cmdlet prepends the name of the remote computer to the current Prompt function. When you use the Enter-PSSession cmdlet to start a session with a remote computer, the command prompt changes to include the name of the remote computer. For example: +The Enter-PSSession cmdlet prepends the name of the remote computer to the +current Prompt function. When you use the Enter-PSSession cmdlet to start a +session with a remote computer, the command prompt changes to include the name +of the remote computer. For example: -``` -PS Hello, World> Enter-PSSession Server01 +```Output +PS Hello, World> Enter-PSSession Server01 [Server01]: PS Hello, World> ``` +Other PowerShell host applications and alternate shells might have their own +custom command prompts. -Other Windows PowerShell host applications and alternate shells might have their own custom command prompts. - -For more information about the $PSDebugContext and $NestedPromptLevel automatic variables, see about_Automatic_Variables. - +For more information about the \$PSDebugContext and $NestedPromptLevel +automatic variables, see [about_Automatic_Variables](about_Automatic_Variables.md). ### HOW TO CUSTOMIZE THE PROMPT -To customize the prompt, write a new Prompt function. The function is not protected, so you can overwrite it. -To write a prompt function, type the following: +To customize the prompt, write a new Prompt function. The function is not +protected, so you can overwrite it. +To write a prompt function, type the following: -``` +```powershell function prompt { } ``` - -Then, between the braces, enter the commands or the string that creates your prompt. +Then, between the braces, enter the commands or the string that creates your +prompt. For example, the following prompt includes your computer name: - -``` +```powershell function prompt {"PS [$env:COMPUTERNAME]> "} ``` - On the Server01 computer, the prompt resembles the following prompt: - -``` +```Output PS [Server01] > ``` - The following prompt function includes the current date and time: - -``` +```powershell function prompt {"$(get-date)> "} ``` - The prompt resembles the following prompt: - -``` +```Output 03/15/2012 17:49:47> ``` - You can also change the default Prompt function: -For example, the following modified Prompt function adds "[ADMIN]:" to the built-in Windows PowerShell prompt when Windows PowerShell is opened by using the "Run as administrator" option: - - -``` -function prompt -{ - $identity = [Security.Principal.WindowsIdentity]::GetCurrent() - $principal = [Security.Principal.WindowsPrincipal] $identity - - $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } - - elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) - { "[ADMIN]: " } - - else { '' }) + 'PS ' + $(Get-Location) + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' +For example, the following modified Prompt function adds "[ADMIN]:" to the +built-in PowerShell prompt when PowerShell is opened by using the "Run as +administrator" option: + +```powershell +function prompt { + $identity = [Security.Principal.WindowsIdentity]::GetCurrent() + $principal = [Security.Principal.WindowsPrincipal] $identity + + $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } + elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] + "Administrator")) { "[ADMIN]: " } + else { '' } + ) + 'PS ' + $(Get-Location) + + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> ' } ``` +When you start PowerShell by using the "Run as administrator" option, a prompt +that resembles the following prompt appears: -When you start Windows PowerShell by using the "Run as administrator" option, a prompt that resembles the following prompt appears: - - -``` +```Output [ADMIN]: PS C:\ps-test> ``` +The following Prompt function displays the history ID of the next command. To +view the command history, use the `Get-History` cmdlet. -The following Prompt function displays the history ID of the next command. To view the command history, use the Get-History cmdlet. - +```powershell +function prompt { + # The at sign creates an array in case only one history item exists. + $history = @(get-history) + if($history.Count -gt 0) + { + $lastItem = $history[$history.Count - 1] + $lastId = $lastItem.Id + } -``` -function prompt -{ - # The at sign creates an array in case only one history item exists. - $history = @(get-history) - if($history.Count -gt 0) - { - $lastItem = $history[$history.Count - 1] - $lastId = $lastItem.Id - } - - $nextCommand = $lastId + 1 - $currentDirectory = get-location - "PS: $nextCommand $currentDirectory >" + $nextCommand = $lastId + 1 + $currentDirectory = get-location + "PS: $nextCommand $currentDirectory >" } ``` +The following prompt uses the Write-Host and Get-Random cmdlets to create a +prompt that changes color randomly. Because `Write-Host` writes to the current +host application but does not return an object, this function includes a +Return statement. Without it, PowerShell uses the default prompt, "PS>". -The following prompt uses the Write-Host and Get-Random cmdlets to create a prompt that changes color randomly. Because Write-Host writes to the current host application but does not return an object, this function includes a Return statement. Without it, Windows PowerShell uses the default prompt, "PS>". - - -``` -function prompt -{ - $color = Get-Random -Min 1 -Max 16 - Write-Host ("PS " + $(Get-Location) +">") -NoNewLine -ForegroundColor $Color - return " " +```powershell +function prompt { + $color = Get-Random -Min 1 -Max 16 + Write-Host ("PS " + $(Get-Location) +">") -NoNewLine ` + -ForegroundColor $Color + return " " } ``` - - ### SAVING THE PROMPT FUNCTION -Like any function, the Prompt function exists only in the current session. To save the Prompt function for future sessions, add it to your Windows PowerShell profiles. For more information about profiles, see about_Profiles. +Like any function, the Prompt function exists only in the current session. To +save the Prompt function for future sessions, add it to your PowerShell +profiles. For more information about profiles, see about_Profiles. ## SEE ALSO -Get-Location +[Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) -Enter-PSSession +[Enter-PSSession](../Enter-PSSession.md) -Get-History +[Get-History](../Get-History.md) -Get-Random +[Get-Random](../../Microsoft.PowerShell.Utility/Get-Random.md) -Write-Host +[Write-Host](../../Microsoft.PowerShell.Utility/Write-Host.md) [about_Profiles](about_Profiles.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_pipelines.md b/reference/6/Microsoft.PowerShell.Core/About/about_pipelines.md index ec7b65c085af..97cd9535c505 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_pipelines.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_pipelines.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-30 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,41 +7,39 @@ title: about_pipelines --- # About Pipelines -## about_Pipelines - - ### Short Description -Combining commands into pipelines in the Windows PowerShell +Combining commands into pipelines in the PowerShell ### Long Description -A pipeline is a series of commands connected by pipeline operators -(`|`)(ASCII 124). Each pipeline operator sends the results of the preceding -command to the next command. +A pipeline is a series of commands connected by pipeline operators (`|`) +(ASCII 124). Each pipeline operator sends the results of the preceding command +to the next command. -You can use pipelines to send the objects that are output by one command -to be used as input to another command for processing. And you can send the -output of that command to yet another command. The result is a very powerful -command chain or "pipeline" that is comprised of a series of simple commands. +You can use pipelines to send the objects that are output by one command to be +used as input to another command for processing. And you can send the output +of that command to yet another command. The result is a very powerful command +chain or "pipeline" that is comprised of a series of simple commands. For example, + ```powershell Command-1 | Command-2 | Command-3 ``` In this example, the objects that `Command-1` emits are sent to `Command-2`. -`Command-2` processes the objects and sends them to `Command-3`. `Command-3` processes -the objects and send them down the pipeline. Because there are no more commands in -the pipeline, the results are displayed at the console. +`Command-2` processes the objects and sends them to `Command-3`. `Command-3` +processes the objects and send them down the pipeline. Because there are no +more commands in the pipeline, the results are displayed at the console. -In a pipeline, the commands are processed from left to right in the order -that they appear. The processing is handled as a single operation and -output is displayed as it is generated. +In a pipeline, the commands are processed from left to right in the order that +they appear. The processing is handled as a single operation and output is +displayed as it is generated. -Here is a simple example. The following command gets the Notepad process -and then stops it. +Here is a simple example. The following command gets the Notepad process and +then stops it. For example, ```powershell @@ -49,77 +47,69 @@ Get-Process notepad | Stop-Process ``` The first command uses the `Get-Process` cmdlet to get an object representing -the Notepad process. It uses a pipeline operator (`|`) to send the process object -to the `Stop-Process` cmdlet, which stops the Notepad process. Notice that the -`Stop-Process` command does not have a Name or ID parameter to specify the process, -because the specified process is submitted through the pipeline. +the Notepad process. It uses a pipeline operator (`|`) to send the process +object to the `Stop-Process` cmdlet, which stops the Notepad process. Notice +that the `Stop-Process` command does not have a Name or ID parameter to +specify the process, because the specified process is submitted through the +pipeline. Here is a practical example. This command pipeline gets the text files in the -current directory, selects only the files that are more than 10,000 bytes long, -sorts them by length, and displays the name and length of each file in a table. +current directory, selects only the files that are more than 10,000 bytes +long, sorts them by length, and displays the name and length of each file in a +table. ```powershell Get-ChildItem -Path *.txt | Where-Object {$_.length -gt 10000} | Sort-Object -Property length | Format-Table -Property name, length ``` -This pipeline is comprised of four commands in the specified order. The command -is written horizontally, but we will show the process vertically in the following -graphic. +This pipeline is comprised of four commands in the specified order. The +command is written horizontally, but we will show the process vertically in +the following graphic. `Get-ChildItem` `-Path` *.txt - **|** - -| (FileInfo objects ) -| ( .txt ) - - **|** - - **V** +``` +| +| (FileInfo objects for *.txt) +| +V +``` `Where-Object` {$_.length `-gt` 10000} - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| +V +``` `Sort-Object` `-Property` Length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) - - **|** - - **V** - +``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| +V +``` `Format-Table` `-Property` name, length - **|** - -| (FileInfo objects ) -| ( .txt ) -| ( Length > 10000 ) -| ( Sorted by length ) -| (Formatted in a table ) - - **|** - - **V** - ``` +| +| (FileInfo objects for *.txt) +| ( Length > 10000 ) +| ( Sorted by length ) +| ( Formatted in a table ) +| +V +``` + +```output Name Length ---- ------ tmp1.txt 82920 @@ -129,13 +119,13 @@ tmp3.txt 114000 ### Using Pipelines +The PowerShell cmdlets were designed to be used in pipelines. For example, you +can usually pipe the results of a Get cmdlet to an action cmdlet (such as a +Set, Start, Stop, or Rename cmdlet) for the same noun. -The Windows PowerShell cmdlets were designed to be used in pipelines. For example, -you can usually pipe the results of a Get cmdlet to an action cmdlet (such as a Set, -Start, Stop, or Rename cmdlet) for the same noun. - -For example, you can pipe any service from the `Get-Service` cmdlet to the `Start-Service` -or `Stop-Service` cmdlets (although disabled services cannot be restarted in this way). +For example, you can pipe any service from the `Get-Service` cmdlet to the +`Start-Service` or `Stop-Service` cmdlets (although disabled services cannot +be restarted in this way). This command pipeline starts the WMI service on the computer: @@ -144,90 +134,98 @@ For example, Get-Service wmi | Start-Service ``` -The cmdlets that get and set objects of the Windows PowerShell providers, such as the +The cmdlets that get and set objects of the PowerShell providers, such as the Item and ItemProperty cmdlets, are also designed to be used in pipelines. -For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` command in the -Windows PowerShell registry provider to the `New-ItemProperty` cmdlet. This command adds -a new registry entry, NoOfEmployees, with a value of 8124, to the MyCompany registry key. +For example, you can pipe the results of a `Get-Item` or `Get-ChildItem` +command in the PowerShell registry provider to the `New-ItemProperty` cmdlet. +This command adds a new registry entry, NoOfEmployees, with a value of 8124, +to the MyCompany registry key. For example, ```powershell -Get-Item -Path HKLM:\Software\MyCompany | New-ItemProperty -Name NoOfEmployees -Value 8124 +Get-Item -Path HKLM:\Software\MyCompany | + New-ItemProperty -Name NoOfEmployees -Value 8124 ``` -Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, `Sort-Object`, `Group-Object`, -and `Measure-Object` are used almost exclusively in pipelines. You can pipe any objects to -these cmdlets. +Many of the utility cmdlets, such as `Get-Member`, `Where-Object`, +`Sort-Object`, `Group-Object`, and `Measure-Object` are used almost +exclusively in pipelines. You can pipe any objects to these cmdlets. -For example, you can pipe all of the processes on the computer to the `Sort-Object` command -and have them sorted by the number of handles in the process. +For example, you can pipe all of the processes on the computer to the +`Sort-Object` command and have them sorted by the number of handles in the +process. For example, + ```powershell Get-Process | Sort-Object -Property handles ``` -Also, you can pipe any objects to the formatting cmdlets, such as `Format-List` and -`Format-Table`, the Export cmdlets, such as `Export-Clixml` and `Export-CSV`, and the Out -cmdlets, such as `Out-Printer`. +Also, you can pipe any objects to the formatting cmdlets, such as +`Format-List` and `Format-Table`, the Export cmdlets, such as `Export-Clixml` +and `Export-CSV`, and the Out cmdlets, such as `Out-Printer`. -For example, you can pipe the Winlogon process to the `Format-List` cmdlet to display all -of the properties of the process in a list. +For example, you can pipe the Winlogon process to the `Format-List` cmdlet to +display all of the properties of the process in a list. For example, + ```powershell Get-Process winlogon | Format-List -Property * ``` -With a bit of practice, you'll find that combining simple commands into pipelines -saves time and typing, and makes your scripting more efficient. +With a bit of practice, you'll find that combining simple commands into +pipelines saves time and typing, and makes your scripting more efficient. ### How Pipelines Work +When you "pipe" objects, that is send the objects in the output of one command +to another command, PowerShell tries to associate the piped objects with one +of the parameters of the receiving cmdlet. -When you "pipe" objects, that is send the objects in the output of one command to another -command, Windows PowerShell tries to associate the piped objects with one of the parameters -of the receiving cmdlet. - -To do so, the Windows PowerShell "parameter binding" component, which associates input objects -with cmdlet parameters, tries to find a parameter that meets the following criteria: +To do so, the PowerShell "parameter binding" component, which associates input +objects with cmdlet parameters, tries to find a parameter that meets the +following criteria: - The parameter must accept input from a pipeline (not all do) -- The parameter must accept the type of object being sent or a type that the object -can be converted to. +- The parameter must accept the type of object being sent or a type that the + object can be converted to. - The parameter must not already be used in the command. -For example, the `Start-Service` cmdlet has many parameters, but only two of them, `-Name` and `-InputObject` -accept pipeline input. The `-Name` parameter takes strings and the `-InputObject` parameter takes -service objects. Therefore, you can pipe strings and service objects (and objects with properties -that can be converted to string and service objects) to `Start-Service`. +For example, the `Start-Service` cmdlet has many parameters, but only two of +them, `-Name` and `-InputObject` accept pipeline input. The `-Name` parameter +takes strings and the `-InputObject` parameter takes service objects. +Therefore, you can pipe strings and service objects (and objects with +properties that can be converted to string and service objects) to +`Start-Service`. -If the parameter binding component of Windows PowerShell cannot associate the piped objects -with a parameter of the receiving cmdlet, the command fails and Windows PowerShell prompts you -for the missing parameter values. +If the parameter binding component of PowerShell cannot associate the piped +objects with a parameter of the receiving cmdlet, the command fails and +PowerShell prompts you for the missing parameter values. -You cannot force the parameter binding component to associate the piped objects with a particular -parameter -- you cannot even suggest a parameter. Instead, the logic of the component manages -the piping as efficiently as possible. +You cannot force the parameter binding component to associate the piped +objects with a particular parameter. You cannot even suggest a parameter. +Instead, the logic of the component manages the piping as efficiently as +possible. ### One-At-A-Time Processing +Piping objects to a command is much like using a parameter of the command to +submit the objects. -Piping objects to a command is much like using a parameter of the command to submit the -objects. - -For example, piping objects representing the services on the computer to a `Format-Table` command, -such as: +For example, piping objects representing the services on the computer to a +`Format-Table` command, such as: ```powershell Get-Service | Format-Table -Property name, dependentservices ``` -is much like saving the service objects in a variable and using the InputObject parameter -of `Format-Table` to submit the service object. +is much like saving the service objects in a variable and using the +InputObject parameter of `Format-Table` to submit the service object. For example, + ```powershell $services = Get-Service Format-Table -InputObject $services -Property name, dependentservices @@ -236,51 +234,58 @@ Format-Table -InputObject $services -Property name, dependentservices or imbedding the command in the parameter value For example, + ```powershell -Format-Table -InputObject (Get-Service wmi) -Property name, dependentservices +Format-Table -InputObject (Get-Service wmi) -Property name,dependentservices ``` -However, there is an important difference. When you pipe multiple objects to a command, -Windows PowerShell sends the objects to the command one at a time. When you use a -command parameter, the objects are sent as a single array object. +However, there is an important difference. When you pipe multiple objects to a +command, PowerShell sends the objects to the command one at a time. When you +use a command parameter, the objects are sent as a single array object. + +This seemingly technical difference can have interesting, and sometimes +useful, consequences. -This seemingly technical difference can have interesting, and sometimes useful, consequences. +For example, if you pipe multiple process objects from the `Get-Process` +cmdlet to the `Get-Member` cmdlet, PowerShell sends each process object, one +at a time, to `Get-Member`. `Get-Member` displays the .NET class (type) of the +process objects, and their properties and methods. -For example, if you pipe multiple process objects from the `Get-Process` cmdlet to the -`Get-Member` cmdlet, Windows PowerShell sends each process object, one at a time, to `Get-Member`. -`Get-Member` displays the .NET class (type) of the process objects, and their properties and methods. -(`Get-Member` eliminates duplicates, so if the objects are all of the same type, it displays only -one object type.) +NOTE: `Get-Member` eliminates duplicates, so if the objects are all of the +same type, it displays only one object type. -In this case, `Get-Member` displays the properties and methods of each process object, that is, a -System.Diagnostics.Process object. +In this case, `Get-Member` displays the properties and methods of each process +object, that is, a System.Diagnostics.Process object. For example, + ```powershell Get-Process | Get-Member ``` -``` +```Output TypeName: System.Diagnostics.Process -Name MemberType Definition ----- ---------- ---------- -Handles AliasProperty Handles = Handlecount -Name AliasProperty Name = ProcessName -NPM AliasProperty NPM = NonpagedSystemMemorySize +Name MemberType Definition +---- ---------- ---------- +Handles AliasProperty Handles = Handlecount +Name AliasProperty Name = ProcessName +NPM AliasProperty NPM = NonpagedSystemMemorySize ... ``` -However, if you use the InputObject parameter of `Get-Member`, then `Get-Member` receives an -array of System.Diagnostics.Process objects as a single unit, and it displays the properties -of an array of objects. (Note the array symbol ([]) after the System.Object type name.) +However, if you use the InputObject parameter of `Get-Member`, then +`Get-Member` receives an array of System.Diagnostics.Process objects as a +single unit, and it displays the properties of an array of objects. (Note the +array symbol ([]) after the System.Object type name.) For example, + ```powershell Get-Member -InputObject (Get-Process) ``` -``` +```Output TypeName: System.Object[] Name MemberType Definition @@ -291,30 +296,32 @@ Clone Method System.Object Clone() ... ``` -This result might not be what you intended, but after you understand it, you can use it. For -example, an array of process objects has a Count property that you can use to count the number -of processes on the computer. +This result might not be what you intended, but after you understand it, you +can use it. For example, an array of process objects has a Count property that +you can use to count the number of processes on the computer. For example, + ```powershell (Get-Process).count ``` -This distinction can be important, so remember that when you pipe objects to a cmdlet, they -are delivered one at a time. +This distinction can be important, so remember that when you pipe objects to a +cmdlet, they are delivered one at a time. ### Accepts Pipeline Input -In order to receive objects in a pipeline, the receiving cmdlet must have a parameter -that accepts pipeline input. You can use a `Get-Help` command with the **Full** or **Parameter** -parameters to determine which, if any, of a cmdlet's parameters accepts pipeline input. +In order to receive objects in a pipeline, the receiving cmdlet must have a +parameter that accepts pipeline input. You can use a `Get-Help` command with +the **Full** or **Parameter** parameters to determine which, if any, of a +cmdlet's parameters accepts pipeline input. -In the `Get-Help` default display, the "Accept pipeline input?" item appears in a table -of parameter attributes. This table is displayed only when you use the **Full** or **Parameter** -parameters of the `Get-Help` cmdlet. +In the `Get-Help` default display, the "Accept pipeline input?" item appears +in a table of parameter attributes. This table is displayed only when you use +the **Full** or **Parameter** parameters of the `Get-Help` cmdlet. -For example, to determine which of the parameters of the `Start-Service` cmdlet accepts -pipeline input, type: +For example, to determine which of the parameters of the `Start-Service` +cmdlet accepts pipeline input, type: ```powershell Get-Help Start-Service -Full @@ -326,108 +333,115 @@ or Get-Help Start-Service -Parameter * ``` -For example, the help for the `Start-Service` cmdlet shows that the **InputObject** and **Name** -parameters accept pipeline input ("true"). All other parameters have a value of "false" -in the "Accept pipeline input?" row. +For example, the help for the `Start-Service` cmdlet shows that the +**InputObject** and **Name** parameters accept pipeline input ("true"). All +other parameters have a value of "false" in the "Accept pipeline input?" row. ``` -InputObject - Specifies ServiceController objects representing the services to be started. - Enter a variable that contains the objects, or type a command or expression - that gets the objects. +Specifies ServiceController objects representing the services to be started. +Enter a variable that contains the objects, or type a command or expression +that gets the objects. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByValue) +Accept wildcard characters? false -Name - Specifies the service names for the service to be started. +Specifies the service names for the service to be started. - The parameter name is optional. You can use Name or its alias, ServiceName, - or you can omit the parameter name. +The parameter name is optional. You can use Name or its alias, ServiceName, +or you can omit the parameter name. - Required? true - Position? 0 - Default value None - Accept pipeline input? True (ByPropertyName, ByValue) - Accept wildcard characters? false +Required? true +Position? 0 +Default value None +Accept pipeline input? True (ByPropertyName, ByValue) +Accept wildcard characters? false ``` This means that you can send objects (PsObjects) through the pipeline to the -`Where-Object` cmdlet and Windows PowerShell will associate the object with the +`Where-Object` cmdlet and PowerShell will associate the object with the **InputObject** and **Name** parameters. ### Methods Of Accepting Pipeline Input - Cmdlets parameters can accept pipeline input in one of two different ways: - ByValue: Parameters that accept input "by value" can accept piped objects -that have the same .NET type as their parameter value or objects that can be -converted to that type. - -For example, the Name parameter of `Start-Service` accepts pipeline input -by value. It can accept string objects or objects that can be converted to -strings. + that have the same .NET type as their parameter value or objects that can be + converted to that type. -- ByPropertyName: Parameters that accept input "by property name" can accept piped -objects only when a property of the object has the same name as the parameter. + For example, the Name parameter of `Start-Service` accepts pipeline input by + value. It can accept string objects or objects that can be converted to + strings. -For example, the Name parameter of `Start-Service` can accept objects that have -a Name property. +- ByPropertyName: Parameters that accept input "by property name" can accept + piped objects only when a property of the object has the same name as the + parameter. -(To list the properties of an object, pipe it to `Get-Member`.) + For example, the Name parameter of `Start-Service` can accept objects that + have a Name property. To list the properties of an object, pipe it to + `Get-Member`. -Some parameters can accept objects by value or by property name. These parameters are -designed to take input from the pipeline easily. +Some parameters can accept objects by value or by property name. These +parameters are designed to take input from the pipeline easily. ### Investigating Pipeline Errors - -If a command fails because of a pipeline error, you can investigate the failure and -rewrite the command. +If a command fails because of a pipeline error, you can investigate the +failure and rewrite the command. For example, the following command tries to move a registry entry from one -registry key to another by using the `Get-Item` cmdlet to get the destination path and -then piping the path to the `Move-ItemProperty` cmdlet. +registry key to another by using the `Get-Item` cmdlet to get the destination +path and then piping the path to the `Move-ItemProperty` cmdlet. -Specifically, the command uses the `Get-Item` cmdlet to get the destination path. It uses -a pipeline operator to send the result to the `Move-ItemProperty` cmdlet. The `Move-ItemProperty` -command specifies the current path and name of the registry entry to be moved. +Specifically, the command uses the `Get-Item` cmdlet to get the destination +path. It uses a pipeline operator to send the result to the +`Move-ItemProperty` cmdlet. The `Move-ItemProperty` command specifies the +current path and name of the registry entry to be moved. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product ``` -``` -The command fails and Windows PowerShell displays the following error +The command fails and PowerShell displays the following error message: -Move-ItemProperty : The input object cannot be bound to any parameters for the -command either because the command does not take pipeline input or the input -and its properties do not match any of the parameters that take pipeline input. +```output +Move-ItemProperty : The input object cannot be bound to any parameters for +the command either because the command does not take pipeline input or the +input and its properties do not match any of the parameters that take +pipeline input. At line:1 char:23 -+ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name product ++ $a | Move-ItemProperty <<<< -Path HKLM:\software\mycompany\design -Name p ``` -To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding component of -Windows PowerShell. The following command traces the Parameter Binding component while the -command is processing. It uses the `-PSHost` parameter to display the results at the console -and the `-filepath` command to send them to the debug.txt file for later reference. +To investigate, use the `Trace-Command` cmdlet to trace the Parameter Binding +component of PowerShell. The following command traces the Parameter Binding +component while the command is processing. It uses the `-PSHost` parameter to +display the results at the console and the `-filepath` command to send them to +the debug.txt file for later reference. For example, + ```powershell -Trace-Command -Name parameterbinding -Expression {Get-Item -Path HKLM:\software\mycompany\sales | -Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} -PSHost -FilePath debug.txt +Trace-Command -Name parameterbinding -Expression { + Get-Item -Path HKLM:\software\mycompany\sales | + Move-ItemProperty -Path HKLM:\software\mycompany\design -Name product} ` + -PSHost -FilePath debug.txt ``` -The results of the trace are lengthy, but they show the values being bound to the `Get-Item` cmdlet -and then the named values being bound to the `Move-ItemProperty` cmdlet. +The results of the trace are lengthy, but they show the values being bound to +the `Get-Item` cmdlet and then the named values being bound to the +`Move-ItemProperty` cmdlet. +``` ... BIND NAMED cmd line args [`Move-ItemProperty`] @@ -442,31 +456,35 @@ BIND arg [product] to parameter [Name] BIND POSITIONAL cmd line args [`Move-ItemProperty`] ... +``` -Finally, it shows that the attempt to bind the path to the Destination parameter -of `Move-ItemProperty` failed. +Finally, it shows that the attempt to bind the path to the **Destination** +parameter of `Move-ItemProperty` failed. +``` ... BIND PIPELINE object to parameters: [`Move-ItemProperty`] PIPELINE object TYPE = [Microsoft.Win32.RegistryKey] RESTORING pipeline parameter's original values -Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION -Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION +Parameter [Destination] PIPELINE INPUT ValueFromPipelineByPropertyName NO CO +ERCION +Parameter [Credential] PIPELINE INPUT ValueFromPipelineByPropertyName NO COE +RCION ... +``` - -To investigate the failure, use the `Get-Help` cmdlet to view the attributes of the -**Destination** parameter. The following command gets detailed information about the -**Destination** parameter. +To investigate the failure, use the `Get-Help` cmdlet to view the attributes +of the **Destination** parameter. The following command gets detailed +information about the **Destination** parameter. ```powershell Get-Help Move-ItemProperty -Parameter Destination ``` -The results show that **Destination** takes pipeline input only "by property name". -That is, the piped object must have a property named Destination. +The results show that **Destination** takes pipeline input only "by property +name". That is, the piped object must have a property named Destination. ``` -Destination @@ -479,11 +497,12 @@ That is, the piped object must have a property named Destination. Accept wildcard characters? false ``` -To see the properties of the object being piped to the `Move-ItemProperty` cmdlet, -pipe it to the `Get-Member` cmdlet. The following command pipes the results of the -first part of the command to the `Get-Member` cmdlet. +To see the properties of the object being piped to the `Move-ItemProperty` +cmdlet, pipe it to the `Get-Member` cmdlet. The following command pipes the +results of the first part of the command to the `Get-Member` cmdlet. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\sales | Get-Member ``` @@ -491,11 +510,13 @@ Get-Item -Path HKLM:\software\mycompany\sales | Get-Member The output shows that the item is a Microsoft.Win32.RegistryKey that does not have a Destination property. That explains why the command failed. -To fix the command, we must specify the destination in the `Move-ItemProperty` cmdlet. We can -use a `Get-ItemProperty` command to get the path, but the name and destination must be specified -in the `Move-ItemProperty` part of the command. +To fix the command, we must specify the destination in the `Move-ItemProperty` +cmdlet. We can use a `Get-ItemProperty` command to get the path, but the name +and destination must be specified in the `Move-ItemProperty` part of the +command. For example, + ```powershell Get-Item -Path HKLM:\software\mycompany\design | Move-ItemProperty -Dest HKLM:\software\mycompany\design -Name product @@ -510,9 +531,11 @@ Get-Itemproperty HKLM:\software\mycompany\sales The results show that the Product registry entry was moved to the Sales key. -``` -PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany\sales -PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany +```Output +PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany\sales +PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\softwa +re\mycompany PSChildName : sales PSDrive : HKLM PSProvider : Microsoft.PowerShell.Core\Registry diff --git a/reference/6/Microsoft.PowerShell.Management/Get-Process.md b/reference/6/Microsoft.PowerShell.Management/Get-Process.md index 0cd95c5dfc8b..89bb191d56a4 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-Process.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-Process.md @@ -108,22 +108,23 @@ The pipeline operator passes the objects to the **Format-Table** cmdlet, which f The Priority view, and other views, are defined in the PS1XML format files in the Windows PowerShell home directory ($pshome). ### Example 5: Add a property to the standard Get-Process output display -``` -PS C:\> Get-Process Powershell -ComputerName S1, localhost | ft @{Label="NPM(K)";Expression={[int]($_.NPM/1024)}}, @{Label="PM(K)";Expression={[int]($_.PM/1024)}},@{Label="WS(K)";Expression={[int]($_.WS/1024)}},@{Label="VM(M)";Expression={[int]($_.VM/1MB)}}, @{Label="CPU(s)";Expression={if ($_.CPU -ne $()) { $_.CPU.ToString("N")}}}, Id, MachineName, ProcessName -Auto - - - - - +```powershell +PS C:\> Get-Process pwsh | + ft @{Label = "NPM(K)"; Expression = {[int]($_.NPM / 1024)}}, + @{Label = "PM(K)"; Expression = {[int]($_.PM / 1024)}}, + @{Label = "WS(K)"; Expression = {[int]($_.WS / 1024)}}, + @{Label = "VM(M)"; Expression = {[int]($_.VM / 1MB)}}, + @{Label = "CPU(s)"; Expression = {if ($_.CPU) {$_.CPU.ToString("N")}}}, + Id, MachineName, ProcessName -Auto NPM(K) PM(K) WS(K) VM(M) CPU(s) Id MachineName ProcessName ------ ----- ----- ----- ------ -- ----------- ----------- -6 23500 31340 142 1980 S1 powershell -6 23500 31348 142 4016 S1 powershell -27 54572 54520 576 4428 localhost powershell + 6 23500 31340 142 1.70 1980 . pwsh + 6 23500 31348 142 2.75 4016 . pwsh + 27 54572 54520 576 5.52 4428 . pwsh ``` -This example provides a **Format-Table** (alias = ft) command that adds the **MachineName** property to the standard **Get-Process** output display. +This example provides a `Format-Table` (alias = ft) command that adds the MachineName property to the standard `Get-Process` output display. ### Example 6: Get version information for a process ``` diff --git a/reference/6/Microsoft.PowerShell.Management/Join-Path.md b/reference/6/Microsoft.PowerShell.Management/Join-Path.md index 152267cf80b4..bb32e3a81c9c 100644 --- a/reference/6/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/6/Microsoft.PowerShell.Management/Join-Path.md @@ -15,10 +15,10 @@ Combines a path and a child path into a single path. ## SYNTAX -``` -Join-Path [-Path] [-ChildPath] [-AdditionalChildPath ] [-Resolve] - [-Credential ] [-InformationAction ] [-InformationVariable ] - [-UseTransaction] [] +```powershell +Join-Path [-Path] [-ChildPath] + [[-AdditionalChildPath] ] + [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## DESCRIPTION @@ -82,7 +82,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: Named +Position: 2 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False @@ -99,7 +99,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False @@ -127,33 +127,6 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Path Specifies the main path (or paths) to which the child-path is appended. Wildcards are permitted. @@ -167,7 +140,7 @@ Parameter Sets: (All) Aliases: PSPath Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md b/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md index f49eb60283a7..7b4f28a1ba40 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md @@ -16,8 +16,7 @@ Gets Windows PowerShell components that are instrumented for tracing. ## SYNTAX ``` -Get-TraceSource [[-Name] ] [-InformationAction ] [-InformationVariable ] - [] +Get-TraceSource [[-Name] ] [] ``` ## DESCRIPTION @@ -46,33 +45,6 @@ This command gets all of the Windows PowerShell components that can be traced. ## PARAMETERS -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Name Specifies the trace sources to get. Wildcards are permitted. @@ -84,7 +56,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/docs-conceptual/getting-started/understanding-concepts-reference.md b/reference/docs-conceptual/getting-started/understanding-concepts-reference.md index db0888cd5056..75f3180da47b 100644 --- a/reference/docs-conceptual/getting-started/understanding-concepts-reference.md +++ b/reference/docs-conceptual/getting-started/understanding-concepts-reference.md @@ -1,4 +1,4 @@ -.md--- +--- ms.date: 2017-06-05 keywords: powershell,cmdlet title: understanding concepts reference