diff --git a/contributing/STYLE.md b/contributing/STYLE.md index c17e3e0562a8..1d321f9db02a 100644 --- a/contributing/STYLE.md +++ b/contributing/STYLE.md @@ -111,19 +111,94 @@ to get this output: ## Links -* Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url)` -* Links should have a a friendly name when applicable, most likely the title of the linked page - * **Exception**: Links to non-Microsoft sites can be bare URLs +* Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url-or-path)` + * **Exception**: Links to non-Microsoft sites can be bare URLs for transparency +* Links must have a friendly name, usually the title of the linked topic * All items in the "related links" section at the bottom should be hyperlinked. +* Use relative links when linking to other content that is hosted on **docs.microsoft.com**. -## Using relative links +### Structure of links on docs.microsoft.com + +Content presented on docs.microsoft.com has the following URL structure: + +``` +https://docs.microsoft.com///[]/[]/[?view=] +``` + +Examples: + +``` +https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview +https://docs.microsoft.com/en-us/powershell/azure/overview?view=azurermps-5.1.1 +``` + +- **\** - identifies the language of the article (example: en-us or de-de) +- **\** - the name of the product or service being documented (example: powerShell, dotnet, or azure) +- **[\]** - (optional) the name of the product's feature or subservice (for example, csharp or load-balancer) +- **[\]** - (optional) the name of a subfolder within a feature +- \ - the name of the article file for the topic (example: load-balancer-overview or overview) +- **[?view=\]** - (optional) the view name used by the version selector for content that has multiple versions available (example: azurermps-5.1.1) + +### Linking to content in the same repo -You should use relative links when linking to other content that is hosted on **docs.microsoft.com**. When the content is in the same repo, the relative links are simple to calculate. -Note that the path to cmdlet reference is created by our publishing system. -There are special rules for linking to reference topics from conceptual topics. +The link target must be the path to the _Markdown file_ in the repo. +For example, the following markdown links to the about_Arrays topic in this repo. + +```Markdown +[about_Arrays](../reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md) +``` + +Here is the live link: + +[about_Arrays](../reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md) + +Note that the live link works within the GitHub view of this content. + +### Linking to content in a different repo + +When the content is in a different repo, the relative links are more complicated. +The link target must be the URL path to the _published article_ on **docs.microsoft.com**. +The relative link starts with the **\** portion of the URL as described above. +You should omit the **[?view=\]** portion unless you need to link to a specific version of the content. + +For example, the following markdown links to the Overview topic for Azure PowerShell. + +```Markdown +[Overview of Azure PowerShell](/powershell/azure/overview) +``` + +Here is the live link: + +[Overview of Azure PowerShell](/powershell/azure/overview) + +Note that the live link does not resolve within the GitHub view of this content. +This link only works on the webpage published to **docs.microsoft.com**. + +## Markdown extensions supported by Open Publishing +The following sections describe supported extensions in Open Publishing. + +### Note, warning, tip, important +Use specific syntax inside a block quote to indicate that the content is a type of note. + +```Markdown +> [!NOTE] +> This is a note. + +> [!WARNING] +> This is a warning. + +> [!TIP] +> This is a tip. + +> [!IMPORTANT] +> This is important. + +``` + +And it will be rendered like this: -\[TO DO\] - document special rules +![alert boxes](./images/alert-boxes.png) ## Next steps @@ -137,4 +212,4 @@ See [Formatting code blocks](FORMATTING-CODE.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/ -[platyPS]: https://github.com/PowerShell/platyPS \ No newline at end of file +[platyPS]: https://github.com/PowerShell/platyPS diff --git a/contributing/WRITING.md b/contributing/WRITING.md index 4cab02420487..3b877c853697 100644 --- a/contributing/WRITING.md +++ b/contributing/WRITING.md @@ -1,7 +1,10 @@ # Writing PowerShell documentation One of the easiest ways to contribute to PowerShell is by helping to write and edit documentation. -All of our documentation hosted on GitHub is written using GitHub Flavored Markdown (GFM). +All of our documentation hosted on GitHub is written using *Markdown*. +Markdown is a lightweight markup language with plain text formatting syntax. +Markdown forms the basis of our documentation's conceptual authoring language. +Creating new articles is as easy as writing a simple text file by using your favorite text editor. ## Markdown editors @@ -12,9 +15,9 @@ Here are some Markdown editors you can try out: * [Atom](https://atom.io/) * [Sublime Text](http://www.sublimetext.com/) -## Using GitHub Flavored Markdown +## Get started using Markdown -To get started using GFM, see GitHub's Help topics for [Writing on GitHub][gfm-help]. +To get started using Markdown, see GitHub's Help topics for [Writing on GitHub][gfm-help]. **NOTE:** GitHub recently adopted the CommonMark specification (with GFM extensions) for its Markdown syntax. In the new specification, many spacing rules have changed. @@ -22,6 +25,10 @@ Spaces are significant in GFM. Do not use hard tabs in Markdown. For more detailed information about the Markdown specification, see the [GitHub Flavored Markdown Spec][gfm-spec]. +DocFX, used by OPS, supports DocFX Flavored Markdown (DFM). +DFM is highly compatible with GitHub Flavored Markdown (GFM) and adds some functionality, including cross-reference and file inclusion. +There are [differences between DFM and GFM][dfm-diffs] that can affect content preview in GitHub or your editor. + ## Creating new topics If you want to contribute new documentation, first check for [issues tagged as "in progress"][labels] @@ -53,4 +60,5 @@ Read the [Style Guide](STYLE.md). [gfm-help]: https://help.github.com/categories/writing-on-github/ [gfm-spec]: https://github.github.com/gfm/ [labels]: https://github.com/PowerShell/PowerShell-Docs/labels/in%20progress -[gfm-task]: https://github.github.com/gfm/#task-list-items-extension- \ No newline at end of file +[gfm-task]: https://github.github.com/gfm/#task-list-items-extension- +[dfm-diffs]: http://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#differences-between-dfm-and-gfm \ No newline at end of file diff --git a/contributing/images/alert-boxes.png b/contributing/images/alert-boxes.png new file mode 100644 index 000000000000..f033cd52ed60 Binary files /dev/null and b/contributing/images/alert-boxes.png differ diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/6/Microsoft.PowerShell.Management/Set-Content.md b/reference/6/Microsoft.PowerShell.Management/Set-Content.md index b23a4fd8a3d3..0ce956f144ac 100644 --- a/reference/6/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Set-Content.md @@ -402,8 +402,6 @@ Otherwise, this cmdlet does not generate any output. ## NOTES -You can also refer to Set-Content by its built-in alias, "sc". For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - Set-Content is designed for string processing. If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. To write objects to files, use Out-File. diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md new file mode 100644 index 000000000000..32bcb7b11aff --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md @@ -0,0 +1,154 @@ +--- +ms.date: 2017-06-09 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +online version: +external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml +title: ConvertFrom-Clixml +--- + +# ConvertFrom-Clixml + +## SYNOPSIS +Converts an CLIXML string into new corresponding object in Windows PowerShell. + +## SYNTAX + +``` +ConvertFrom-Clixml -InputObject [-IncludeTotalCount] [-Skip ] [-First ] [] +``` + +## DESCRIPTION +The **ConvertFrom-CliXml** cmdlet converts a CLIXML string with data that represents Microsoft .NET Framework objects and creates the objects in Windows PowerShell. + +A valuable use of **ConvertFrom-CliXml** is to deserialize credentials and secure strings that have been serialized as secure XML by running the ConvertTo-Clixml cmdlet. +For an example of how to do this, see Example 2. + +## EXAMPLES + +### Example 1: Import a serialized file and recreate an object + +```powershell +$clixml = Get-Process | ConvertTo-Clixml +$Processes = ConvertFrom-Clixml $clixml +``` + +This command uses the ConvertTo-Clixml cmdlet to create a serialized copy of the process information returned by Get-Process. +It then uses **ConvertFrom-Clixml** to retrieve the contents of the serialized string and re-create an object that is stored in the $Processes variable. + +### Example 2: Convert an encrypted credential object + +```powershell +$CredXml = $Credential | ConvertTo-Clixml +$Credential = ConvertFrom-CliXml $CredXml +``` + +The **ConvertTo-CliXml** cmdlet encrypts credential objects by using the +[Windows Data Protection API](http://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx). +This ensures that only your user account can decrypt the contents of the credential object. + +In this example, given a credential that you've stored in the $Credential variable by running the Get-Credential cmdlet, you can run the **ConvertTo-CliXml** cmdlet to serialize the credential to a string. + +To deserialize the credential later, run the second command. +This time, you are running ConvertFrom-Clixml to import the secured credential object into your script. +This eliminates the risk of exposing plain-text passwords in your script. + +## PARAMETERS + +### -InputObject +Specifies the CLIXML string to be converted to objects. +You can also pipe the CLIXML string to **ConvertFrom-Clixml**. + +```yaml +Type: string +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -First +Gets only the specified number of objects. +Enter the number of objects to get. + +```yaml +Type: UInt64 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Skip +Ignores the specified number of objects and then gets the remaining objects. +Enter the number of objects to skip. + +```yaml +Type: UInt64 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeTotalCount +Reports the total number of objects in the data set (an integer) followed by the selected objects. +If the cmdlet cannot determine the total count, it displays "Unknown total count." The integer has an Accuracy property that indicates the reliability of the total count value. +The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet could not count the objects, 1.0 means that the count is exact, and a value between 0.0 and 1.0 indicates an increasingly reliable estimate. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). + +## INPUTS + +### System.String +You can pipe a string that contains a path to **ConvertFrom-Clixml**. + +## OUTPUTS + +### PSObject +**ConvertFrom-Clixml** returns objects that have been deserialized from the stored XML files. + +## NOTES +* When specifying multiple values for a parameter, use commas to separate the values. For example, "\ \, \". + +* + +## RELATED LINKS + +[Use PowerShell to Pass Credentials to Legacy Systems](http://blogs.technet.com/b/heyscriptingguy/archive/2011/06/05/use-powershell-to-pass-credentials-to-legacy-systems.aspx) + +[Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk) + +[Export-Clixml](Export-Clixml.md) + +[Import-Clixml](Import-Clixml.md) + +[ConvertTo-Clixml](ConvertTo-Clixml.md) + + diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md new file mode 100644 index 000000000000..dfca81a1ca09 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md @@ -0,0 +1,169 @@ +--- +ms.date: 2017-06-09 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +online version: +external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml +title: ConvertTo-Clixml +--- + +# ConvertTo-Clixml + +## SYNOPSIS +Converts objects to an XML-based representation and returns that as a string. + +## SYNTAX + +``` +ConvertTo-Clixml [-Depth ] -InputObject [-Encoding ] [] +``` + +## DESCRIPTION +The **ConvertTo-CliXml** cmdlet creates XML-based representations of objects and returns them as strings. +You can then use the **ConvertFrom-Clixml** cmdlet to re-create the saved objects based on the contents of the strings. + +A valuable use of **ConvertTo-CliXml** is to serialize credentials and secure strings securely as XML. +For an example of how to do this, see Example 3. + +## EXAMPLES + +### Example 1: Convert a string to an XML representation + +```powershell +"This is a test" | ConvertTo-Clixml +``` + +This command returns a string with am XML-based representation of the string object with a value of "This is a test". + +### Example 2: Convert an object to an XML-based representation + +```powershell +$FileaclString = Get-Acl C:\test.txt | ConvertTo-Clixml +Fileacl = ConvertFrom-Clixml $FileaclString +``` + +This example shows how to convert an object to an XML string and then create an object by converting the XML from the string. + +The first command uses the Get-Acl cmdlet to get the security descriptor of the Test.txt file. +It uses a pipeline operator to pass the security descriptor to **ConvertTo-Clixml**, which converts the object to an XML-based representation and returns that as a string. +Then, it saves the string in the $FileAclString variable. + +The second command uses the ConvertFrom-Clixml cmdlet to create an object from the XML in the $FileAclString variable. +Then, it saves the object in the $FileAcl variable. + +### Example 3: Convert an encrypted credential object + +```powershell +$CredXml = $Credential | ConvertTo-Clixml +$Credential = ConvertFrom-CliXml $CredXml +``` + +The **ConvertTo-CliXml** cmdlet encrypts credential objects by using the +[Windows Data Protection API](http://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx). +This ensures that only your user account can decrypt the contents of the credential object. + +In this example, given a credential that you've stored in the $Credential variable by running the Get-Credential cmdlet, you can run the **ConvertTo-CliXml** cmdlet to serialize the credential to a string. + +To deserialize the credential later, run the second command. +This time, you are running ConvertFrom-Clixml to import the secured credential object into your script. +This eliminates the risk of exposing plain-text passwords in your script. + +## PARAMETERS + +### -Depth +Specifies how many levels of contained objects are included in the XML representation. +The default value is 2. + +The default value can be overridden for the object type in the Types.ps1xml files. +For more information, see about_Types.ps1xml. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Encoding +Specifies the type of encoding for the target file. +The acceptable values for this parameter are: + +- ASCII +- UTF8 +- UTF7 +- UTF32 +- Unicode +- BigEndianUnicode +- Default +- OEM + +The default value is Unicode. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject +Specifies the object to be converted. +Enter a variable that contains the objects, or type a command or expression that gets the objects. +You can also pipe objects to **ConvertTo-Clixml**. + +```yaml +Type: PSObject +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). + +## INPUTS + +### System.Management.Automation.PSObject +You can pipe any object to **ConvertTo-Clixml**. + +## OUTPUTS + +### System.String +The XML-based representation is returned as a collection of strings. + +## NOTES + +## RELATED LINKS + +[Use PowerShell to Pass Credentials to Legacy Systems](http://blogs.technet.com/b/heyscriptingguy/archive/2011/06/05/use-powershell-to-pass-credentials-to-legacy-systems.aspx) + +[Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk) + +[ConvertTo-Json](ConvertTo-Json.md) + +[ConvertTo-Xml](ConvertTo-Xml.md) + +[ConvertTo-Csv](ConvertTo-Csv.md) + +[Export-Clixml](Export-Clixml.md) + +[Import-Clixml](Import-Clixml.md) + +[ConvertFrom-Clixml](ConvertFrom-Clixml.md) diff --git a/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md index 8ae22d949270..8507862cf847 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md @@ -18,15 +18,13 @@ Creates an XML-based representation of an object or objects and stores it in a f ### ByPath (Default) ``` Export-Clixml [-Depth ] [-Path] -InputObject [-Force] [-NoClobber] - [-Encoding ] [-InformationAction ] [-InformationVariable ] [-WhatIf] - [-Confirm] [] + [-Encoding ] [-WhatIf] [-Confirm] [] ``` ### ByLiteralPath ``` Export-Clixml [-Depth ] -LiteralPath -InputObject [-Force] [-NoClobber] - [-Encoding ] [-InformationAction ] [-InformationVariable ] [-WhatIf] - [-Confirm] [] + [-Encoding ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -42,16 +40,18 @@ For an example of how to do this, see Example 3. ## EXAMPLES ### Example 1: Export a string to an XML file -``` -PS C:\> "This is a test" | Export-Clixml sample.xml + +```powershell +"This is a test" | Export-Clixml sample.xml ``` This command creates an XML file that stores a representation of the string, "This is a test". ### Example 2: Export an object to an XML file -``` -PS C:\> Get-Acl C:\test.txt | Export-Clixml -Path "fileacl.xml" -PS C:\> $Fileacl = Import-Clixml "fileacl.xml" + +```powershell +Get-Acl C:\test.txt | Export-Clixml -Path "fileacl.xml" +$Fileacl = Import-Clixml "fileacl.xml" ``` This example shows how to export an object to an XML file and then create an object by importing the XML from the file. @@ -63,11 +63,12 @@ The second command uses the Import-Clixml cmdlet to create an object from the XM Then, it saves the object in the $FileAcl variable. ### Example 3: Encrypt an exported credential object -``` -PS C:\> $CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $credential | Export-CliXml $CredPath -PS C:\> $CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $Credential = Import-CliXml $CredXmlPath + +```powershell +$CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$credential | Export-CliXml $CredPath +$CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$Credential = Import-CliXml $CredXmlPath ``` The **Export-CliXml** cmdlet encrypts credential objects by using the Windows Data Protection APIhttp://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx. @@ -149,33 +150,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.```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 -The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -275,7 +249,7 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -301,5 +275,9 @@ You can pipe any object to **Export-Clixml**. [Export-Csv](Export-Csv.md) +[ConvertTo-Clixml](ConvertTo-Clixml.md) + +[ConvertFrom-Clixml](ConvertFrom-Clixml.md) + [Import-Clixml](Import-Clixml.md) diff --git a/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md index 9b10800a07a1..84bf429635d1 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md @@ -17,14 +17,12 @@ Imports a CLIXML file and creates corresponding objects in Windows PowerShell. ### ByPath (Default) ``` -Import-Clixml [-Path] [-InformationAction ] [-InformationVariable ] - [-IncludeTotalCount] [-Skip ] [-First ] [] +Import-Clixml [-Path] [-IncludeTotalCount] [-Skip ] [-First ] [] ``` ### ByLiteralPath ``` -Import-Clixml -LiteralPath [-InformationAction ] [-InformationVariable ] - [-IncludeTotalCount] [-Skip ] [-First ] [] +Import-Clixml -LiteralPath [-IncludeTotalCount] [-Skip ] [-First ] [] ``` ## DESCRIPTION @@ -36,20 +34,22 @@ For an example of how to do this, see Example 2. ## EXAMPLES ### Example 1: Import a serialized file and recreate an object -``` -PS C:\> Get-Process | Export-Clixml pi.xml -PS C:\> $Processes = Import-Clixml pi.xml + +```powershell +Get-Process | Export-Clixml pi.xml +$Processes = Import-Clixml pi.xml ``` This command uses the Export-Clixml cmdlet to save a serialized copy of the process information returned by Get-Process. It then uses **Import-Clixml** to retrieve the contents of the serialized file and re-create an object that is stored in the $Processes variable. ### Example 2: Import a secure credential object -``` -PS C:\> $Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $Credential | Export-CliXml $Credxmlpath -PS C:\> $Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $Credential = Import-CliXml $Credxmlpath + +```powershell +$Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$Credential | Export-CliXml $Credxmlpath +$Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$Credential = Import-CliXml $Credxmlpath ``` The **Export-CliXml** cmdlet encrypts credential objects by using the Windows Data Protection APIhttp://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx. @@ -68,33 +68,6 @@ This eliminates the risk of exposing plain-text passwords in your script. ## 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 -``` - ### -Path Specifies the XML files. @@ -179,7 +152,7 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -202,5 +175,9 @@ You can pipe a string that contains a path to **Import-Clixml**. [Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk) +[ConvertTo-Clixml](ConvertTo-Clixml.md) + +[ConvertFrom-Clixml](ConvertFrom-Clixml.md) + [Export-Clixml](Export-Clixml.md) diff --git a/reference/docs-conceptual/PowerShell-Core-Support.md b/reference/docs-conceptual/PowerShell-Core-Support.md new file mode 100644 index 000000000000..74656d24f813 --- /dev/null +++ b/reference/docs-conceptual/PowerShell-Core-Support.md @@ -0,0 +1,97 @@ +# PowerShell Core Support Lifecycle + +PowerShell Core is a distinct set of tools and components that is shipped, installed, and configured separately from Windows PowerShell. +Therefore, PowerShell Core is not included in the Windows 7/8.1/10 or Windows Server licensing agreements. + +However, PowerShell Core is supported under traditional Microsoft support agreements, including [Premier][], [Microsoft Enterprise Agreements][enterprise-agreement], and [Microsoft Software Assurance][assurance]. +You can also pay for [assisted support][] for PowerShell Core by filing a support request for your problem. + +We also offer [community support][] on GitHub where you can file an issue, bug, or feature request. +Alternatively, you may find help from other members of the community on the general [Microsoft Community][] or the Microsoft [PowerShell Tech Community][]. +We offer no guarantee there that your issue will be addressed or resolved in a timely manner. +If you have a problem that requires immediate attention, +you should use the traditional, paid support options. + +## Lifecycle of PowerShell Core + +PowerShell Core is adopting the [Microsoft Modern Lifecycle Policy][modern]. +This support lifecycle is intended to keep customers up-to-date with the latest versions. + +The version 6.x branch of PowerShell Core will be updated approximately once every six months (e.g. 6.0, 6.1, 6.2, etc.) + +> [!IMPORTANT] +> You must update within six months after each new minor version release to continue receiving support. + +For example, if PowerShell Core 6.1 is released on July 1st, 2018, +you would be expected to update to PowerShell Core 6.1 by January 1st, 2019 to maintain support. + +![PowerShell Core branch lifecycle][lifecycle-chart] + +The Modern Lifecycle Policy also requires that Microsoft give customers 12 months notice before discontinuing support for a product (i.e. PowerShell Core). + +Eventually, we expect PowerShell Core will adopt the "long-term servicing" approach where we would require only servicing and security updates to stay in support on a specific branch/version of 6.x. + +## Supported platforms + +PowerShell Core is officially supported on the following platforms: + +* Windows 7, 8.1, and 10 +* Windows Server 2008 R2, 2012 R2, 2016 +* [Windows Server Semi-Annual Channel][semi-annual] +* Ubuntu 14.04, 16.04, and 17.04 +* Debian 8.7+, and 9 +* CentOS 7 +* Red Hat Enterprise Linux 7 +* OpenSUSE 42.2 +* Fedora 25, 26 +* macOS 10.12+ + +Our community has also contributed packages for the following platforms, +but they are not officially suppported: + +* Arch Linux +* Kali Linux +* AppImage (works on multiple Linux platforms) + +## Notes on licensing + +PowerShell Core is released under the [MIT license][]. +Under this license, and in the absence of a paid support agreement, +users are limited to [community support][]. +With community support, Microsoft makes no guarantees of responsiveness or fixes. + +## Windows PowerShell Module + +Support for PowerShell Core does not extend to other product modules unless those modules explicitly support PowerShell Core. +For example, using the `ActiveDirectory` module that ships as part of Windows Server is an unsupported scenario. + +However, modules that do not explicitly support PowerShell Core may be compatible in some cases. +By installing the [`WindowsPSModulePath`][] module, +you can append the Windows PowerShell `PSModulePath` to your PowerShell Core `PSModulePath`. + +First, install the `WindowsPSModulePath` module from the PowerShell Gallery: + +```powershell +# Add `-Scope CurrentUser` if you're installing as non-admin +Install-Module WindowsPSModulePath -Force +``` + +After installing this module, run the `Add-WindowsPSModulePath` cmdlet to add the Windows PowerShell `PSModulePath` to PowerShell Core: + +```powershell +# Add this line to your profile if you always want Windows PowerShell PSModulePath +Add-WindowsPSModulePath +``` + +[Premier]: https://www.microsoft.com/en-us/microsoftservices/support.aspx +[enterprise-agreement]: https://www.microsoft.com/en-us/licensing/licensing-programs/enterprise.aspx +[assurance]: https://www.microsoft.com/en-us/licensing/licensing-programs/software-assurance-default.aspx +[community support]: https://github.com/powershell/powershell/issues +[Microsoft Community]: https://answers.microsoft.com/ +[PowerShell Tech Community]: https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell +[assisted support]: https://support.microsoft.com/assistedsupportproducts +[modern]: https://support.microsoft.com/help/30881/modern-lifecycle-policy +[lifecycle-chart]: ./images/modern-lifecycle.png +[semi-annual]: https://docs.microsoft.com/windows-server/get-started/semi-annual-channel-overview +[MIT license]: https://github.com/PowerShell/PowerShell/blob/master/LICENSE.txt +[`WindowsPSModulePath`]: https://www.powershellgallery.com/packages/WindowsPSModulePath/ diff --git a/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md b/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md index bdd7befe9e78..121d608858a2 100644 --- a/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md +++ b/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md @@ -6,18 +6,31 @@ ms.assetid: d6938b56-7dc8-44ba-b4d4-cd7b169fd74d --- # Running Remote Commands + You can run commands on one or hundreds of computers with a single Windows PowerShell command. Windows PowerShell supports remote computing by using various technologies, including WMI, RPC, and WS-Management. +## Remoting in PowerShell Core + +PowerShell Core, the newer edition of PowerShell on Windows, macOS, and Linux, +supports WMI, WS-Management, and SSH remoting. +(RPC is no longer supported.) + +For more information on setting this up, see: + +* [SSH Remoting in PowerShell Core][ssh-remoting] +* [WinRM Remoting in PowerShell Core][winrm-remoting] + ## Remoting Without Configuration Many Windows PowerShell cmdlets have the ComputerName parameter that enables you to collect data and change settings on one or more remote computers. They use a variety of communication technologies and many work on all Windows operating systems that Windows PowerShell supports without any special configuration. These cmdlets include: + * [Restart-Computer](https://go.microsoft.com/fwlink/?LinkId=821625) * [Test-Connection](https://go.microsoft.com/fwlink/?LinkId=821646) * [Clear-EventLog](https://go.microsoft.com/fwlink/?LinkId=821568) * [Get-EventLog](https://go.microsoft.com/fwlink/?LinkId=821585) * [Get-HotFix](https://go.microsoft.com/fwlink/?LinkId=821586) - - [Get-Process](https://go.microsoft.com/fwlink/?linkid=821590) +* [Get-Process](https://go.microsoft.com/fwlink/?linkid=821590) * [Get-Service](https://go.microsoft.com/fwlink/?LinkId=821593) * [Set-Service](https://go.microsoft.com/fwlink/?LinkId=821633) * [Get-WinEvent](https://go.microsoft.com/fwlink/?linkid=821529) @@ -134,3 +147,6 @@ For help with remoting errors, see [about_Remote_Troubleshooting](https://techne - [New-PSSession](https://go.microsoft.com/fwlink/?LinkId=821498) - [Register-PSSessionConfiguration](https://go.microsoft.com/fwlink/?LinkId=821508) - [WSMan Provider](https://technet.microsoft.com/en-us/library/66fe1241-e08f-49ca-832f-a84c33ca8735) + +[wsman-remoting]: WSMan-Remoting-in-PowerShell-Core.md +[ssh-resmoting]: SSH-Remoting-in-PowerShell-Core.md diff --git a/reference/docs-conceptual/core-powershell/SSH-Remoting-in-PowerShell-Core.md b/reference/docs-conceptual/core-powershell/SSH-Remoting-in-PowerShell-Core.md new file mode 100644 index 000000000000..163e1c9f10b7 --- /dev/null +++ b/reference/docs-conceptual/core-powershell/SSH-Remoting-in-PowerShell-Core.md @@ -0,0 +1,221 @@ +# PowerShell Remoting Over SSH + +## Overview + +PowerShell remoting normally uses WinRM for connection negotiation and data transport. +SSH was chosen for this remoting implementation since it is now available for both Linux and Windows platforms and allows true multiplatform PowerShell remoting. +However, WinRM also provides a robust hosting model for PowerShell remote sessions which this implementation does not yet do. +And this means that PowerShell remote endpoint configuration and JEA (Just Enough Administration) is not yet supported in this implementation. + +PowerShell SSH remoting lets you do basic PowerShell session remoting between Windows and Linux machines. +This is done by creating a PowerShell hosting process on the target machine as an SSH subsystem. +Eventually this will be changed to a more general hosting model similar to how WinRM works in order to support endpoint configuration and JEA. + +The New-PSSession, Enter-PSSession and Invoke-Command cmdlets now have a new parameter set to facilitate this new remoting connection + +```powershell +[-HostName ] [-UserName ] [-KeyFilePath ] +``` + +This new parameter set will likely change but for now allows you to create SSH PSSessions that you can interact with from the command line or invoke commands and scripts on. +You specify the target machine with the HostName parameter and provide the user name with UserName. +When running the cmdlets interactively at the PowerShell command line you will be prompted for a password. +But you also have the option to use SSH key authentication and provide a private key file path with the KeyFilePath parameter. + +## General setup information + +SSH is required to be installed on all machines. +You should install both client (ssh.exe) and server (sshd.exe) so that you can experiment with remoting to and from the machines. +For Windows you will need to install [Win32 OpenSSH from GitHub](https://github.com/PowerShell/Win32-OpenSSH/releases). +For Linux you will need to install SSH (including sshd server) appropriate to your platform. +You will also need a recent PowerShell build or package from GitHub having the SSH remoting feature. +SSH subsystems is used to establish a PowerShell process on the remote machine and the SSH server will need to be configured for that. +In addition you will need to enable password authentication and optionally key based authentication. + +## Setup on Windows Machine + +1. [Install the latest version of PowerShell Core for Windows][] + - You can tell if it has the SSH remoting support by looking at the parameter sets for New-PSSession + ```powershell + PS> Get-Command New-PSSession -syntax + New-PSSession [-HostName] [-Name ] [-UserName ] [-KeyFilePath ] [-SSHTransport] [] + ``` +1. Install the latest [Win32 OpenSSH] build from GitHub using the [installation] instructions +1. Edit the sshd_config file at the location where you installed Win32 OpenSSH + - Make sure password authentication is enabled + ```none + PasswordAuthentication yes + ``` + - Add a PowerShell subsystem entry, replace `c:/program files/powershell/6.0.0/pwsh.exe` with the correct path to the version you want to use + ```none + Subsystem powershell c:/program files/powershell/6.0.0/pwsh.exe -sshs -NoLogo -NoProfile + ``` + - Optionally enable key authentication + ```none + PubkeyAuthentication yes + ``` +1. Restart the sshd service + ```powershell + Restart-Service sshd + ``` +1. Add the path where OpenSSH is installed to your Path Env Variable + - This should be along the lines of `C:\Program Files\OpenSSH\` + - This allows for the ssh.exe to be found + +## Setup on Linux (Ubuntu 14.04) Machine + +1. Install the latest [PowerShell for Linux] build from GitHub +1. Install [Ubuntu SSH] as needed + ```bash + sudo apt install openssh-client + sudo apt install openssh-server + ``` +1. Edit the sshd_config file at location /etc/ssh + - Make sure password authentication is enabled + ```none + PasswordAuthentication yes + ``` + - Add a PowerShell subsystem entry + ```none + Subsystem powershell /usr/bin/pwsh -sshs -NoLogo -NoProfile + ``` + - Optionally enable key authentication + ```none + PubkeyAuthentication yes + ``` +1. Restart the sshd service + ```bash + sudo service sshd restart + ``` + +## Setup on MacOS Machine + +1. Install the latest [PowerShell for MacOS] build + - Make sure SSH Remoting is enabled by following these steps: + - Open `System Preferences` + - Click on `Sharing` + - Check `Remote Login` - Should say `Remote Login: On` + - Allow access to appropriate users +1. Edit the `sshd_config` file at location `/private/etc/ssh/sshd_config` + - Use your favorite editor or + ```bash + sudo nano /private/etc/ssh/sshd_config + ``` + - Make sure password authentication is enabled + ```none + PasswordAuthentication yes + ``` + - Add a PowerShell subsystem entry + ```none + Subsystem powershell /usr/local/bin/powershell -sshs -NoLogo -NoProfile + ``` + - Optionally enable key authentication + ```none + PubkeyAuthentication yes + ``` +1. Restart the sshd service + ```bash + sudo launchctl stop com.openssh.sshd + sudo launchctl start com.openssh.sshd + ``` + +## PowerShell Remoting Example + +The easiest way to test remoting is to just try it on a single machine. +Here I will create a remote session back to the same machine on a Linux box. +Notice that I am using PowerShell cmdlets from a command prompt so we see prompts from SSH asking to verify the host computer as well as password prompts. +You can do the same thing on a Windows machine to ensure remoting is working there and then remote between machines by simply changing the host name. + +```powershell +# +# Linux to Linux +# +PS /home/TestUser> $session = New-PSSession -HostName UbuntuVM1 -UserName TestUser +The authenticity of host 'UbuntuVM1 (9.129.17.107)' cannot be established. +ECDSA key fingerprint is SHA256:2kCbnhT2dUE6WCGgVJ8Hyfu1z2wE4lifaJXLO7QJy0Y. +Are you sure you want to continue connecting (yes/no)? +TestUser@UbuntuVM1s password: + +PS /home/TestUser> $session + + Id Name ComputerName ComputerType State ConfigurationName Availability + -- ---- ------------ ------------ ----- ----------------- ------------ + 1 SSH1 UbuntuVM1 RemoteMachine Opened DefaultShell Available + +PS /home/TestUser> Enter-PSSession $session + +[UbuntuVM1]: PS /home/TestUser> uname -a +Linux TestUser-UbuntuVM1 4.2.0-42-generic 49~14.04.1-Ubuntu SMP Wed Jun 29 20:22:11 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux + +[UbuntuVM1]: PS /home/TestUser> Exit-PSSession + +PS /home/TestUser> Invoke-Command $session -ScriptBlock { Get-Process powershell } + +Handles NPM(K) PM(K) WS(K) CPU(s) Id SI ProcessName PSComputerName +------- ------ ----- ----- ------ -- -- ----------- -------------- + 0 0 0 19 3.23 10635 635 powershell UbuntuVM1 + 0 0 0 21 4.92 11033 017 powershell UbuntuVM1 + 0 0 0 20 3.07 11076 076 powershell UbuntuVM1 + + +# +# Linux to Windows +# +PS /home/TestUser> Enter-PSSession -HostName WinVM1 -UserName PTestName +PTestName@WinVM1s password: + +[WinVM1]: PS C:\Users\PTestName\Documents> cmd /c ver + +Microsoft Windows [Version 10.0.10586] + +[WinVM1]: PS C:\Users\PTestName\Documents> + +# +# Windows to Windows +# +C:\Users\PSUser\Documents>pwsh.exe +PowerShell +Copyright (c) Microsoft Corporation. All rights reserved. + +PS C:\Users\PSUser\Documents> $session = New-PSSession -HostName WinVM2 -UserName PSRemoteUser +The authenticity of host 'WinVM2 (10.13.37.3)' can't be established. +ECDSA key fingerprint is SHA256:kSU6slAROyQVMEynVIXAdxSiZpwDBigpAF/TXjjWjmw. +Are you sure you want to continue connecting (yes/no)? +Warning: Permanently added 'WinVM2,10.13.37.3' (ECDSA) to the list of known hosts. +PSRemoteUser@WinVM2's password: +PS C:\Users\PSUser\Documents> $session + + Id Name ComputerName ComputerType State ConfigurationName Availability + -- ---- ------------ ------------ ----- ----------------- ------------ + 1 SSH1 WinVM2 RemoteMachine Opened DefaultShell Available + + +PS C:\Users\PSUser\Documents> Enter-PSSession -Session $session +[WinVM2]: PS C:\Users\PSRemoteUser\Documents> $PSVersionTable + +Name Value +---- ----- +PSEdition Core +PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...} +SerializationVersion 1.1.0.1 +BuildVersion 3.0.0.0 +CLRVersion +PSVersion 6.0.0-alpha +WSManStackVersion 3.0 +PSRemotingProtocolVersion 2.3 +GitCommitId v6.0.0-alpha.17 + + +[WinVM2]: PS C:\Users\PSRemoteUser\Documents> +``` + +### Known Issues + +1. sudo command does not work in remote session to Linux machine. + +[PowerShell for Windows]: https://github.com/PowerShell/PowerShell/blob/master/docs/installation/windows.md#msi +[Win32 OpenSSH]: https://github.com/PowerShell/Win32-OpenSSH +[installation]: https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH +[PowerShell for Linux]: https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#ubuntu-1404 +[Ubuntu SSH]: https://help.ubuntu.com/lts/serverguide/openssh-server.html +[PowerShell for MacOS]: https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#macos-1012 diff --git a/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md b/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md new file mode 100644 index 000000000000..41021451931d --- /dev/null +++ b/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md @@ -0,0 +1,58 @@ +# WS-Management (WSMan) Remoting in PowerShell Core + +## Instructions to Create a Remoting Endpoint + +The PowerShell Core package for Windows includes a WinRM plug-in (`pwrshplugin.dll`) and an installation script (`Install-PowerShellRemoting.ps1`) in `$PSHome`. +These files enable PowerShell to accept incoming PowerShell remote connections when its endpoint is specified. + +### Motivation + +An installation of PowerShell can establish PowerShell sessions to remote computers using `New-PSSession` and `Enter-PSSession`. +To enable it to accept incoming PowerShell remote connections, the user must create a WinRM remoting endpoint. +This is an explicit opt-in scenario where the user runs Install-PowerShellRemoting.ps1 to create the WinRM endpoint. +The installation script is a short-term solution until we add additional functionality to `Enable-PSRemoting` to perform the same action. +For more details, please see issue [#1193](https://github.com/PowerShell/PowerShell/issues/1193). + +### Script Actions + +The script + +1. Creates a directory for the plug-in within %windir%\System32\PowerShell +1. Copies pwrshplugin.dll to that location +1. Generates a configuration file +1. Registers that plug-in with WinRM + +### Registration + +The script must be executed within an Administrator-level PowerShell session and runs in two modes. + +#### Executed by the instance of PowerShell that it will register + +``` powershell +Install-PowerShellRemoting.ps1 +``` + +#### Executed by another instance of PowerShell on behalf of the instance that it will register + +``` powershell +\Install-PowerShellRemoting.ps1 -PowerShellHome "" -PowerShellVersion "" +``` + +For Example: + +``` powershell +C:\Program Files\PowerShell\6.0.0.9\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0.9\" -PowerShellVersion "6.0.0-alpha.9" +``` + +**NOTE:** The remoting registration script will restart WinRM, so all existing PSRP sessions will terminate immediately after the script is run. If run during a remote session, this will terminate the connection. + +## How to Connect to the New Endpoint + +Create a PowerShell session to the new PowerShell endpoint by specifying `-ConfigurationName "some endpoint name"`. To connect to the PowerShell instance from the example above, use either: + +``` powershell +New-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" +Enter-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" +``` + +Note that `New-PSSession` and `Enter-PSSession` invocations that do not specify `-ConfigurationName` will target the default PowerShell endpoint, `microsoft.powershell`. diff --git a/reference/docs-conceptual/core-powershell/vscode/using-vscode.md b/reference/docs-conceptual/core-powershell/vscode/using-vscode.md new file mode 100644 index 000000000000..0979a7139701 --- /dev/null +++ b/reference/docs-conceptual/core-powershell/vscode/using-vscode.md @@ -0,0 +1,191 @@ +# Using Visual Studio Code for PowerShell Development + +In addition to the [PowerShell ISE][ise], +PowerShell is also well-supported in Visual Studio Code. +Furthermore, the ISE is not supported with PowerShell Core, +while Visual Studio Code is supported for PowerShell Core on all platforms (Windows, macOS, and Linux) + +You can use Visual Studio Code on Windows with PowerShell version 5 by using Windows 10 or by installing [Windows Management Framework 5.0 RTM](https://www.microsoft.com/en-us/download/details.aspx?id=50395) for down-level Windows OSs (e.g. Windows 8.1, etc.). + +Before starting it, please make sure PowerShell exists on your system. +For modern workloads on Windows, macOS, and Linux, see: + +- [Installing PowerShell Core on macOS and Linux][install-pscore-linux] +- [Installing PowerShell Core on Windows][install-pscore-windows] + +For traditional Windows PowerShell workloads, see [Installing Windows PowerShell][install-winps]. + +## Editing with Visual Studio Code + +### [1. Installing Visual Studio Code](https://code.visualstudio.com/Docs/setup/setup-overview) + +- **Linux**: follow the installation instructions on the [Running VS Code on Linux](https://code.visualstudio.com/docs/setup/linux) page + +- **macOS**: follow the installation instructions on the [Running VS Code on macOS](https://code.visualstudio.com/docs/setup/mac) page + +> [!IMPORTANT] +> On macOS, you must install OpenSSL for the PowerShell extension to work correctly. +> The easiest way to accomplish this is to install [Homebrew](http://brew.sh/) and then run `brew install openssl`. +> The PowerShell extension will now be able to load successfully. + +- **Windows**: follow the installation instructions on the [Running VS Code on Windows](https://code.visualstudio.com/docs/setup/windows) page + +### 2. Installing PowerShell Extension + +- Launch the Visual Studio Code app by: + - **Windows**: typing `code` in your PowerShell session + - **Linux**: typing `code` in your terminal + - **macOS**: typing `code` in your terminal + +- Launch **Quick Open** by pressing **Ctrl+P** (**Cmd+P** on Mac). +- In Quick Open, type `ext install powershell` and hit **Enter**. +- The **Extensions** view will open on the Side Bar. Select the PowerShell extension from Microsoft. + You will see something like below: + + ![VSCode](./vscode.png) + +- Click the **Install** button on the PowerShell extension from Microsoft. +- After the install, you will see the **Install** button turns to **Reload**. + Click on **Reload**. +- After Visual Studio Code has reload, you are ready for editing. + +For example, to create a new file, click **File->New**. +To save it, click **File->Save** and then provide a file name, let's say `HelloWorld.ps1`. +To close the file, click on "x" next to the file name. +To exit Visual Studio Code, **File->Exit**. + +#### Using a specific installed version of PowerShell + +If you wish to use a specific installation of PowerShell with Visual Studio Code, you will need to add a new variable to your user settings file. + +1. Click **File -> Preferences -> Settings** +1. Two editor panes will appear. + In the right-most pane (`settings.json`), insert the setting below appropriate for your OS somewhere between the two curly brackets (`{` and `}`) and replace ** with the installed PowerShell version: + + ```json + // On Windows: + "powershell.powerShellExePath": "c:/Program Files/PowerShell//pwsh.exe" + + // On Linux: + "powershell.powerShellExePath": "/opt/microsoft/powershell//pwsh" + + // On macOS: + "powershell.powerShellExePath": "/usr/local/microsoft/powershell//pwsh" + ``` +1. Replace the setting with the path to the desired PowerShell executable +1. Save the settings file and restart Visual Studio Code + +#### Configuration settings for Visual Studio Code + +By using the steps in the previous paragraph you can add configuration settings in `settings.json`. + +We recommend the following configuration settings for Visual Studio Code: + +```json +{ + "csharp.suppressDotnetRestoreNotification": true, + "editor.renderWhitespace": "all", + "editor.renderControlCharacters": true, + "omnisharp.projectLoadTimeout": 120, + "files.trimTrailingWhitespace": true +} +``` + +## Debugging with Visual Studio Code + +### No-workspace debugging + +As of Visual Studio Code version 1.9 you can debug PowerShell scripts without having to open the folder containing the PowerShell script. +Simply open the PowerShell script file with **File->Open File...**, set a breakpoint on a line (press F9) and then press F5 to start debugging. +You will see the Debug actions pane appear which allows you to break into the debugger, step, resume and stop debugging. + +### Workspace debugging + +Workspace debugging refers to debugging in the context of a folder that you have opened in Visual Studio Code using **Open Folder...** from the **File** menu. +The folder you open is typically your PowerShell project folder and/or the root of your Git repository. + +Even in this mode, you can start debugging the currently selected PowerShell script by simply pressing F5. +However, workspace debugging allows you to define multiple debug configurations other than just debugging the currently open file. +For instance, you can add a configurations to: + +- Launch Pester tests in the debugger +- Launch a specific file with arguments in the debugger +- Launch an interactive session in the debugger +- Attach the debugger to a PowerShell host process + +Follow these steps to create your debug configuration file: + +1. Open the **Debug** view by pressing **Ctrl+Shift+D** (**Cmd+Shift+D** on Mac). +1. Press the **Configure** gear icon in the toolbar. +1. Visual Studio Code will prompt you to **Select Environment**. + Choose **PowerShell**. + + When you do this, Visual Studio Code creates a directory and a file ".vscode\launch.json" in the root of your workspace folder. + This is where your debug configuration is stored. If your files are in a Git repository, you will typically want to commit the launch.json file. + The contents of the launch.json file are: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Launch (current file)", + "script": "${file}", + "args": [], + "cwd": "${file}" + }, + { + "type": "PowerShell", + "request": "attach", + "name": "PowerShell Attach to Host Process", + "processId": "${command.PickPSHostProcess}", + "runspaceId": 1 + }, + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Interactive Session", + "cwd": "${workspaceRoot}" + } + ] +} +``` + +This represents the common debug scenarios. +However, when you open this file in the editor, you will see an **Add Configuration...** button. +You can press this button to add more PowerShell debug configurations. One handy configuration to add is **PowerShell: Launch Script**. +With this configuration, you can specify a specific file with optional arguments that should be launched whenever you press F5 no matter which file is currently active in the editor. + +Once the debug configuration is established, you can select which configuration you want to use during a debug session by selecting one from the debug configuration drop-down in the **Debug** view's toolbar. + +There are a few blogs that may be helpful to get you started using PowerShell extension for Visual Studio Code + +- Visual Studio Code: [PowerShell Extension][ps-extension] +- [Write and debug PowerShell scripts in Visual Studio Code][debug] +- [Debugging Visual Studio Code Guidance][vscode-guide] +- [Debugging PowerShell in Visual Studio Code][ps-vscode] +- [Get started with PowerShell development in Visual Studio Code][getting-started] +- [Visual Studio Code editing features for PowerShell development – Part 1][editing-part1] +- [Visual Studio Code editing features for PowerShell development – Part 2][editing-part2] +- [Debugging PowerShell script in Visual Studio Code – Part 1][debugging-part1] +- [Debugging PowerShell script in Visual Studio Code – Part 2][debugging-part2] + +[ise]: ../ise-guide.md +[install-pscore-linux]: ../../setup/Installing-PowerShell-Core-on-macOS-and-Linux.md +[install-pscore-windows]: ../../setup/Installing-PowerShell-Core-on-Windows.md +[install-winps]: ../../setup/Installing-Windows-PowerShell.md +[ps-extension]:https://blogs.msdn.microsoft.com/cdndevs/2015/12/11/visual-studio-code-powershell-extension/ +[debug]:https://blogs.msdn.microsoft.com/powershell/2015/11/16/announcing-powershell-language-support-for-visual-studio-code-and-more/ +[vscode-guide]:https://johnpapa.net/debugging-with-visual-studio-code/ +[ps-vscode]:https://github.com/PowerShell/vscode-powershell/tree/master/examples +[getting-started]:https://blogs.technet.microsoft.com/heyscriptingguy/2016/12/05/get-started-with-powershell-development-in-visual-studio-code/ +[editing-part1]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/01/11/visual-studio-code-editing-features-for-powershell-development-part-1/ +[editing-part2]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/01/12/visual-studio-code-editing-features-for-powershell-development-part-2/ +[debugging-part1]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/06/debugging-powershell-script-in-visual-studio-code-part-1/ +[debugging-part2]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/13/debugging-powershell-script-in-visual-studio-code-part-2/ + +## PowerShell Extension for Visual Studio Code + +The PowerShell extension's source code can be found on [GitHub](https://github.com/PowerShell/vscode-powershell). diff --git a/reference/docs-conceptual/core-powershell/vscode/vscode.png b/reference/docs-conceptual/core-powershell/vscode/vscode.png new file mode 100644 index 000000000000..4c9354bd0c90 Binary files /dev/null and b/reference/docs-conceptual/core-powershell/vscode/vscode.png differ diff --git a/reference/docs-conceptual/images/modern-lifecycle.png b/reference/docs-conceptual/images/modern-lifecycle.png new file mode 100644 index 000000000000..b9283dc6a651 Binary files /dev/null and b/reference/docs-conceptual/images/modern-lifecycle.png differ diff --git a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md new file mode 100644 index 000000000000..4d7eb338bd86 --- /dev/null +++ b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md @@ -0,0 +1,106 @@ +# Installing PowerShell Core on Windows + +## MSI + +To install PowerShell on a Windows client or Windows Server (works on Windows 7 SP1, Server 2008 R2, and later), download the MSI package from + +our GitHub [releases][] page. +The MSI file looks like this - `PowerShell-6.0.0...msi` + +Once downloaded, double-click the installer and follow the prompts. + +There is a shortcut placed in the Start Menu upon installation. + +* By default the package is installed to `$env:ProgramFiles\PowerShell\` +* You can launch PowerShell via the Start Menu or `$env:ProgramFiles\PowerShell\pwsh.exe` + +### Prerequisites + +To enable PowerShell remoting over WSMan, the following prerequisites need to be met: + +* Install the [Universal C Runtime](https://www.microsoft.com/download/details.aspx?id=50410) on Windows versions prior to Windows 10. + It is available via direct download or Windows Update. + Fully patched (including optional packages), supported systems will already have this installed. +* Install the Windows Management Framework (WMF) [4.0](https://www.microsoft.com/download/details.aspx?id=40855) + or newer ([5.1](https://www.microsoft.com/download/details.aspx?id=54616)) on Windows 7 and Windows Server 2008 R2. + +## ZIP + +PowerShell binary ZIP archives are provided to enable advanced deployment scenarios. +Be noted that when using the ZIP archive, you won't get the prerequisites check as in the MSI package. +So in order for remoting over WSMan to work properly on Windows versions prior to Windows 10, +you need to make sure the [prerequisites](#prerequisites) are met. + +## Deploying on Nano Server + +These instructions assume that a version of PowerShell is already running on the Nano Server image and that it has been generated by the [Nano Server Image Builder](https://technet.microsoft.com/windows-server-docs/get-started/deploy-nano-server). +Nano Server is a "headless" OS and deployment of PowerShell Core binaries can happen in two different ways: + +1. Offline - Mount the Nano Server VHD and unzip the contents of the zip file to your chosen location within the mounted image. +1. Online - Transfer the zip file over a PowerShell Session and unzip it in your chosen location. + +In both cases, you will need the Windows 10 x64 Zip release package and will need to run the commands within an "Administrator" PowerShell instance. + +### Offline Deployment of PowerShell Core + +1. Use your favorite zip utility to unzip the package to a directory within the mounted Nano Server image. +1. Unmount the image and boot it. +1. Connect to the inbox instance of Windows PowerShell. +1. Follow the instructions to create a remoting endpoint using the [another instance technique](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). + +### Online Deployment of PowerShell Core + +The following steps will guide you through the deployment of PowerShell Core to a running instance of Nano Server and the configuration of its remote endpoint. + +* Connect to the inbox instance of Windows PowerShell + +```powershell +$session = New-PSSession -ComputerName -Credential +``` + +* Copy the file to the Nano Server instance + +```powershell +Copy-Item \powershell--win-x64.zip c:\ -ToSession $session +``` + +* Enter the session + +```powershell +Enter-PSSession $session +``` + +* Extract the Zip file + +```powershell +# Insert the appropriate version. +Expand-Archive -Path C:\powershell--win-x64.zip -DestinationPath "C:\PowerShellCore_" +``` + +* If you want WSMan-based remoting, follow the instructions to create a remoting endpoint using the [another instance technique](../core-powershell/WSMan-Remoting-in-PowerShell-Core.md#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). + +## Instructions to Create a Remoting Endpoint + +PowerShell Core supports the PowerShell Remoting Protocol (PSRP) over both WSMan and SSH. For more information, see: + +* [SSH Remoting in PowerShell Core][ssh-remoting] +* [WSMan Remoting in PowerShell Core][wsman-remoting] + +## Artifact Installation Instructions + +We publish an archive with CoreCLR bits on every CI build with [AppVeyor][]. + +## CoreCLR Artifacts + +* Download zip package from **artifacts** tab of the particular build. +* Unblock zip file: right-click in File Explorer -> Properties -> + check 'Unblock' box -> apply +* Extract zip file to `bin` directory +* `./bin/pwsh.exe` + + +[releases]: https://github.com/PowerShell/PowerShell/releases +[signing]: ../../tools/Sign-Package.ps1 +[ssh-remoting]: ../core-powershell/SSH-Remoting-in-PowerShell-Core.md +[wsman-remoting]: ../core-powershell/WSMan-Remoting-in-PowerShell-Core.md +[AppVeyor]: https://ci.appveyor.com/project/PowerShell/powershell diff --git a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md new file mode 100644 index 000000000000..a3e31810d9ea --- /dev/null +++ b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md @@ -0,0 +1,808 @@ +# Package installation instructions + +Supports [Ubuntu 14.04][u14], [Ubuntu 16.04][u16], [Ubuntu 17.04][u17], [Debian 8][deb8], [Debian 9][deb9], +[CentOS 7][cos], [Red Hat Enterprise Linux (RHEL) 7][rhel7], [OpenSUSE 42.2][opensuse], [Fedora 25][fed25], +[Fedora 26][fed26], [Arch Linux][arch], and [macOS 10.12][mac]. + +For Linux distributions that are not officially supported, +you can try using the [PowerShell AppImage][lai]. +You can also try deploying PowerShell binaries directly using the Linux [`tar.gz` archive][tar], +but you would need to set up the necessary dependencies based on the OS in separate steps. + +All packages are available on our GitHub [releases][] page. +Once the package is installed, run `pwsh` from a terminal. + +[u14]: #ubuntu-1404 +[u16]: #ubuntu-1604 +[u17]: #ubuntu-1704 +[deb8]: #debian-8 +[deb9]: #debian-9 +[cos]: #centos-7 +[rhel7]: #red-hat-enterprise-linux-rhel-7 +[opensuse]: #opensuse-422 +[fed25]: #fedora-25 +[fed26]: #fedora-26 +[arch]: #arch-linux +[lai]: #linux-appimage +[mac]: #macos-1012 +[tar]: #binary-archives + +## Ubuntu 14.04 + +### Installation via Package Repository - Ubuntu 14.04 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Ubuntu repository +curl https://packages.microsoft.com/config/ubuntu/14.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Ubuntu 14.04 + +Download the Debian package +`powershell_6.0.0-rc-1.ubuntu.14.04_amd64.deb` +from the [releases][] page onto the Ubuntu machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.ubuntu.14.04_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Ubuntu 14.04 + +```sh +sudo apt-get remove powershell +``` + +## Ubuntu 16.04 + +### Installation via Package Repository - Ubuntu 16.04 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Ubuntu repository +curl https://packages.microsoft.com/config/ubuntu/16.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Ubuntu 16.04 + +Download the Debian package +`powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb` +from the [releases][] page onto the Ubuntu machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Ubuntu 16.04 + +```sh +sudo apt-get remove powershell +``` + +## Ubuntu 17.04 + +### Installation via Package Repository - Ubuntu 17.04 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Ubuntu repository +curl https://packages.microsoft.com/config/ubuntu/17.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Ubuntu 17.04 + +Download the Debian package +`powershell_6.0.0-rc-1.ubuntu.17.04_amd64.deb` +from the [releases][] page onto the Ubuntu machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.ubuntu.17.04_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Ubuntu 17.04 + +```sh +sudo apt-get remove powershell +``` + +## Debian 8 + +### Installation via Package Repository - Debian 8 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Install system components +sudo apt-get update +sudo apt-get install curl apt-transport-https + +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Product feed +sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-debian-jessie-prod jessie main" > /etc/apt/sources.list.d/microsoft.list' + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Debian 8 + +Download the Debian package +`powershell_6.0.0-rc-1.debian.8_amd64.deb` +from the [releases][] page onto the Debian machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.debian.8_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Debian 8 + +```sh +sudo apt-get remove powershell +``` + +## Debian 9 + +### Installation via Package Repository - Debian 9 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Install system components +sudo apt-get update +sudo apt-get install curl gnupg apt-transport-https + +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Product feed +sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-debian-stretch-prod stretch main" > /etc/apt/sources.list.d/microsoft.list' + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Debian 9 + +Download the Debian package +`powershell_6.0.0-rc-1.debian.9_amd64.deb` +from the [releases][] page onto the Debian machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.debian.9_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Debian 9 + +```sh +sudo apt-get remove powershell +``` + +## CentOS 7 + +> This package also works on Oracle Linux 7. + +### Installation via Package Repository (preferred) - CentOS 7 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Install PowerShell +sudo yum install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +you just need to use `sudo yum update powershell` to update PowerShell. + +### Installation via Direct Download - CentOS 7 + +Using [CentOS 7][], download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the CentOS machine. + +Then execute the following in the terminal: + +```sh +sudo yum install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - CentOS 7 + +```sh +sudo yum remove powershell +``` + +[CentOS 7]: https://www.centos.org/download/ + +## Red Hat Enterprise Linux (RHEL) 7 + +### Installation via Package Repository (preferred) - Red Hat Enterprise Linux (RHEL) 7 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Install PowerShell +sudo yum install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +you just need to use `sudo yum update powershell` to update PowerShell. + +### Installation via Direct Download - Red Hat Enterprise Linux (RHEL) 7 + +Download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the Red Hat Enterprise Linux machine. + +Then execute the following in the terminal: + +```sh +sudo yum install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - Red Hat Enterprise Linux (RHEL) 7 + +```sh +sudo yum remove powershell +``` + +## OpenSUSE 42.2 + +> **Note:** When installing PowerShell Core, OpenSUSE may report that nothing provides `libcurl`. +`libcurl` should already be installed on supported versions of OpenSUSE. +Run `zypper search libcurl` to confirm. +The error will present 2 'solutions'. Choose 'Solution 2' to continue installing PowerShell Core. + +### Installation via Package Repository (preferred) - OpenSUSE 42.2 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft signature key +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc + +# Add the Microsoft Product feed +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/zypp/repos.d/microsoft.repo + +# Update the list of products +sudo zypper update + +# Install PowerShell +sudo zypper install powershell + +# Start PowerShell +pwsh +``` + +### Installation via Direct Download - OpenSUSE 42.2 + +Download the RPM package `powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the OpenSUSE machine. + +```sh +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc +sudo zypper install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc +sudo zypper install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - OpenSUSE 42.2 + +```sh +sudo zypper remove powershell +``` + +## Fedora 25 + +### Installation via Package Repository (preferred) - Fedora 25 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft signature key +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc + +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Update the list of products +sudo dnf update + +# Install PowerShell +sudo dnf install -y powershell + +# Start PowerShell +pwsh +``` + +### Installation via Direct Download - Fedora 25 + +Download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the Fedora machine. + +Then execute the following in the terminal: + +```sh +sudo dnf install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - Fedora 25 + +```sh +sudo dnf remove powershell +``` + +## Fedora 26 + +### Installation via Package Repository (preferred) - Fedora 26 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft signature key +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc + +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Update the list of products +sudo dnf update + +# Install a system component +sudo dnf install compat-openssl10 + +# Install PowerShell +sudo dnf install -y powershell + +# Start PowerShell +pwsh +``` + +### Installation via Direct Download - Fedora 26 + +Download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the Fedora machine. + +Then execute the following in the terminal: + +```sh +sudo dnf update +sudo dnf install compat-openssl10 +sudo dnf install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo dnf update +sudo dnf install compat-openssl10 +sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - Fedora 26 + +```sh +sudo dnf remove powershell +``` + +## Arch Linux + +PowerShell is available from the [Arch Linux][] User Repository (AUR). + +* It can be compiled with the [latest tagged release][arch-release] +* It can be compiled from the [latest commit to master][arch-git] +* It can be installed using the [latest release binary][arch-bin] + +Packages in the AUR are community maintained - there is no official support. + +For more information on installing packages from the AUR, see the [Arch Linux wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages) or the community [DockerFile](https://github.com/PowerShell/PowerShell/blob/master/docker/community/archlinux/Dockerfile). + +[Arch Linux]: https://www.archlinux.org/download/ +[arch-release]: https://aur.archlinux.org/packages/powershell/ +[arch-git]: https://aur.archlinux.org/packages/powershell-git/ +[arch-bin]: https://aur.archlinux.org/packages/powershell-bin/ + +## Linux AppImage + +Using a recent Linux distribution, +download the AppImage `powershell-6.0.0-rc-x86_64.AppImage` +from the [releases][] page onto the Linux machine. + +Then execute the following in the terminal: + +```bash +chmod a+x powershell-6.0.0-rc-x86_64.AppImage +./powershell-6.0.0-rc-x86_64.AppImage +``` + +The [AppImage][] lets you run PowerShell without installing it. +It is a portable application that bundles PowerShell and its dependencies +(including .NET Core's system dependencies) into one cohesive package. +This package works independently of the user's Linux distribution, +and is a single binary. + +[appimage]: http://appimage.org/ + +## macOS 10.12 + +### Installation via Homebrew (preferred) - macOS 10.12 + +[Homebrew][brew] is the missing package manager for macOS. +If the `brew` command is not found, +you need to install Homebrew following [their instructions][brew]. + +Once you've installed Homebrew, installing PowerShell is easy. +First, install [Homebrew-Cask][cask], so you can install more packages: + +```sh +brew tap caskroom/cask +``` + +Now, you can install PowerShell: + +```sh +brew cask install powershell +``` + +When new versions of PowerShell are released, +simply update Homebrew's formulae and upgrade PowerShell: + +```sh +brew update +brew cask reinstall powershell +``` + +> Note: because of [this issue in Cask](https://github.com/caskroom/homebrew-cask/issues/29301), you currently have to do a reinstall to upgrade. + +[brew]: http://brew.sh/ +[cask]: https://caskroom.github.io/ + +### Installation via Direct Download - macOS 10.12 + +Using macOS 10.12, download the PKG package +`powershell-6.0.0-rc-osx.10.12-x64.pkg` +from the [releases][] page onto the macOS machine. + +Either double-click the file and follow the prompts, +or install it from the terminal: + +```sh +sudo installer -pkg powershell-6.0.0-rc-osx.10.12-x64.pkg -target / +``` + +### Uninstallation - macOS 10.12 + +If you installed PowerShell with Homebrew, uninstallation is easy: + +```sh +brew cask uninstall powershell +``` + +If you installed PowerShell via direct download, +PowerShell must be removed manually: + +```sh +sudo rm -rf /usr/local/bin/pwsh /usr/local/microsoft/powershell +``` + +To uninstall the additional PowerShell paths (such as the user profile path) +please see the [paths][paths] section below in this document +and remove the desired the paths with `sudo rm`. +(Note: this is not necessary if you installed with Homebrew.) + +[paths]:#paths + +## Kali + +### Installation + +```sh +# Install prerequisites +apt-get install libunwind8 libicu55 +wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.0.0_1.0.1t-1+deb8u6_amd64.deb +dpkg -i libssl1.0.0_1.0.1t-1+deb8u6_amd64.deb + +# Install PowerShell +dpkg -i powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb + +# Start PowerShell +pwsh +``` + +### Run PowerShell in latest Kali (Kali GNU/Linux Rolling) without installing it + +```sh +# Grab the latest App Image +wget https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-x86_64.AppImage + +# Make executable +chmod a+x powershell-6.0.0-rc-x86_64.AppImage + +# Start PowerShell +./powershell-6.0.0-rc-x86_64.AppImage +``` + +### Uninstallation - Kali + +```sh +dpkg -r powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb +``` + +## Raspbian + +Currently, PowerShell is only supported on Raspbian Stretch. + +### Installation + +```sh +# Install prerequisites +sudo apt-get install libunwind8 + +# Grab the latest tar.gz +wget https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-linux-arm32.tar.gz + +# Make folder to put powershell +mkdir ~/powershell + +# Unpack the tar.gz file +tar -xvf ./powershell-6.0.0-rc-linux-arm32.tar.gz -C ~/powershell + +# Start PowerShell +~/powershell/pwsh +``` + +### Uninstallation - Raspbian + +```sh +rm -rf ~/powershell +``` + +## Binary Archives + +PowerShell binary `tar.gz` archives are provided for macOS and Linux platforms to enable advanced deployment scenarios. + +### Dependencies + +For Linux, PowerShell builds portable binaries for all Linux distributions. +But .NET Core runtime requires different dependencies on different distributions, +and hence PowerShell does the same. + +The following chart shows the .NET Core 2.0 dependencies on different Linux distributions that are officially supported. + +| OS | Dependencies | +| ------------------ | ------------ | +| Ubuntu 14.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu52 | +| Ubuntu 16.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu55 | +| Ubuntu 17.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu57 | +| Debian 8 (Jessie) | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu52 | +| Debian 9 (Stretch) | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.2, libicu57 | +| CentOS 7
Oracle Linux 7
RHEL 7
OpenSUSE 42.2
Fedora 25 | libunwind, libcurl, openssl-libs, libicu | +| Fedora 26 | libunwind, libcurl, openssl-libs, libicu, compat-openssl10 | + +In order to deploy PowerShell binaries on Linux distributions that are not officially supported, +you would need to install the necessary dependencies for the target OS in separate steps. +For example, our [Amazon Linux dockerfile][amazon-dockerfile] installs dependencies first, +and then extracts the Linux `tar.gz` archive. + +[amazon-dockerfile]: https://github.com/PowerShell/PowerShell/blob/master/docker/community/amazonlinux/Dockerfile + +### Installation - Binary Archives + +#### Linux + +```sh +# Download the powershell '.tar.gz' archive +curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-linux-x64.tar.gz + +# Create the target folder where powershell will be placed +sudo mkdir -p /opt/microsoft/powershell/6.0.0-rc + +# Expand powershell to the target folder +sudo tar zxf /tmp/powershell.tar.gz -C /opt/microsoft/powershell/6.0.0-rc + +# Set execute permissions +sudo chmod +x /usr/local/microsoft/powershell/6.0.0-rc/pwsh + +# Create the symbolic link that points to pwsh +sudo ln -s /opt/microsoft/powershell/6.0.0-rc/pwsh /usr/bin/pwsh +``` + +#### macOS + +```sh +# Download the powershell '.tar.gz' archive +curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-osx-x64.tar.gz + +# Create the target folder where powershell will be placed +sudo mkdir -p /usr/local/microsoft/powershell/6.0.0-rc + +# Expand powershell to the target folder +sudo tar zxf /tmp/powershell.tar.gz -C /usr/local/microsoft/powershell/6.0.0-rc + +# Set execute permissions +sudo chmod +x /usr/local/microsoft/powershell/6.0.0-rc/pwsh + +# Create the symbolic link that points to pwsh +sudo ln -s /usr/local/microsoft/powershell/6.0.0-rc/pwsh /usr/local/bin/pwsh +``` + +### Uninstallation - Binary Archives + +#### Linux + +```sh +sudo rm -rf /usr/bin/pwsh /opt/microsoft/powershell +``` + +#### macOS + +```sh +sudo rm -rf /usr/local/bin/pwsh /usr/local/microsoft/powershell +``` + +## Paths + +* `$PSHOME` is `/opt/microsoft/powershell/6.0.0-rc/` +* User profiles will be read from `~/.config/powershell/profile.ps1` +* Default profiles will be read from `$PSHOME/profile.ps1` +* User modules will be read from `~/.local/share/powershell/Modules` +* Shared modules will be read from `/usr/local/share/powershell/Modules` +* Default modules will be read from `$PSHOME/Modules` +* PSReadline history will be recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` + +The profiles respect PowerShell's per-host configuration, +so the default host-specific profiles exists at `Microsoft.PowerShell_profile.ps1` in the same locations. + +On Linux and macOS, the [XDG Base Directory Specification][xdg-bds] is respected. + +Note that because macOS is a derivation of BSD, +instead of `/opt`, the prefix used is `/usr/local`. +Thus, `$PSHOME` is `/usr/local/microsoft/powershell/6.0.0-rc/`, +and the symlink is placed at `/usr/local/bin/pwsh`. + +[releases]: https://github.com/PowerShell/PowerShell/releases/latest +[xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html diff --git a/reference/docs-conceptual/setup/setup-reference.md b/reference/docs-conceptual/setup/setup-reference.md index 959d7ee4842f..aeb967904927 100644 --- a/reference/docs-conceptual/setup/setup-reference.md +++ b/reference/docs-conceptual/setup/setup-reference.md @@ -6,6 +6,8 @@ title: setup reference # Setup Guide +- [Installing PowerShell Core on macOS and Linux](Installing-PowerShell-Core-on-macOS-and-Linux.md) +- [Installing PowerShell Core on Windows](Installing-PowerShell-Core-on-Windows.md) - [Installing Windows PowerShell](Installing-Windows-PowerShell.md) - [Installing the Windows PowerShell 2.0 Engine](Installing-the-Windows-PowerShell-2.0-Engine.md) - [Installing the Windows PowerShell SDK](Installing-the-Windows-PowerShell-SDK.md) @@ -17,4 +19,3 @@ title: setup reference - [Starting Windows PowerShell](Starting-Windows-PowerShell.md) - [Windows PowerShell System Requirements](Windows-PowerShell-System-Requirements.md) - [WinRMSecurity](WinRMSecurity.md) - diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 87255ba592b2..a221257a4bd2 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -240,5 +240,7 @@ href: whats-new/what-s-new-in-windows-powershell-50.md - name: What's New With PowerShell href: whats-new/what-s-new-with-powershell.md + - name: PowerShell Core Support Lifecycle + href: PowerShell-Core-Support.md - name: Glossary href: windows-powershell-glossary.md diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md new file mode 100644 index 000000000000..81b2d64ff4da --- /dev/null +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md @@ -0,0 +1,403 @@ +# What's New in PowerShell Core 6.0 + +[PowerShell Core 6.0][github] is a new edition of PowerShell that is cross-platform (Windows, macOS, and Linux), open-source, and built for heterogeneous environments and the hybrid cloud. + +## Moved from .NET Framework to .NET Core + +PowerShell Core uses [.NET Core 2.0][] as its runtime. +.NET Core 2.0 enables PowerShell Core to work on multiple platforms (Windows, macOS, and Linux). +PowerShell Core also exposes the API set offered by .NET Core 2.0 to be used in PowerShell cmdlets and scripts. + +Windows PowerShell used the .NET Framework runtime to host the PowerShell engine. +This means that Windows PowerShell exposes the API set offered by .NET Framework. + +The APIs shared between .NET Core and .NET Framework are defined as part of [.NET Standard][]. + +For more information on how this affects module/script compatibility between PowerShell Core and Windows PowerShell, +see [Backwards compatibility with Windows PowerShell][#backwards-compatibility-with-windows-powershell] + +## Support for macOS and Linux + +PowerShell now officially supports macOS and Linux, including: + +- Windows 7, 8.1, and 10 +- Windows Server 2008 R2, 2012 R2, 2016 +- [Windows Server Semi-Annual Channel][semi-annual] +- Ubuntu 14.04, 16.04, and 17.04 +- Debian 8.7+, and 9 +- CentOS 7 +- Red Hat Enterprise Linux 7 +- OpenSUSE 42.2 +- Fedora 25, 26 +- macOS 10.12+ + +Our community has also contributed packages for the following platforms, +but they are not officially supported: + +- Arch Linux +- Kali Linux +- AppImage (works on multiple Linux platforms) + +We also have experimental (unsupported) releases for the following platforms: + +- Windows on ARM32/ARM64 +- Raspbian (Stretch) + +A number of changes were made to in PowerShell Core 6.0 to make it work better on non-Windows systems. +Some of these are breaking changes, which also affect Windows. +Others are only present or applicable in non-Windows installations of PowerShell Core. + +- Added support for native command globbing on Unix platforms. +- The `more` functionality respects the Linux `$PAGER` and defaults to `less`. + This means you can now use wildcards with native binaries/commands (for example, `ls *.txt`). (#3463) +- Trailing backslash is automatically escaped when dealing with native command arguments. (#4965) +- Ignore the `-ExecutionPolicy` switch when running PowerShell on non-Windows platforms because script signing is not currently supported. (#3481) +- Fixed ConsoleHost to honor `NoEcho` on Unix platforms. (#3801) +- Fixed `Get-Help` to support case insensitive pattern matching on Unix platforms. (#3852) +- `powershell` man-page added to package + +### Logging + +On macOS, PowerShell uses the native `os_log` APIs to log to Apple's [unified logging system][os_log]. +On Linux, PowerShell uses [Syslog][], a ubiquitous logging solution. + +### Filesystem + +A number of changes have been made on macOS and Linux to support filename characters not traditionally supported on Windows: + +- Paths given to cmdlets are now slash-agnostic (both / and \ work as directory separator) +- XDG Base Directory Specification is now respected and used by default: + - The Linux/macOS profile path is located at `~/.config/powershell/profile.ps1` + - The history save path is located at `~/.local/share/powershell/PSReadline/ConsoleHost_history.txt` + - The user module path is located at `~/.local/share/powershell/Modules` +- Support for file and folder names containing the colon character on Unix. (#4959) +- Support for script names or full paths that have commas. (#4136) (Thanks to @TimCurwick!) +- Detect when `-LiteralPath` is used to suppress wildcard expansion for navigation cmdlets. (#5038) +- Updated `Get-ChildItem` to work more like the *nix `ls -R` and the Windows `DIR /S` native commands. + `Get-ChildItem` now returns the symbolic links encountered during a recursive search and does not search the directories that those links target. (#3780) + +### Case sensitivity + +Linux and macOS tend to be case-sensitive while Windows is case-insensitive while preserving case. +In general, PowerShell is case insensitive. + +For example, environment variables are case-sensitive on macOS and Linux, +so the casing of the `PSModulePath` environment variable has been standardized. (#3255) +`Import-Module` is case insensitive when it's using a file path to determine the module's name. (#5097) + +## Support for side-by-side installations + +PowerShell Core is installed, configured, and executed separately from Windows PowerShell. +PowerShell Core has a "portable" ZIP package. +Using the ZIP package, you can install any number of versions anywhere on disk, including local to an application that takes PowerShell as a dependency. +Side-by-side installation makes it easier to test new versions of PowerShell and migrating existing scripts over time. +Side-by-side also enables backwards compatibility as scripts can be pinned to specific versions that they require. + +> [!NOTE] +> By default, the MSI-based installer on Windows does an in-place update install. +> + +## Renamed `powershell(.exe)` to `pwsh(.exe)` + +The binary name for PowerShell Core has been changed from `powershell(.exe)` to `pwsh(.exe)`. +This change provides a deterministic way for users to run PowerShell Core on machines to support side-by-side Windows PowerShell and PowerShell Core installations. +`pwsh` is also much shorter and easier to type. + +Additional changes to `pwsh(.exe)` from `powershell.exe`: + +- Changed the first positional parameter from `-Command` to `-File`. + This change fixes the usage of `#!` (aka as a shebang) in PowerShell scripts that are being executed from non-PowerShell shells on non-Windows platforms. + It also means that you can run commands like `pwsh foo.ps1` or `pwsh fooScript` without specifying `-File`. + However, this change requires that you explicitly specify `-c` or `-Command` when trying to run commands like `pwsh.exe -Command Get-Command`. (#4019) +- PowerShell Core accepts the `-i` (or `-Interactive`) switch to indicate an interactive shell. (#3558) + This allows PowerShell to be used as a default shell on Unix platforms. +- Removed parameters `-importsystemmodules` and `-psconsoleFile` from `pwsh.exe`. (#4995) +- Changed `pwsh -version` and built-in help for `pwsh.exe` to align with other native tools. (#4958 & #4931) (Thanks @iSazonov) +- Invalid argument error messages for `-File` and `-Command` and exit codes consistent with Unix standards (#4573) +- Added `-WindowStyle` parameter on Windows. (#4573) + Similarly, package-based installations updates on non-Windows platforms are in-place updates. + +## Backwards compatibility with Windows PowerShell + +The goal of PowerShell Core is to remain as compatible as possible with Windows PowerShell. +PowerShell Core uses [.NET Standard][] 2.0 to provide binary compatibility with existing .NET assemblies. +Many PowerShell modules depend on these assemblies (often times DLLs), so .NET Standard allows them to continue working with .NET Core. +PowerShell Core also includes a heuristic to look in well-known folders--like where the Global Assembly Cache typically resides on disk--to find .NET Framework DLL dependencies. + +You can learn more about .NET Standard on the [.NET Blog][], in this [YouTube][] video, and via this [FAQ][] on GitHub. + +Best efforts have been made to ensure that the PowerShell language and "built-in" modules (like `Microsoft.PowerShell.Management`, `Microsoft.PowerShell.Utility`, etc.) work the same as they do in Windows PowerShell. +In many cases, with the help of the community, we've added new capabilities and bug fixes to those cmdlets. +In some cases, due to a missing dependency in underlying .NET layers, functionality was removed or is unavailable. + +Most of the modules that ship as part of Windows (for example, `DnsClient`, `Hyper-V`, `NetTCPIP`, `Storage`, etc.) and other Microsoft products including Azure and Office have not been *explicitly* ported to .NET Core yet. +The PowerShell team is working with these product groups and teams to validate and port their existing modules to PowerShell Core. +With .NET Standard and [CDXML][], many of these traditional Windows PowerShell modules do seem to work in PowerShell Core, +but they have not been formally validated, and they are not formally supported. + +By installing the [`WindowsPSModulePath`][windowspsmodulepath] module, +you can use Windows PowerShell modules by appending the Windows PowerShell `PSModulePath` to your PowerShell Core `PSModulePath`. + +First, install the `WindowsPSModulePath` module from the PowerShell Gallery: + +```powershell +# Add `-Scope CurrentUser` if you're installing as non-admin +Install-Module WindowsPSModulePath -Force +``` + +After installing this module, +run the `Add-WindowsPSModulePath` cmdlet to add the Windows PowerShell `PSModulePath` to PowerShell Core: + +```powershell +# Add this line to your profile if you always want Windows PowerShell PSModulePath +Add-WindowsPSModulePath +``` + +## Docker support + +PowerShell Core adds support for Docker containers for all the major platforms we support +(including multiple Linux distros, Windows Server Core, and Nano Server). + +For a complete list, check out the tags on [`microsoft/powershell` on Docker Hub][docker-hub]. +For more information on Docker and PowerShell Core, see [Docker][] on GitHub. + +## SSH-based PowerShell Remoting + +The PowerShell Remoting Protocol (PSRP) now works with the Secure Shell (SSH) protocol in addition to the traditional WinRM-based PSRP. + +This means that you can use cmdlets like `Enter-PSSession` and `New-PSSession` and authenticate using SSH. +All you have to do is register PowerShell as a subsystem with an OpenSSH-based SSH server, +and you can use your existing SSH-based authenticate mechanisms (like passwords or private keys) with the traditional `PSSession` semantics. + +For more information on configuring and using SSH-based remoting, +see [PowerShell Remoting over SSH][ssh-remoting]. + +## Default encoding is UTF-8 without a BOM + +In the past, Windows PowerShell cmdlets like `Get-Content`, `Set-Content` used different encodings, such as ASCII and UTF-16. +The variance in encoding defaults created problems when mixing cmdlets without specifying an encoding. + +Non-Windows platforms traditionally use UTF-8 without a Byte Order Mark (BOM) as the default encoding for text files. +More Windows applications and tools are moving away from UTF-16 and towards BOM-less UTF-8 encoding. +PowerShell Core changes the default encoding to conform with the broader ecosystems. + +This means that all built-in cmdlets that use the `-Encoding` parameter use the `UTF8NoBOM` value by default. +The following cmdlets are affected by this change: + +- Add-Content +- Export-Clixml +- Export-Csv +- Export-PSSession +- Format-Hex +- Get-Content +- Import-Csv +- New-ModuleManifest +- Out-File +- Select-String +- Send-MailMessage +- Set-Content + +These cmdlets have also been updated so that the `-Encoding` parameter universally accepts `System.Text.Encoding`. + +The default value of `$OutputEncoding` has also been changed to UTF-8. + +As a best practice, you should explicitly set encodings in scripts using the `-Encoding` parameter to produce deterministic behavior across platforms. + +## Support backgrounding of pipelines with ampersand (`&`) (#3360) + +Putting `&` at the end of a pipeline causes the pipeline to be run as a PowerShell job. +When a pipeline is backgrounded, a job object is returned. +Once the pipeline is running as a job, all of the standard `*-Job` cmdlets can be used to manage the job. +Variables (ignoring process-specific variables) used in the pipeline are automatically copied to the job so `Copy-Item $foo $bar &` just works. +The job is also run in the current directory instead of the user's home directory. +For more information about PowerShell jobs, see [about_Jobs](https://msdn.microsoft.com/powershell/reference/6/about/about_jobs). + +## Semantic versioning + +- Made `SemanticVersion` compatible with `SemVer 2.0`. (#5037) (Thanks @iSazonov!) +- Changed default `ModuleVersion` in `New-ModuleManifest` to `0.0.1` to align with SemVer. (#4842) (Thanks @LDSpits) +- Added `semver` as a type accelerator for `System.Management.Automation.SemanticVersion`. (#4142) (Thanks to @oising!) +- Enabled comparison between a `SemanticVersion` instance and a `Version` instance that is constructed only with `Major` and `Minor` version values. + +## Language updates + +- Implement Unicode escape parsing so that users can use Unicode characters as arguments, strings, or variable names. (#3958) (Thanks to @rkeithhill!) +- Added new escape character for ESC: `` `e`` +- Added support for converting enums to string (#4318) (Thanks @KirkMunro) +- Fixed casting single element array to a generic collection. (#3170) +- Added character range overload to the `..` operator, so `'a'..'z'` returns characters from 'a' to 'z'. (#5026) (Thanks @IISResetMe!) +- Fixed variable assignment to not overwrite read-only variables +- Push locals of automatic variables to 'DottedScopes' when dotting script cmdlets (#4709) +- Enable use of 'Singleline, Multiline' option in split operator (#4721) (Thanks @iSazonov) + +## Engine updates + +- `$PSVersionTable` has four new properties: + - `PSEdition`: This is set to `Core` on PowerShell Core and `Desktop` on Windows PowerShell + - `GitCommitId`: This is the Git commit ID of the Git branch or tag where PowerShell was built. + On released builds, it will likely be the same as `PSVersion`. + - `OS`: This is an OS version string returned by `[System.Environment]::OSVersion.VersionString` + - `Platform`: This is returned by `[System.Environment]::OSVersion.Platform` + It is set to `Win32NT` on Windows, `MacOSX` on macOS, and `Unix` on Linux. +- Removed the `BuildVersion` property from `$PSVersionTable`. + This property was strongly tied to the Windows build version. + Instead, we recommend that you use `GitCommitId` to retrieve the exact build version of PowerShell Core. (#3877) (Thanks to @iSazonov!) +- Remove `ClrVersion` property from `$PSVersionTable`. + This property is irrelevant for .NET Core, and was only preserved in .NET Core for specific legacy purposes that are inapplicable to PowerShell. +- Added three new automatic variables to determine whether PowerShell is running in a given OS: + `$IsWindows`, `$IsMacOs`, and `$IsLinux`. +- Add `GitCommitId` to PowerShell Core banner. + Now you don't have to run `$PSVersionTable` as soon as you start PowerShell to get the version! (#3916) (Thanks to @iSazonov!) +- Add a JSON config file called `PowerShellProperties.json` in `$PSHome` to store some settings required before startup time (e.g. `ExecutionPolicy`). +- Don't block pipeline when running Windows EXE's +- Enabled enumeration of COM collections. (#4553) + +## Cmdlet updates + +### New cmdlets + +- Add `Get-Uptime` to `Microsoft.PowerShell.Utility`. +- Add `Remove-Alias` Command. (#5143) (Thanks @PowershellNinja!) +- Add `Remove-Service` to Management module. (#4858) (Thanks @joandrsn!) + +### Web cmdlets + +- Add certificate authentication support for web cmdlets. (#4646) (Thanks @markekraus) +- Add support for content headers to web cmdlets. (#4494 & #4640) (Thanks @markekraus) +- Add multiple link header support to Web Cmdlets. (#5265) (Thanks @markekraus!) +- Support Link header pagination in web cmdlets (#3828) + - For `Invoke-WebRequest`, when the response includes a Link header we create a RelationLink property as a Dictionary representing the URLs and `rel` attributes and ensure the URLs are absolute to make it easier for the developer to use. + - For `Invoke-RestMethod`, when the response includes a Link header we expose a `-FollowRelLink` switch to automatically follow `next` `rel` links until they no longer exist or once we hit the optional `-MaximumFollowRelLink` parameter value. +- Add `-CustomMethod` parameter to web cmdlets to allow for non-standard method verbs. (#3142) (Thanks to @Lee303!) +- Add `SslProtocol` support to Web Cmdlets. (#5329) (Thanks @markekraus!) +- Add Multipart support to web cmdlets. (#4782) (Thanks @markekraus) +- Add `-NoProxy` to web cmdlets so that they ignore the system-wide proxy setting. (#3447) (Thanks to @TheFlyingCorpse!) +- User Agent of Web Cmdlets now reports the OS platform (#4937) (Thanks @LDSpits) +- Add `-SkipHeaderValidation` switch to web cmdlets to support adding headers without validating the header value. (#4085) +- Enable web cmdlets to not validate the HTTPS certificate of the server if required. +- Add authentication parameters to web cmdlets. (#5052) (Thanks @markekraus) + - Add `-Authentication` that provides three options: Basic, OAuth, and Bearer. + - Add `-Token` to get the bearer token for OAuth and Bearer options. + - Add `-AllowUnencryptedAuthentication` to bypass authentication that is provided for any transport scheme other than HTTPS. +- Add `-ResponseHeadersVariable` to `Invoke-RestMethod` to enable the capture of response headers. (#4888) (Thanks @markekraus) +- Fix web cmdlets to include the HTTP response in the exception when the response status code is not success. (#3201) +- Change web cmdlets `UserAgent` from `WindowsPowerShell` to `PowerShell`. (#4914) (Thanks @markekraus) +- Add explicit `ContentType` detection to `Invoke-RestMethod` (#4692) +- Fix web cmdlets `-SkipHeaderValidation` to work with non-standard User-Agent headers. (#4479 & #4512) (Thanks @markekraus) + +### JSON cmdlets + +- Add `-AsHashtable` to `ConvertFrom-Json` to return a `Hashtable` instead. (#5043) (Thanks @bergmeister!) +- Use prettier formatter with `ConvertTo-Json` output. (#2787) (Thanks to @kittholland!) +- Add `Jobject` serialization support to `ConvertTo-Json`. (#5141) +- Fix `ConvertFrom-Json` to deserialize an array of strings from the pipeline that together construct a complete JSON string. + This fixes some cases where newlines would break JSON parsing. (#3823) +- Remove the `AliasProperty "Count"` defined for `System.Array`. + This removes the extraneous `Count` property on some `ConvertFrom-Json` output. (#3231) (Thanks to @PetSerAl!) + +### CSV cmdlets + +- Add `PSTypeName` Support for `Import-Csv` and `ConvertFrom-Csv`. (#5389) (Thanks @markekraus!) +- Make `Import-Csv` support `CR`, `LF`, and `CRLF` as line delimiters. (#5363) (Thanks @iSazonov!) +- Make `-NoTypeInformation` the default on `Export-Csv` and `ConvertTo-Csv`. (#5164) (Thanks @markekraus) + +### Service cmdlets + +- Add properties `UserName`, `Description`, `DelayedAutoStart`, `BinaryPathName`, and `StartupType` to the `ServiceController` objects returned by `Get-Service`. (#4907) (Thanks @joandrsn) +- Add functionality to set credentials on `Set-Service` command. (#4844) (Thanks @joandrsn) + +### Other cmdlets + +- Add a parameter to `Get-ChildItem` called `-FollowSymlink` that traverses symlinks on demand, with checks for link loops. (#4020) +- Update `Add-Type` to support `CSharpVersion7`. (#3933) (Thanks to @iSazonov) +- Remove the `Microsoft.PowerShell.LocalAccounts` module due to the use of unsupported APIs until a better solution is found. (#4302) +- Remove the `*-Counter` cmdlets in `Microsoft.PowerShell.Diagnostics` due to the use of unsupported APIs until a better solution is found. (#4303) +- Add support for `Invoke-Item -Path `. (#4262) +- Add `-Extension` and `-LeafBase` switches to `Split-Path` so that you can split paths between the filename extension and the rest of the filename. (#2721) (Thanks to @powercode!) +- Add parameters `-Top` and `-Bottom` to `Sort-Object` for Top/Bottom N sort +- Expose a process' parent process by adding the `CodeProperty "Parent"` to `System.Diagnostics.Process`. (#2850) (Thanks to @powercode!) +- Use MB instead of KB for memory columns of `Get-Process` +- Add `-NoNewLine` switch for `Out-String`. (#5056) (Thanks @raghav710) +- `Move-Item` cmdlet honors `-Include`, `-Exclude`, and `-Filter` parameters. (#3878) +- Allow `*` to be used in registry path for `Remove-Item`. (#4866) +- Add `-Title` to `Get-Credential` and unify the prompt experience across platforms. +- Add the `-TimeOut` parameter to `Test-Connection`. (#2492) +- `Get-AuthenticodeSignature` cmdlets can now get file signature timestamp. (#4061) +- Remove unsupported `-ShowWindow` switch from `Get-Help`. (#4903) +- Fix `Get-Content -Delimiter` to not include the delimiter in the array elements returned (#3706) (Thanks @mklement0) +- Add `Meta`, `Charset`, and `Transitional` parameters to `ConvertTo-HTML` (#4184) (Thanks @ergo3114) +- Add `WindowsUBR` and `WindowsVersion` properties to `Get-ComputerInfo` result +- Add `-Group` parameter to `Get-Verb` +- Add `ShouldProcess` support to `New-FileCatalog` and `Test-FileCatalog` (fixes `-WhatIf` and `-Confirm`). (#3074) (Thanks to @iSazonov!) +- Add `-WhatIf` switch to `Start-Process` cmdlet (#4735) (Thanks @sarithsutha) +- Add `ValidateNotNullOrEmpty` too many existing parameters. + +## Tab completion + +- Enhanced the type inference in tab completion based on runtime variable values. (#2744) (Thanks to @powercode!) + This enables tab completion in situations like: + + ```powershell + $p = Get-Process + $p | Foreach-Object Prio + ``` + +- Add Hashtable tab completion for `-Property` of `Select-Object`. (#3625) (Thanks to @powercode) +- Enable argument auto-completion for `-ExcludeProperty` and `-ExpandProperty` of `Select-Object`. (#3443) (Thanks to @iSazonov!) +- Fix a bug in tab completion to make `native.exe --` call into native completer. (#3633) (Thanks to @powercode!) + +## Breaking changes + +We've introduced a number of breaking changes in PowerShell Core 6.0. +To read more about them in detail, see [Breaking Changes in PowerShell Core 6.0][breaking-changes]. + +## Debugging + +- Support for remote step-in debugging for `Invoke-Command -ComputerName`. (#3015) +- Enable binder debug logging in PowerShell Core + +## Filesystem updates + +- Enable usage of the Filesystem provider from a UNC path. ($4998) +- `Split-Path` now works with UNC roots +- `cd` with no arguments now behaves as `cd ~` +- Fixed PowerShell Core to allow use of paths that are more than 260 characters long. (#3960) + +## Bug fixes and performance improvements + +We've made *many* improvements to performance across PowerShell, +including in startup time, various built-in cmdlets, and interaction with native binaries. + +We've also fixed a number of bugs within PowerShell Core. +For a complete list of fixes and changes, check out our [changelog][] on GitHub. + +## Telemetry + +- PowerShell Core 6.0 added telemetry to the console host to report two values (#3620): + - the OS platform (`$PSVersionTable.OSDescription`) + - the exact version of PowerShell (`$PSVersionTable.GitCommitId`) + +If you want to opt-out of this telemetry, simply delete `$PSHome\DELETE_ME_TO_DISABLE_CONSOLEHOST_TELEMETRY`. +Deleting this file bypasses all telemetry even before the first run of PowerShell. +We also plan on exposing this telemetry data and the insights we glean from the telemetry in the [community dashboard][community-dashboard]. +You can find out more about how we use this data in this [blog post][telemetry-blog]. + +[github]: https://github.com/PowerShell/PowerShell +[.NET Core 2.0]: https://docs.microsoft.com/en-us/dotnet/core/ +[.NET Standard]: https://docs.microsoft.com/en-us/dotnet/standard/net-standard +[os_log]: https://developer.apple.com/documentation/os/logging +[Syslog]: https://en.wikipedia.org/wiki/Syslog +[ssh-remoting]: ../core-powershell/SSH-Remoting-in-PowerShell-Core.md +[breaking-changes]: https://github.com/PowerShell/PowerShell/tree/master/docs/BREAKINGCHANGES.md +[changelog]: https://github.com/PowerShell/PowerShell/tree/master/CHANGELOG.md +[community-dashboard]: https://aka.ms/PSGitHubBI +[telemetry-blog]: https://blogs.msdn.microsoft.com/powershell/2017/01/31/powershell-open-source-community-dashboard/ +[.NET Standard]: https://docs.microsoft.com/dotnet/standard/net-standard +[.NET Blog]: https://blogs.msdn.microsoft.com/dotnet/2016/09/26/introducing-net-standard +[YouTube]: https://www.youtube.com/watch?v=YI4MurjfMn8&list=PLRAdsfhKI4OWx321A_pr-7HhRNk7wOLLY +[FAQ]: https://github.com/dotnet/standard/blob/master/docs/faq.md +[CDXML]: https://msdn.microsoft.com/en-us/library/jj542525(v=vs.85).aspx +[docker-hub]: https://hub.docker.com/r/microsoft/powershell/ +[docker]: https://github.com/PowerShell/PowerShell/tree/master/docker +[windowspsmodulepath]: https://www.powershellgallery.com/packages/WindowsPSModulePath/ +[semi-annual]: https://docs.microsoft.com/windows-server/get-started/semi-annual-channel-overview \ No newline at end of file