Merge pull request #11629 from MicrosoftDocs/main

1/3/2024 PM Publish

Author: Taojunshen

.github/ISSUE_TEMPLATE/01-article.yml

@@ -33,9 +33,8 @@ body:
       multiple: true
       options:
         - "5.1"
-        - "7.2"
-        - "7.3"
         - "7.4"
+        - "7.5"
   - type: textarea
     id: summary
     validations:

CODE_OF_CONDUCT.md

@@ -1,10 +1,44 @@
 # Microsoft Open Source Code of Conduct
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+This project has adopted the [Microsoft Open Source Code of Conduct][02].
 
-Resources:
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and
+healthy community.
 
-- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
-- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
-- Contact [[email protected]](mailto:[email protected]) with questions or concerns
-- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support)
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the
+  experience
+- Focusing on what's best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- Disruptive behavior
+  - Submitting spam comments, issues, or pull requests
+  - Defacing or vandalizing the project, repository, content, or documentation
+  - Intentionally introducing security vulnerabilities
+- Disrespectful behavior
+  - Trolling, insulting or derogatory comments, and personal or political attacks
+  - Public or private harassment
+  - Publishing others' private information, such as a physical or email address, without their
+    explicit permission
+  - The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Other conduct that could reasonably be considered inappropriate in a professional setting
+
+## Resources
+
+- [Microsoft Open Source Code of Conduct][02]
+- [Microsoft Code of Conduct FAQ][03]
+- Contact [[email protected]][04] with questions or concerns
+- Employees can reach out at [aka.ms/opensource/moderation-support][01]
+
+<!--  link references -->
+[01]: https://aka.ms/opensource/moderation-support
+[02]: https://opensource.microsoft.com/codeofconduct/
+[03]: https://opensource.microsoft.com/codeofconduct/faq/
+[04]: mailto:[email protected]

CONTRIBUTING.md

@@ -3,4 +3,4 @@
 Thank you for your interest in contributing to quality documentations.
 As an open source project, we welcome input and updates from the community.
 
-Please see our Contributor's Guide at https://aka.ms/PSDocsContributor.
+Please see our Contributor's Guide at <https://aka.ms/PSDocsContributor>

README.md

@@ -1,5 +1,5 @@
 ---
-ms.date: 11/02/2024
+ms.date: 01/03/2025
 ---
 # PowerShell Documentation
 
@@ -9,15 +9,6 @@ Welcome to the PowerShell-Docs repository, the home of the official PowerShell d
 
 This project has adopted the [Microsoft Open Source Code of Conduct][04].
 
-## Build Status
-
-[live-badge]: https://powershell.visualstudio.com/PowerShell-Docs/_apis/build/status/PowerShell-Docs-CI?branchName=live
-[main-badge]: https://powershell.visualstudio.com/PowerShell-Docs/_apis/build/status/PowerShell-Docs-CI?branchName=main
-
-|          live branch          |          main branch          |
-| :---------------------------- | :---------------------------- |
-| [![live-badge][]][live-badge] | [![main-badge][]][main-badge] |
-
 ## PowerShell Updatable Help (CabGen) CI Build Status
 
 [![Build Status][cabgen-status]][cabgen-log]
@@ -29,14 +20,13 @@ This project has adopted the [Microsoft Open Source Code of Conduct][04].
 
 The following list describes the main folders in this repository.
 
+- `.devcontainer` - configuration files for the VS Code Remote - Containers extension
 - `.github` - contains configuration settings used by GitHub for this repository
-- `.vscode` - contains configuration settings and recommended extensions for Visual Studio Code (VS
-  Code)
+- `.vscode` - contains configuration settings and recommended extensions for VS Code
 - `assets` - contains downloadable files linked in the documentation
 - `redir` - contain redirection mapping files
