diff --git a/.github/ISSUE_TEMPLATE/Document_New_Feature.md b/.github/ISSUE_TEMPLATE/Document_New_Feature.md deleted file mode 100644 index 5dd75b3270a4..000000000000 --- a/.github/ISSUE_TEMPLATE/Document_New_Feature.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -name: Document new feature or change in behavior 🆕 -about: Document a new feature or changed behavior -title: "Document Request" -labels: doc-idea -assignees: '' ---- - - -# Summary of the new document or enhancement - -- List of articles that need to be updated: -- New articles that need to be created: -- Link(s) to related code PR(s) in the PowerShell/PowerShell repo: -- Link(s) to related issue(s) in the PowerShell/PowerShell repo: - -## Description of what changed - diff --git a/.github/ISSUE_TEMPLATE/Documentation_Issue.md b/.github/ISSUE_TEMPLATE/Documentation_Issue.md deleted file mode 100644 index 2a1ccd3921f3..000000000000 --- a/.github/ISSUE_TEMPLATE/Documentation_Issue.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: Documentation Issue 📚 -about: Problems with PowerShell documentation -title: "Documentation Issue" -labels: question -assignees: '' ---- - -# Documentation Issue - - -## Context of the issue - -- URL to the article (Docs or GitHub URL): -- Issue affects the following content (check all that apply): - -**Conceptual content** -- [ ] Overview and Install -- [ ] Learning PowerShell - - [ ] PowerShell 101 - - [ ] Deep dives - - [ ] Remoting -- [ ] Release notes (What's New) -- [ ] Windows PowerShell - - WMF, ISE, release notes, etc. -- [ ] DSC articles -- [ ] Community resources -- [ ] Sample scripts -- [ ] Gallery articles -- [ ] Scripting and development - - [ ] Legacy SDK - -**Cmdlet reference & about_ topics** -- [ ] Preview content -- [ ] Version 7.2 content -- [ ] Version 7.1 content -- [ ] Version 7.0 content -- [ ] Version 5.1 content - -- Is the issue specific to a platform (Y/N - Win/macOS/Linux): - -## Detailed description of the issue - - diff --git a/.github/ISSUE_TEMPLATE/New_Document.yml b/.github/ISSUE_TEMPLATE/New_Document.yml new file mode 100644 index 000000000000..15a47cf05b2e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/New_Document.yml @@ -0,0 +1,42 @@ +name: New Document Request/Idea 🆕 +description: Suggest a new document or major rewrite of an existing one. +labels: doc-idea +body: +- type: checkboxes + attributes: + label: Prerequisites + options: + - label: Write a descriptive title. + required: true + - label: Search the existing issues. + required: true +- type: textarea + attributes: + label: Summary of the new document or enhancement + description: > + A clear and concise description of purpose the new document. Why it is needed? + What gap is it filling? Who is the intended audience? What is the intended + scenario being addressed? + placeholder: > + Try formulating it in user story style. 'As a user I need a document about X so that I + can Y.' with X being the problem or scenario and Y being the purpose and/or target audience + for the document. + validations: + required: true +- type: input + attributes: + label: Proposed title + validations: + required: true +- type: input + attributes: + label: Proposed location in the TOC + validations: + required: false +- type: textarea + attributes: + label: List of related articles to link to + description: Provide a list of files that need to be updated. + placeholder: Enter the Docs or GitHub URL to the article to be updated. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/New_Document_Request.md b/.github/ISSUE_TEMPLATE/New_Document_Request.md deleted file mode 100644 index 435049a5441a..000000000000 --- a/.github/ISSUE_TEMPLATE/New_Document_Request.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: New Document Request/Idea 🚀 -about: Suggest a new document or major rewrite of an existing one -title: "Document Request" -labels: doc-idea -assignees: '' - ---- - -# Summary of the new document or enhancement - - - -Details of requested document: - -- Proposed title: -- Propose location in the TOC: -- Target audience: -- Purpose or scenario: - _or_ - Proposed changes/additions to existing article: -- List of related articles to link to: diff --git a/.github/ISSUE_TEMPLATE/New_Feature.yml b/.github/ISSUE_TEMPLATE/New_Feature.yml new file mode 100644 index 000000000000..16b9525b0267 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/New_Feature.yml @@ -0,0 +1,39 @@ +name: Describe new feature or change in behavior 🚀 +description: Update existing documentation for a change in behavior or add new documentation for a new feature. +labels: doc-idea +body: +- type: checkboxes + attributes: + label: Prerequisites + options: + - label: Write a descriptive title. + required: true + - label: Search the existing issues. + required: true +- type: textarea + attributes: + label: Summary of the new feature or changed behavior + description: > + A clear and concise description of change. + placeholder: > + Describe the impact of the change and examples, if possible. Include new and changed + parameters and changed output. Put code and output inside ``` blocks. + validations: + required: true +- type: textarea + attributes: + label: List of articles that need to be updated + description: Provide a list of files that need to be updated. + placeholder: Enter the Docs or GitHub URL to the article to be updated. +- type: input + attributes: + label: Link to related PR in PowerShell/PowerShell repo + placeholder: PowerShell/PowerShell#12345 + validations: + required: true +- type: input + attributes: + label: Link to related Issues in PowerShell/PowerShell repo + placeholder: PowerShell/PowerShell#12345 + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/New_Issue.yml b/.github/ISSUE_TEMPLATE/New_Issue.yml new file mode 100644 index 000000000000..b453aa078b5a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/New_Issue.yml @@ -0,0 +1,58 @@ +name: Documentation issue report 🐛 +description: Report an issue with current documentation. +labels: doc-bug +body: +- type: markdown + attributes: + value: | + Use this template to report issues with documentation. This can include typos, + technical and factual errors, grammar, spelling, formatting, presentation, etc. + + Support questions should be posted to community support forums. See the [Community support](https://docs.microsoft.com/powershell/scripting/community/community-support) page. +- type: checkboxes + attributes: + label: Prerequisites + options: + - label: Write a descriptive title. + required: true + - label: Search the existing issues. + required: true + - label: I am reporting the documentation problem for version of PowerShell I am using. + required: true +- type: dropdown + attributes: + label: Version + description: What version of the documentation is affected? (select all that apply) + multiple: true + options: + - 5.1 + - 7.0 + - 7.1 + - 7.2 + - Preview version + validations: + required: true +- type: input + attributes: + label: Link to affected document + placeholder: Enter a GitHub or Docs URL to the article. + validations: + required: true +- type: textarea + attributes: + label: Description of the documentation error + description: > + Describe the error in the documentation. Include details about what you this is wrong. + placeholder: | + Example 3 has invalid parameters. + + List of steps, sample code, or failing test to support your claim. + validations: + required: true +- type: textarea + attributes: + label: Suggested fix + description: > + How would you change the document to make it correct. + validations: + required: false diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index d5ecccf78269..e47661c54d8b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -38,9 +38,10 @@ PowerShell supports the following arithmetic operators: | |strings, arrays, and hash tables. |`"file" + "name"` | | | |`@(1, "one") + @(2.0, "two")`| | | |`@{"one" = 1} + @{"two" = 2}`| +| +     |Makes a number out of an object   | + 123                       | | - |Subtracts one value from another |`6 - 2` | | |value | | -| - |Makes a number a negative number |`-6` | +| - |Calculates the opposite number |`- -6` | | | |`(Get-Date).AddDays(-1)` | | * |Multiply numbers or copy strings |`6 * 2` | | |and arrays the specified number |`@("!") * 4` | @@ -178,7 +179,9 @@ operation fails. The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object -types. Assume `$array = 1,2,3`: +types. +Assume `$array = 1,2,3`, +`$red = [ConsoleColor]::Red`, `$blue = [ConsoleColor]::Blue`: |Expression |Result | |-----------------|-----------------------| @@ -187,6 +190,10 @@ types. Assume `$array = 1,2,3`: |`$array + "file"`|`1`,`2`,`3`,`file` | |`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| |`"file" * 3` |`filefilefile` | +|`$blue + 3` |`Red` | +|`$red - 3` |`Blue` | +|`$blue - $red` |`-3` | +|`+ '123'` |`123` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -201,7 +208,7 @@ The following examples demonstrate this principle: |`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| | |`Error: "Input string was not in a correct format."` | | |`At line:1 char:1` | -| |+ 16 + "file"` | +| |`+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -305,8 +312,7 @@ result without losing precision. For example: ```powershell 2 + 3.1 - -(2). GetType().FullName +(2).GetType().FullName (2 + 3.1).GetType().FullName ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md index cd001e7421f1..7ae440184d46 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md @@ -1,7 +1,7 @@ --- description: Describes automatic members in all PowerShell objects Locale: en-US -ms.date: 07/14/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Inrinsic_Members?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Intrinsic_Members @@ -95,4 +95,38 @@ information on how to use these methods, see [about_Arrays](about_Arrays.md). The **Count** and **Length** properties are available to all PowerShell objects. These are similar to each other but may work differently depending on -the data type. For more information about these properties, see [about_Properties](about_Properties.md). +the data type. For more information about these properties, see +[about_Properties](about_Properties.md). + +## Array indexing scalar types + +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + +For more information, see [about_Operators](about_Operators.md#index-operator--). + +## New() method for types + +Beginning in PowerShell 5.0, PowerShell adds a static `New()` method for all +.NET types. The following examples produce the same result. + +```powershell +$expression = New-Object -TypeName regex -ArgumentList 'pattern' +$expression = [regex]::new('pattern') +``` + +Using the `new()` method performs better than using `New-Object`. + +For more information, see [about_Classes](about_Classes.md). diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md index e56200bb195c..1ac3005434c8 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 06/08/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -270,10 +270,7 @@ Converts or limits objects to the specified type. If the objects cannot be converted, PowerShell generates an error. ```powershell -[DateTime]"2/20/88" - [DateTime]"1/20/88" -[Int] (7/2) -[String] 1 + 0 -[Int] '1' + 0 +[DateTime] '2/20/88' - [DateTime] '1/20/88' -eq [TimeSpan] '31' ``` A cast can also be performed when a variable is assigned to using @@ -349,9 +346,12 @@ method and [Composite Formatting](/dotnet/standard/base-types/composite-formatti ### Index operator `[ ]` Selects objects from indexed collections, such as arrays and hash tables. Array -indexes are zero-based, so the first object is indexed as `[0]`. For arrays -(only), you can also use negative indexes to get the last values. Hash tables -are indexed by key value. +indexes are zero-based, so the first object is indexed as `[0]`. You can also +use negative indexes to get the last values. Hash tables are indexed by key +value. + +Given a list of indices, the index operator returns a list of members +corresponding to those indices. ``` PS> $a = 1, 2, 3 @@ -359,6 +359,10 @@ PS> $a[0] 1 PS> $a[-1] 3 +PS> $a[2, 1, 0] +3 +2 +1 ``` ```powershell @@ -385,6 +389,21 @@ intro Once upon a time... ``` +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + ### Pipeline operator `|` Sends ("pipes") the output of the command that precedes it to the command that diff --git a/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md index 41bef6d6c9b0..ffc92c14ec1c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 09/13/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/invoke-command?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-Command diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 587c2f690127..43a7fa1aee8a 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -38,9 +38,10 @@ PowerShell supports the following arithmetic operators: | |strings, arrays, and hash tables. |`"file" + "name"` | | | |`@(1, "one") + @(2.0, "two")`| | | |`@{"one" = 1} + @{"two" = 2}`| +| + |Makes a number out of an object | + 123 | | - |Subtracts one value from another |`6 - 2` | | |value | | -| - |Makes a number a negative number |`-6` | +| - |Calculates the opposite number |`- -6` | | | |`(Get-Date).AddDays(-1)` | | * |Multiply numbers or copy strings |`6 * 2` | | |and arrays the specified number |`@("!") * 4` | @@ -178,7 +179,9 @@ operation fails. The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object -types. Assume `$array = 1,2,3`: +types. +Assume `$array = 1,2,3`, +`$red = [ConsoleColor]::Red`, `$blue = [ConsoleColor]::Blue`: |Expression |Result | |-----------------|-----------------------| @@ -187,6 +190,10 @@ types. Assume `$array = 1,2,3`: |`$array + "file"`|`1`,`2`,`3`,`file` | |`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| |`"file" * 3` |`filefilefile` | +|`$blue + 3` |`Red` | +|`$red - 3` |`Blue` | +|`$blue - $red` |`-3` | +|`+ '123'` |`123` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -201,7 +208,7 @@ The following examples demonstrate this principle: |`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| | |`Error: "Input string was not in a correct format."` | | |`At line:1 char:1` | -| |+ 16 + "file"` | +| |`+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -305,8 +312,7 @@ result without losing precision. For example: ```powershell 2 + 3.1 - -(2). GetType().FullName +(2).GetType().FullName (2 + 3.1).GetType().FullName ``` diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md index 1068d4c96929..793e070ac9da 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md @@ -1,7 +1,7 @@ --- description: Describes automatic members in all PowerShell objects Locale: en-US -ms.date: 06/01/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Inrinsic_Members?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Intrinsic_Members @@ -95,4 +95,38 @@ information on how to use these methods, see [about_Arrays](about_Arrays.md). The **Count** and **Length** properties are available to all PowerShell objects. These are similar to each other but may work differently depending on -the data type. For more information about these properties, see [about_Properties](about_Properties.md). +the data type. For more information about these properties, see +[about_Properties](about_Properties.md). + +## Array indexing scalar types + +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + +For more information, see [about_Operators](about_Operators.md#index-operator--). + +## New() method for types + +Beginning in PowerShell 5.0, PowerShell adds a static `New()` method for all +.NET types. The following examples produce the same result. + +```powershell +$expression = New-Object -TypeName regex -ArgumentList 'pattern' +$expression = [regex]::new('pattern') +``` + +Using the `new()` method performs better than using `New-Object`. + +For more information, see [about_Classes](about_Classes.md). diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Operators.md index da4bc039a5a2..f9f71a771fbb 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 06/08/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -337,10 +337,7 @@ Converts or limits objects to the specified type. If the objects cannot be converted, PowerShell generates an error. ```powershell -[DateTime]"2/20/88" - [DateTime]"1/20/88" -[Int] (7/2) -[String] 1 + 0 -[Int] '1' + 0 +[DateTime] '2/20/88' - [DateTime] '1/20/88' -eq [TimeSpan] '31' ``` A cast can also be performed when a variable is assigned to using @@ -416,9 +413,12 @@ method and [Composite Formatting](/dotnet/standard/base-types/composite-formatti ### Index operator `[ ]` Selects objects from indexed collections, such as arrays and hash tables. Array -indexes are zero-based, so the first object is indexed as `[0]`. For arrays -(only), you can also use negative indexes to get the last values. Hash tables -are indexed by key value. +indexes are zero-based, so the first object is indexed as `[0]`. You can also +use negative indexes to get the last values. Hash tables are indexed by key +value. + +Given a list of indices, the index operator returns a list of members +corresponding to those indices. ``` PS> $a = 1, 2, 3 @@ -426,6 +426,10 @@ PS> $a[0] 1 PS> $a[-1] 3 +PS> $a[2, 1, 0] +3 +2 +1 ``` ```powershell @@ -452,6 +456,21 @@ intro Once upon a time... ``` +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + ### Pipeline operator `|` Sends ("pipes") the output of the command that precedes it to the command that diff --git a/reference/7.0/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/7.0/Microsoft.PowerShell.Core/Invoke-Command.md index 44d0c9199744..5ce4c7cb155d 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/7.0/Microsoft.PowerShell.Core/Invoke-Command.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 09/13/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/invoke-command?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-Command @@ -605,7 +605,7 @@ Enable-WSManCredSSP -Role Client -DelegateComputer Server02 $s = New-PSSession Server02 Invoke-Command -Session $s -ScriptBlock {Enable-WSManCredSSP -Role Server -Force} $parameters = @{ - Session = $s + ComputerName = 'Server02' ScriptBlock = { Get-Item \\Net03\Scripts\LogFiles.ps1 } Authentication = "CredSSP" Credential = "Domain01\Admin01" diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 13856c41ab40..5594de3334f5 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -38,9 +38,10 @@ PowerShell supports the following arithmetic operators: | |strings, arrays, and hash tables. |`"file" + "name"` | | | |`@(1, "one") + @(2.0, "two")`| | | |`@{"one" = 1} + @{"two" = 2}`| +| + |Makes a number out of an object | + 123 | | - |Subtracts one value from another |`6 - 2` | | |value | | -| - |Makes a number a negative number |`-6` | +| - |Calculates the opposite number |`- -6` | | | |`(Get-Date).AddDays(-1)` | | * |Multiply numbers or copy strings |`6 * 2` | | |and arrays the specified number |`@("!") * 4` | @@ -178,7 +179,9 @@ operation fails. The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object -types. Assume `$array = 1,2,3`: +types. +Assume `$array = 1,2,3`, +`$red = [ConsoleColor]::Red`, `$blue = [ConsoleColor]::Blue`: |Expression |Result | |-----------------|-----------------------| @@ -187,6 +190,10 @@ types. Assume `$array = 1,2,3`: |`$array + "file"`|`1`,`2`,`3`,`file` | |`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| |`"file" * 3` |`filefilefile` | +|`$blue + 3` |`Red` | +|`$red - 3` |`Blue` | +|`$blue - $red` |`-3` | +|`+ '123'` |`123` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -201,7 +208,7 @@ The following examples demonstrate this principle: |`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| | |`Error: "Input string was not in a correct format."` | | |`At line:1 char:1` | -| |+ 16 + "file"` | +| |`+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -305,8 +312,7 @@ result without losing precision. For example: ```powershell 2 + 3.1 - -(2). GetType().FullName +(2).GetType().FullName (2 + 3.1).GetType().FullName ``` diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md index f0744154eff7..97c1474c14d9 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md @@ -1,7 +1,7 @@ --- description: Describes automatic members in all PowerShell objects Locale: en-US -ms.date: 07/14/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Inrinsic_Members?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Intrinsic_Members @@ -95,4 +95,38 @@ information on how to use these methods, see [about_Arrays](about_Arrays.md). The **Count** and **Length** properties are available to all PowerShell objects. These are similar to each other but may work differently depending on -the data type. For more information about these properties, see [about_Properties](about_Properties.md). +the data type. For more information about these properties, see +[about_Properties](about_Properties.md). + +## Array indexing scalar types + +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + +For more information, see [about_Operators](about_Operators.md#index-operator--). + +## New() method for types + +Beginning in PowerShell 5.0, PowerShell adds a static `New()` method for all +.NET types. The following examples produce the same result. + +```powershell +$expression = New-Object -TypeName regex -ArgumentList 'pattern' +$expression = [regex]::new('pattern') +``` + +Using the `new()` method performs better than using `New-Object`. + +For more information, see [about_Classes](about_Classes.md). diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Operators.md index 0699eb1d7923..a31a0d5ad352 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 06/08/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -337,10 +337,7 @@ Converts or limits objects to the specified type. If the objects cannot be converted, PowerShell generates an error. ```powershell -[DateTime]"2/20/88" - [DateTime]"1/20/88" -[Int] (7/2) -[String] 1 + 0 -[Int] '1' + 0 +[DateTime] '2/20/88' - [DateTime] '1/20/88' -eq [TimeSpan] '31' ``` A cast can also be performed when a variable is assigned to using @@ -416,9 +413,12 @@ method and [Composite Formatting](/dotnet/standard/base-types/composite-formatti ### Index operator `[ ]` Selects objects from indexed collections, such as arrays and hash tables. Array -indexes are zero-based, so the first object is indexed as `[0]`. For arrays -(only), you can also use negative indexes to get the last values. Hash tables -are indexed by key value. +indexes are zero-based, so the first object is indexed as `[0]`. You can also +use negative indexes to get the last values. Hash tables are indexed by key +value. + +Given a list of indices, the index operator returns a list of members +corresponding to those indices. ``` PS> $a = 1, 2, 3 @@ -426,6 +426,10 @@ PS> $a[0] 1 PS> $a[-1] 3 +PS> $a[2, 1, 0] +3 +2 +1 ``` ```powershell @@ -452,6 +456,21 @@ intro Once upon a time... ``` +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + ### Pipeline operator `|` Sends ("pipes") the output of the command that precedes it to the command that diff --git a/reference/7.1/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/7.1/Microsoft.PowerShell.Core/Invoke-Command.md index f1486249f13b..a9ff65f824fb 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/7.1/Microsoft.PowerShell.Core/Invoke-Command.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 09/13/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/invoke-command?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-Command @@ -605,7 +605,7 @@ Enable-WSManCredSSP -Role Client -DelegateComputer Server02 $s = New-PSSession Server02 Invoke-Command -Session $s -ScriptBlock {Enable-WSManCredSSP -Role Server -Force} $parameters = @{ - Session = $s + ComputerName = 'Server02' ScriptBlock = { Get-Item \\Net03\Scripts\LogFiles.ps1 } Authentication = "CredSSP" Credential = "Domain01\Admin01" diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index d7f61054a7bf..3b7f95236224 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -38,9 +38,10 @@ PowerShell supports the following arithmetic operators: | |strings, arrays, and hash tables. |`"file" + "name"` | | | |`@(1, "one") + @(2.0, "two")`| | | |`@{"one" = 1} + @{"two" = 2}`| +| + |Makes a number out of an object | + 123 | | - |Subtracts one value from another |`6 - 2` | | |value | | -| - |Makes a number a negative number |`-6` | +| - |Calculates the opposite number |`- -6` | | | |`(Get-Date).AddDays(-1)` | | * |Multiply numbers or copy strings |`6 * 2` | | |and arrays the specified number |`@("!") * 4` | @@ -178,7 +179,9 @@ operation fails. The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object -types. Assume `$array = 1,2,3`: +types. +Assume `$array = 1,2,3`, +`$red = [ConsoleColor]::Red`, `$blue = [ConsoleColor]::Blue`: |Expression |Result | |-----------------|-----------------------| @@ -187,6 +190,10 @@ types. Assume `$array = 1,2,3`: |`$array + "file"`|`1`,`2`,`3`,`file` | |`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| |`"file" * 3` |`filefilefile` | +|`$blue + 3` |`Red` | +|`$red - 3` |`Blue` | +|`$blue - $red` |`-3` | +|`+ '123'` |`123` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -201,7 +208,7 @@ The following examples demonstrate this principle: |`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| | |`Error: "Input string was not in a correct format."` | | |`At line:1 char:1` | -| |+ 16 + "file"` | +| |˙+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -305,8 +312,7 @@ result without losing precision. For example: ```powershell 2 + 3.1 - -(2). GetType().FullName +(2).GetType().FullName (2 + 3.1).GetType().FullName ``` diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md index f64b64687a0e..30858cc3bd10 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md @@ -1,7 +1,7 @@ --- description: Describes automatic members in all PowerShell objects Locale: en-US -ms.date: 07/14/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Inrinsic_Members?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Intrinsic_Members @@ -95,4 +95,38 @@ information on how to use these methods, see [about_Arrays](about_Arrays.md). The **Count** and **Length** properties are available to all PowerShell objects. These are similar to each other but may work differently depending on -the data type. For more information about these properties, see [about_Properties](about_Properties.md). +the data type. For more information about these properties, see +[about_Properties](about_Properties.md). + +## Array indexing scalar types + +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + +For more information, see [about_Operators](about_Operators.md#index-operator--). + +## New() method for types + +Beginning in PowerShell 5.0, PowerShell adds a static `New()` method for all +.NET types. The following examples produce the same result. + +```powershell +$expression = New-Object -TypeName regex -ArgumentList 'pattern' +$expression = [regex]::new('pattern') +``` + +Using the `new()` method performs better than using `New-Object`. + +For more information, see [about_Classes](about_Classes.md). diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md index 46e47ed4eec4..b555e678613b 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 06/08/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -337,10 +337,7 @@ Converts or limits objects to the specified type. If the objects cannot be converted, PowerShell generates an error. ```powershell -[DateTime]"2/20/88" - [DateTime]"1/20/88" -[Int] (7/2) -[String] 1 + 0 -[Int] '1' + 0 +[DateTime] '2/20/88' - [DateTime] '1/20/88' -eq [TimeSpan] '31' ``` A cast can also be performed when a variable is assigned to using @@ -416,9 +413,12 @@ method and [Composite Formatting](/dotnet/standard/base-types/composite-formatti ### Index operator `[ ]` Selects objects from indexed collections, such as arrays and hash tables. Array -indexes are zero-based, so the first object is indexed as `[0]`. For arrays -(only), you can also use negative indexes to get the last values. Hash tables -are indexed by key value. +indexes are zero-based, so the first object is indexed as `[0]`. You can also +use negative indexes to get the last values. Hash tables are indexed by key +value. + +Given a list of indices, the index operator returns a list of members +corresponding to those indices. ``` PS> $a = 1, 2, 3 @@ -426,6 +426,10 @@ PS> $a[0] 1 PS> $a[-1] 3 +PS> $a[2, 1, 0] +3 +2 +1 ``` ```powershell @@ -452,6 +456,21 @@ intro Once upon a time... ``` +When an object is not an indexed collection, using the index operator to access +the first element returns the object itself. Index values beyond the first +element return `$null`. + +``` +PS> (2)[0] +2 +PS> (2)[-1] +2 +PS> (2)[1] -eq $null +True +PS> (2)[0,0] -eq $null +True +``` + ### Pipeline operator `|` Sends ("pipes") the output of the command that precedes it to the command that diff --git a/reference/7.2/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/7.2/Microsoft.PowerShell.Core/Invoke-Command.md index f7d68f328628..94bfa12ea90b 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/7.2/Microsoft.PowerShell.Core/Invoke-Command.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 09/13/2021 +ms.date: 11/16/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/invoke-command?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-Command @@ -605,7 +605,7 @@ Enable-WSManCredSSP -Role Client -DelegateComputer Server02 $s = New-PSSession Server02 Invoke-Command -Session $s -ScriptBlock {Enable-WSManCredSSP -Role Server -Force} $parameters = @{ - Session = $s + ComputerName = 'Server02' ScriptBlock = { Get-Item \\Net03\Scripts\LogFiles.ps1 } Authentication = "CredSSP" Credential = "Domain01\Admin01" diff --git a/reference/docs-conceptual/gallery/how-to/getting-support/troubleshooting-cmdlets.md b/reference/docs-conceptual/gallery/how-to/getting-support/troubleshooting-cmdlets.md index 0c9611fff321..528594bc0311 100644 --- a/reference/docs-conceptual/gallery/how-to/getting-support/troubleshooting-cmdlets.md +++ b/reference/docs-conceptual/gallery/how-to/getting-support/troubleshooting-cmdlets.md @@ -21,7 +21,7 @@ Update-Module Azure -Verbose ## Required network endpoints -The Install and Update cmdlets require internet access to connect to the network endpoints used by +The Install and Update cmdlets require internet access to connect to the network endpoints used by the PowerShell Gallery. Ensure that your network access policies allow you to connect to the following endpoints. diff --git a/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md b/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md index e96b470b3da1..efee625b865a 100644 --- a/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md +++ b/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md @@ -136,7 +136,7 @@ You can double-click the file and follow the prompts, or install it from the ter following commands. Change the name of the file to match the file you downloaded. ```sh -sudo installer -pkg powershell-7.1.5-osx-x64.pkg -target / +sudo installer -pkg powershell-7.2.0-osx-x64.pkg -target / ``` Install [OpenSSL](#installing-dependencies). OpenSSL is needed for PowerShell remoting and CIM @@ -189,19 +189,19 @@ match the version you want to install. ```sh # Download the powershell '.tar.gz' archive -curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v7.1.5/powershell-7.1.5-osx-x64.tar.gz +curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v7.2.0/powershell-7.2.0-osx-x64.tar.gz # Create the target folder where powershell is placed -sudo mkdir -p /usr/local/microsoft/powershell/7.1.5 +sudo mkdir -p /usr/local/microsoft/powershell/7.2.0 # Expand powershell to the target folder -sudo tar zxf /tmp/powershell.tar.gz -C /usr/local/microsoft/powershell/7.1.5 +sudo tar zxf /tmp/powershell.tar.gz -C /usr/local/microsoft/powershell/7.2.0 # Set execute permissions -sudo chmod +x /usr/local/microsoft/powershell/7.1.5/pwsh +sudo chmod +x /usr/local/microsoft/powershell/7.2.0/pwsh # Create the symbolic link that points to pwsh -sudo ln -s /usr/local/microsoft/powershell/7.1.5/pwsh /usr/local/bin/pwsh +sudo ln -s /usr/local/microsoft/powershell/7.2.0/pwsh /usr/local/bin/pwsh ``` ## Installing dependencies @@ -224,8 +224,10 @@ if needed. [installation guide](https://www.macports.org/install.php). 1. Update MacPorts by running `sudo port selfupdate`. 1. Upgrade MacPorts packages by running `sudo port upgrade outdated`. -1. Install OpenSSL by running `sudo port install openssl10`. -1. Link the libraries to make them available to PowerShell: +1. Install OpenSSL: + - For x64-based systems run `sudo port install openssl10` + - For M1-based systems run `sudo port install openssl10 +universal` +4. Link the libraries to make them available to PowerShell: ```sh sudo mkdir -p /usr/local/opt/openssl @@ -254,7 +256,7 @@ and remove the paths using `sudo rm`. ## Paths -- `$PSHOME` is `/usr/local/microsoft/powershell/7.1.5/` +- `$PSHOME` is `/usr/local/microsoft/powershell/7.2.0/` - User profiles are read from `~/.config/powershell/profile.ps1` - Default profiles are read from `$PSHOME/profile.ps1` - User modules are read from `~/.local/share/powershell/Modules` @@ -268,7 +270,7 @@ exists at `Microsoft.PowerShell_profile.ps1` in the same locations. PowerShell respects the [XDG Base Directory Specification][xdg-bds] on macOS. Because macOS is a derivation of BSD, the prefix `/usr/local` is used instead of `/opt`. So, -`$PSHOME` is `/usr/local/microsoft/powershell/7.1.5/`, and the symbolic link is placed at +`$PSHOME` is `/usr/local/microsoft/powershell/7.2.0/`, and the symbolic link is placed at `/usr/local/bin/pwsh`. ## Supported versions