-- `reference` - contains the documentation published to
-  [learn.microsoft.com][01]. This includes both
-  reference and conceptual content.
+- `reference` - contains the documentation published to [learn.microsoft.com][01]. This includes
+  both reference and conceptual content.
   - `5.1` - contains the cmdlet reference and about topics for PowerShell 5.1
   - `7.4` - contains the cmdlet reference and about topics for PowerShell 7.4
   - `7.5` - contains the cmdlet reference and about topics for PowerShell 7.5
@@ -52,9 +42,10 @@ The following list describes the main folders in this repository.
 - `tests` - contains the Pester tests used by the build system
 - `tools` - contains other tools used by the build system
 
-> NOTE: The reference content (in the numbered folders) is used to create the webpages on the Docs
-> site as well as the updateable help used by PowerShell. The articles in the `docs-conceptual`
-> folder are only published to the Docs website.
+> [!NOTE]
+> The reference content (in the numbered folders) is used to create the webpages on the Docs site as
+> well as the updateable help used by PowerShell. The articles in the `docs-conceptual` folder are
+> only published to the Docs website.
 
 ## Contributing
 
@@ -69,11 +60,13 @@ consistent across versions.
 
 ## Licenses
 
-There are two license files for this project. The MIT License applies to the code contained in this
-repo. The Creative Commons license applies to the documentation.
+There are two license files for this project. The [MIT License][05] applies to the code contained in
+this repo. The [Creative Commons license][06] applies to the documentation.
 
 <!-- link references -->
 [01]: https://learn.microsoft.com/powershell/scripting/
 [02]: https://aka.ms/PSDocsContributor
 [03]: https://cla.microsoft.com/
 [04]: CODE_OF_CONDUCT.md
+[05]: LICENSE-CODE.md
+[06]: LICENSE.md

reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md

@@ -1,7 +1,7 @@
 ---
 description: Describes arrays, which are data structures designed to store collections of items.
 Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/03/2025
 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple]
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
@@ -10,6 +10,7 @@ title: about_Arrays
 # about_Arrays
 
 ## Short description
+
 Describes arrays, which are data structures designed to store collections of
 items.
 
@@ -341,9 +342,25 @@ while($i -lt 4) {
 
 ### Count or Length or LongLength
 
-To determine how many items are in an array, use the **Length** property or its
-**Count** alias. **Longlength** is useful if the array contains more than
-2,147,483,647 elements.
+In PowerShell, arrays have three properties that indicate the number of items
+contained in the array.
+
+- **Count** - This property is the most commonly used property to determine the
+  number of items in any collection, not just an array. It's an `[Int32]` type
+  value. In Windows PowerShell 5.1 (and older) **Count** alias property for
+  **Length**.
+
+- **Length** - This property is an `[Int32]` type value. This contains the same
+  value as **Count**.
+
+  > [!NOTE]
+  > While **Count** and **Length** are equivalent for arrays, **Length** can
+  > have a different meaning for other types. For example, **Length** for a
+  > string is the number of characters in the string. But the **Count**
+  > property is always `1`.
+
+- **Longlength** - This property is an `[Int64]` type value. Use this property
+  for arrays containing more than 2,147,483,647 elements.
 
 ```powershell
 $a = 0..9
@@ -470,7 +487,7 @@ True
 In this example, `$intA` is explicitly typed to contain integers.
 
 ```powershell
-[int[]] $intA = 1, 2, 3
+[Int[]] $intA = 1, 2, 3
 $intA.Clear()
 $intA
 ```
@@ -488,7 +505,7 @@ for each element of the array.
 
 The `ForEach()` method has several overloads that perform different operations.
 
-```
+```Syntax
 ForEach(scriptblock expression)
 ForEach(scriptblock expression, object[] arguments)
 ForEach(type convertToType)
@@ -884,10 +901,11 @@ faster, especially for large arrays.
 
 ## Arrays of zero or one
 
-Beginning in Windows PowerShell 3.0, a collection of zero or one object has the
-**Count** and **Length** properties. Also, you can index into an array of one
-object. This feature helps you to avoid scripting errors that occur when a
-command that expects a collection gets fewer than two items.
+Beginning in Windows PowerShell 3.0, a scalar types and collection of zero or
+one objects has the **Count** and **Length** properties. Also, you can use
+array index notation to access the value of a singleton scalar object. This
+feature helps you to avoid scripting errors that occur when a command that
+expects a collection gets fewer than two items.
 
 > [!NOTE]
 In Windows PowerShell, objects created by casting a **Hashtable** to

reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md

@@ -1,7 +1,7 @@
 ---
 description: Introduces advanced functions that are a way to create cmdlets using scripts.
 Locale: en-US
-ms.date: 01/20/2023
+ms.date: 01/02/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced
@@ -14,8 +14,8 @@ Introduces advanced functions that are a way to create cmdlets using scripts.
 ## Long description
 
 A cmdlet is a single command that participates in the pipeline semantics of
-PowerShell. This includes binary cmdlets, advanced script functions, CDXML, and
-Workflows.
+PowerShell. This includes binary cmdlets, PowerShell advanced script
+functions, CDXML, and Workflows.
 
 Advanced functions allow you create cmdlets that are written as a PowerShell
 function. Advanced functions make it easier to create cmdlets without having to
@@ -28,6 +28,12 @@ the Cmdlet attribute that's used in compiled cmdlet classes to identify the
 class as a cmdlet. For more information about this attribute, see
 [about_Functions_CmdletBindingAttribute][03].
 
+The parameters of the function are variables declared in the `param()`
+statement. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes. For more information about how to declare parameters, see
+[about_Functions_Advanced_Parameters][02].
+
 The following example shows a function that accepts a name and then prints a
 greeting using the supplied name. Also notice that this function defines a name
 that includes a verb (Send) and noun (Greeting) pair like the verb-noun pair of
@@ -37,36 +43,29 @@ a compiled cmdlet. However, functions aren't required to have a verb-noun name.
 function Send-Greeting
 {
     [CmdletBinding()]
-    Param(
+    param(
         [Parameter(Mandatory=$true)]
         [string] $Name
     )
 
-    Process
+    process
     {
         Write-Host ("Hello " + $Name + "!")
     }
 }
 ```
 
-The parameters of the function are declared using the `Parameter` attribute.
-This attribute can be used alone, or it can be combined with the Alias
-attribute or with several other parameter validation attributes. For more
-information about how to declare parameters (including dynamic parameters that
-are added at runtime), see [about_Functions_Advanced_Parameters][02].
-
-The actual work of the previous function is performed in the `process` block,
-which is equivalent to the **ProcessingRecord** method that's used by compiled
-cmdlets to process the data that's passed to the cmdlet. This block, along with
-the `begin` and `end` blocks, is described in the
-[about_Functions_Advanced_Methods][01] topic.
+This function performs the work in the `process` block, which is equivalent to
+the **ProcessingRecord** method used in compiled cmdlets. The `process` block
+and the other named blocks are described in
+[about_Functions_Advanced_Methods][01].
 
 Advanced functions differ from compiled cmdlets in the following ways:
 
 - Advanced function parameter binding doesn't throw an exception when an array
   of strings is bound to a **Boolean** parameter.
-- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass named
-  parameters.
+- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass
+  named parameters.
 - Advanced functions can't be used in transactions.
 
 ## See also
@@ -76,10 +75,12 @@ Advanced functions differ from compiled cmdlets in the following ways:
 - [about_Functions_Advanced_Parameters][02]
 - [about_Functions_CmdletBindingAttribute][03]
 - [about_Functions_OutputTypeAttribute][04]
+- [about_Variables][06]
 
 <!-- link references -->
 [01]: about_Functions_Advanced_Methods.md
 [02]: about_Functions_Advanced_Parameters.md
 [03]: about_Functions_CmdletBindingAttribute.md
 [04]: about_Functions_OutputTypeAttribute.md
 [05]: about_Functions.md
+[06]: about_Variables.md