diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 72fb0b9d71a3..19a64bfc80ad 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -1,7 +1,7 @@ --- -description: Describes how to write comment-based help topics for functions and scripts. +description: Describes how to write comment-based help content for functions and scripts. Locale: en-US -ms.date: 07/05/2022 +ms.date: 01/09/2025 no-loc: [.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, .INPUTS, .OUTPUTS, .NOTES, .LINK, .COMPONENT, .ROLE, .FUNCTIONALITY, .FORWARDHELPTARGETNAME, .FORWARDHELPCATEGORY, .REMOTEHELPRUNSPACE, .EXTERNALHELP] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -10,47 +10,49 @@ title: about_Comment_Based_Help # about_Comment_Based_Help ## Short description -Describes how to write comment-based help topics for functions and scripts. +Describes how to write comment-based help content for functions and scripts. ## Long description -You can write comment-based help topics for functions and scripts by using +You can write comment-based help content for functions and scripts by using special help comment keywords. -The [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) cmdlet displays -comment-based help in the same format in which it displays the cmdlet help -topics that are generated from XML files. Users can use all of the parameters -of `Get-Help`, such as **Detailed**, **Full**, **Examples**, and **Online**, to -display the contents of comment-based help. +The [Get-Help][06] cmdlet displays comment-based help in the same format in +which it displays the cmdlet help content that are generated from XML files. +Users can use all of the parameters of `Get-Help`, such as **Detailed**, +**Full**, **Examples**, and **Online**, to display the contents of +comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function or script, -use the `.ExternalHelp` keyword. Without this keyword, `Get-Help` cannot find -XML-based help topics for functions or scripts. +use the `.EXTERNALHELP` keyword. Without this keyword, `Get-Help` can't find +XML-based help content for functions or scripts. -This topic explains how to write help topics for functions and scripts. For -information about how to display help topics for functions and scripts, see -[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help). +This topic explains how to write help content for functions and scripts. For +information about how to display help content for functions and scripts, see +[Get-Help][06]. -The [Update-Help](xref:Microsoft.PowerShell.Core.Update-Help) and -[Save-Help](xref:Microsoft.PowerShell.Core.Save-Help) cmdlets work only on XML -files. Updatable Help does not support comment-based help topics. +The [Update-Help][08] and [Save-Help][07] cmdlets work only on XML files. +Updatable Help doesn't support comment-based help content. ## Syntax for comment-based help +To create Comment-based help content, you can use either style of comments: +single-line comments or block comments. + The syntax for comment-based help is as follows: -``` +```Syntax # . # ``` or -``` +```Syntax <# -. - + . + #> ``` @@ -60,26 +62,26 @@ symbols to create a comment block. All the lines within the comment block are interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a -comment-based help topic follows a comment that is not part of the help -topic, there must be at least one blank line between the last non-help -comment line and the beginning of the comment-based help. +comment-based help topic follows a comment that's not part of the help topic, +there must be at least one blank line between the last non-help comment line +and the beginning of the comment-based help. Keywords define each section of comment-based help. Each comment-based help keyword is preceded by a dot `.`. The keywords can appear in any order. The -keyword names are not case-sensitive. +keyword names aren't case-sensitive. For example, the `.Description` keyword precedes a description of a function or script. -``` +```powershell <# .Description Get-Function displays the name and syntax of all functions in the session. #> ``` -The comment block must contain at least one keyword. Some of the keywords, -such as `.EXAMPLE`, can appear many times in the same comment block. The help +The comment block must contain at least one keyword. Some of the keywords, such +as `.EXAMPLE`, can appear many times in the same comment block. The help content for each keyword begins on the line after the keyword and can span multiple lines. @@ -89,34 +91,32 @@ Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - At the end of the function body. -- Before the `function` keyword. There cannot be more than one blank line +- Before the `function` keyword. There can't be more than one blank line between the last line of the function help and the `function` keyword. For example: ```powershell -function Get-Function -{ -<# -. - -#> +function Get-Function { + <# + . + + #> - # function logic + # function logic } ``` or ```powershell -function Get-Function -{ - # function logic +function Get-Function { + # function logic -<# -. - -#> + <# + . + + #> } ``` @@ -124,8 +124,8 @@ or ```powershell <# -. - + . + #> function Get-Function { } ``` @@ -154,8 +154,6 @@ For example: . #> - - function Get-Function { } ``` @@ -163,37 +161,18 @@ or ```powershell function Get-Function { } - <# . #> ``` -## Syntax for comment-based help in script modules - -In a script module `.psm1`, comment-based help uses the syntax for functions, -not the syntax for scripts. You cannot use the script syntax to provide help -for all functions defined in a script module. - -For example, if you are using the `.ExternalHelp` keyword to identify the -XML-based help files for the functions in a script module, you must add an -`.ExternalHelp` comment to each function. - -```powershell -# .ExternalHelp -function -{ - ... -} -``` - ## Comment-based help keywords -The following are valid comment-based help keywords. They are listed in the -order in which they typically appear in a help topic along with their intended -use. These keywords can appear in any order in the comment-based help, and -they are not case-sensitive. +The following are valid comment-based help keywords. These keywords can appear +in any order in the comment-based help, and they aren't case-sensitive. The +keywords are listed in in this article inthe order that they typically appear +in a help topic. ### .SYNOPSIS @@ -216,7 +195,7 @@ PowerShell interprets all text between the `.PARAMETER` line and the next keyword or the end of the comment block as part of the parameter description. The description can include paragraph breaks. -``` +```Syntax .PARAMETER ``` @@ -285,7 +264,7 @@ when you use the **Online** parameter of `Get-Help`. The URI must begin with ### .COMPONENT The name of the technology or feature that the function or script uses, or to -which it is related. The **Component** parameter of `Get-Help` uses this value +which it's related. The **Component** parameter of `Get-Help` uses this value to filter the search results returned by `Get-Help`. ### .ROLE @@ -302,7 +281,7 @@ results returned by `Get-Help`. ### .FORWARDHELPTARGETNAME Redirects to the help topic for the specified command. You can redirect users -to any help topic, including help topics for a function, script, cmdlet, or +to any help topic, including help content for a function, script, cmdlet, or provider. ```powershell @@ -324,8 +303,8 @@ this keyword to avoid conflicts when there are commands with the same name. Specifies a session that contains the help topic. Enter a variable that contains a **PSSession** object. This keyword is used by the -[Export-PSSession](xref:Microsoft.PowerShell.Utility.Export-PSSession) -cmdlet to find the help topics for the exported commands. +[Export-PSSession][09] cmdlet to find the help content for the exported +commands. ```powershell # .REMOTEHELPRUNSPACE @@ -339,26 +318,26 @@ Specifies an XML-based help file for the script or function. # .EXTERNALHELP ``` -The `.ExternalHelp` keyword is required when a function or script is documented -in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +The `.EXTERNALHELP` keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` can't find the XML-based help file for the function or script. -The `.ExternalHelp` keyword takes precedence over other comment-based help -keywords. If `.ExternalHelp` is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches the value -of the `.ExternalHelp` keyword. +The `.EXTERNALHELP` keyword takes precedence over other comment-based help +keywords. If `.EXTERNALHELP` is present, `Get-Help` doesn't display +comment-based help, even if it can't find a help topic that matches the value +of the `.EXTERNALHELP` keyword. -If the function is exported by a module, set the value of the `.ExternalHelp` +If the function is exported by a module, set the value of the `.EXTERNALHELP` keyword to a filename without a path. `Get-Help` looks for the specified file name in a language-specific subdirectory of the module directory. There are no requirements for the name of the XML-based help file for a function, but a best practice is to use the following format: -``` +```Syntax -help.xml ``` -If the function is not included in a module, include a path to the XML-based +If the function isn't included in a module, include a path to the XML-based help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in @@ -366,42 +345,42 @@ accordance with the language fallback standards established for Windows, just as it does in a module directory. For more information about the cmdlet help XML-based help file format, see -[How to Write Cmdlet Help](/powershell/scripting/developer/help/writing-comment-based-help-topics). +[How to Write Cmdlet Help][01]. ## Autogenerated content -The name, syntax, parameter list, parameter attribute table, common -parameters, and remarks are automatically generated by the `Get-Help` cmdlet. +The name, syntax, parameter list, parameter attribute table, common parameters, +and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The **Name** section of a function help topic is taken from the function name in -the function syntax. The **Name** of a script help topic is taken from the -script filename. To change the name or its capitalization, change the -function syntax or the script filename. +The **Name** section of a function help topic is taken from the function name +in the function syntax. The **Name** of a script help topic is taken from the +script filename. To change the name or its capitalization, change the function +syntax or the script filename. ### Syntax The **Syntax** section of the help topic is generated from the function or script syntax. To add detail to the help topic syntax, such as the .NET type of -a parameter, add the detail to the syntax. If you do not specify a parameter +a parameter, add the detail to the syntax. If you don't specify a parameter type, the **Object** type is inserted as the default value. ### Parameter List -The parameter list in the help topic is generated from the function or -script syntax and from the descriptions that you add by using the `.Parameter` +The parameter list in the help topic is generated from the function or script +syntax and from the descriptions that you add by using the `.Parameter` keyword. The function parameters appear in the **Parameters** section of the -help topic in the same order that they appear in the function or script -syntax. The spelling and capitalization of parameter names is also taken from -the syntax. It is not affected by the parameter name specified by the -`.Parameter` keyword. +help topic in the same order that they appear in the function or script syntax. +The spelling and capitalization of parameter names is also taken from the +syntax. It isn't affected by the parameter name specified by the `.Parameter` +keyword. ### Common Parameters -The **Common parameters** are added to the syntax and parameter list of the help -topic, even if they have no effect. For more information about the common -parameters, see [about_CommonParameters](about_CommonParameters.md). +The **Common parameters** are added to the syntax and parameter list of the +help topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters][02]. ### Parameter Attribute Table @@ -410,14 +389,14 @@ use the **Full** or **Parameter** parameter of `Get-Help`. The value of the **Required**, **Position**, and **Default** value attributes is taken from the function or script syntax. -Default values and a value for **Accept Wildcard characters** do not appear in -the parameter attribute table even when they are defined in the function or +Default values and a value for **Accept Wildcard characters** don't appear in +the parameter attribute table even when they're defined in the function or script. To help users, provide this information in the parameter description. ### Remarks The **Remarks** section of the help topic is automatically generated from the -function or script name. You cannot change or affect its content. +function or script name. You can't change or affect its content. ## Examples @@ -450,7 +429,7 @@ Specifies the extension. "Txt" is the default. .INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. .OUTPUTS @@ -535,7 +514,7 @@ This cmdlet supports the common parameters: -Verbose, -Debug, "get-help about_commonparameters". INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. OUTPUTS @@ -599,7 +578,7 @@ file name or extension. .INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. .OUTPUTS @@ -635,7 +614,7 @@ Set-Item ### Comment-based Help for a Script The following sample script includes comment-based help. Notice the blank lines -between the closing `#>` and the `Param` statement. In a script that does not +between the closing `#>` and the `Param` statement. In a script that doesn't have a `Param` statement, there must be at least two blank lines between the final comment in the help topic and the first function declaration. Without these blank lines, `Get-Help` associates the help topic with the function, not @@ -662,11 +641,11 @@ saves the output in the local directory. .INPUTS -None. You cannot pipe objects to Update-Month.ps1. +None. You can't pipe objects to Update-Month.ps1. .OUTPUTS -None. Update-Month.ps1 does not generate any output. +None. Update-Month.ps1 doesn't generate any output. .EXAMPLE @@ -688,8 +667,8 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not in a -directory that is listed in the `$env:Path` environment variable, the +The following command gets the script help. Because the script isn't in a +directory that's listed in the `$env:Path` environment variable, the `Get-Help` command that gets the script help must specify the script path. ```powershell @@ -745,11 +724,11 @@ This cmdlet supports the common parameters: -Verbose, -Debug, # INPUTS -None. You cannot pipe objects to Update-Month.ps1. +None. You can't pipe objects to Update-Month.ps1. # OUTPUTS -None. Update-Month.ps1 does not generate any output. +None. Update-Month.ps1 doesn't generate any output. Example 1 @@ -769,57 +748,54 @@ C:\Reports\2009\January.csv ### Redirecting to an XML File -You can write XML-based help topics for functions and scripts. Although +You can write XML-based help content for functions and scripts. Although comment-based help is easier to implement, XML-based help is required for -Updatable Help and to provide help topics in multiple languages. +Updatable Help and to provide help content in multiple languages. The following example shows the first few lines of the Update-Month.ps1 script. -The script uses the `.ExternalHelp` keyword to specify the path to an XML-based +The script uses the `.EXTERNALHELP` keyword to specify the path to an XML-based help topic for the script. -Note that the value of the `.ExternalHelp` keyword appears on the same -line as the keyword. Any other placement is ineffective. +Note that the value of the `.EXTERNALHELP` keyword appears on the same line as +the keyword. Any other placement is ineffective. ```powershell -# .ExternalHelp C:\MyScripts\Update-Month-Help.xml +# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml param ([string]$InputPath, [string]$OutPutPath) function Get-Data { } ... ``` -The following examples show three valid placements of the `.ExternalHelp` +The following examples show three valid placements of the `.EXTERNALHELP` keyword in a function. ```powershell -function Add-Extension -{ -# .ExternalHelp C:\ps-test\Add-Extension.xml +function Add-Extension { + # .EXTERNALHELP C:\ps-test\Add-Extension.xml -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name } ``` ```powershell -function Add-Extension -{ -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name +function Add-Extension { + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name -# .ExternalHelp C:\ps-test\Add-Extension.xml + # .EXTERNALHELP C:\ps-test\Add-Extension.xml } ``` ```powershell -# .ExternalHelp C:\ps-test\Add-Extension.xml -function Add-Extension -{ -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name +# .EXTERNALHELP C:\ps-test\Add-Extension.xml +function Add-Extension { + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name } ``` @@ -832,19 +808,18 @@ the help function uses the `.ForwardHelpTargetName` and `.ForwardHelpCategory` keywords to redirect the user to the `Get-Help` cmdlet help topic. ```powershell -function help -{ +function help { + <# + .FORWARDHELPTARGETNAME Get-Help + .FORWARDHELPCATEGORY Cmdlet + #> -<# -.FORWARDHELPTARGETNAME Get-Help -.FORWARDHELPCATEGORY Cmdlet -#> -[CmdletBinding(DefaultParameterSetName='AllUsersView')] -param( -[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)] -[System.String] -${Name}, -... + [CmdletBinding(DefaultParameterSetName='AllUsersView')] + param( + [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)] + [System.String] + ${Name}, + ... ``` The following command uses this feature: @@ -866,7 +841,18 @@ Displays information about PowerShell cmdlets and concepts. ## See also -- [about_Functions](about_Functions.md) -- [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) -- [about_Scripts](about_Scripts.md) -- [Writing Comment-Based Help Topics](/powershell/scripting/developer/help/writing-comment-based-help-topics) +- [about_Functions][04] +- [about_Functions_Advanced_Parameters][03] +- [about_Scripts][05] +- [Writing Comment-Based help content][01] + + +[01]: /powershell/scripting/developer/help/writing-comment-based-help-topics +[02]: about_CommonParameters.md +[03]: about_Functions_Advanced_Parameters.md +[04]: about_Functions.md +[05]: about_Scripts.md +[06]: xref:Microsoft.PowerShell.Core.Get-Help +[07]: xref:Microsoft.PowerShell.Core.Save-Help +[08]: xref:Microsoft.PowerShell.Core.Update-Help +[09]: xref:Microsoft.PowerShell.Utility.Export-PSSession diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Data_Sections.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Data_Sections.md index 8ba6b95a3cb2..e349f7431b45 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Data_Sections.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Data_Sections.md @@ -1,7 +1,7 @@ --- description: Explains Data sections, which isolate text strings and other read-only data from script logic. Locale: en-US -ms.date: 04/23/2019 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_data_sections?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Data_Sections @@ -9,14 +9,15 @@ title: about_Data_Sections # about_Data_Sections ## Short description -Explains Data sections, which isolate text strings and other read-only + +Explains `DATA` sections, which isolate text strings and other read-only data from script logic. ## Long description -Scripts that are designed for PowerShell can have one or more Data sections -that contain only data. You can include one or more Data sections in any -script, function, or advanced function. The content of the Data section is +Scripts that are designed for PowerShell can have one or more `DATA` sections +that contain only data. You can include one or more `DATA` sections in any +script, function, or advanced function. The content of the `DATA` section is restricted to a specified subset of the PowerShell scripting language. Separating data from code logic makes it easier to identify and manage both @@ -24,24 +25,23 @@ logic and data. It lets you have separate string resource files for text, such as error messages and Help strings. It also isolates the code logic, which facilitates security and validation tests. -In PowerShell, the Data section is used to support script internationalization. -You can use Data sections to make it easier to isolate, locate, and process -strings that will be translated into many user interface (UI) languages. +In PowerShell, you can use the `DATA` section to support script +internationalization. You can use `DATA` sections to make it easier to isolate, +locate, and process strings that can be translated into other languages. -The Data section is a PowerShell 2.0 feature. Scripts with Data sections will -not run in PowerShell 1.0 without revision. +The `DATA` section was added in PowerShell 2.0 feature. ### Syntax -The syntax for a Data section is as follows: +The syntax for a `DATA` section is as follows: -``` +```Syntax DATA [] [-supportedCommand ] { } ``` -The Data keyword is required. It is not case-sensitive. The permitted content +The `DATA` keyword is required. It isn't case-sensitive. The permitted content is limited to the following elements: - All PowerShell operators, except `-match` @@ -65,28 +65,28 @@ is limited to the following elements: '@ ``` -- Cmdlets that are permitted in a Data section. By default, only the +- Cmdlets that are permitted in a `DATA` section. By default, only the `ConvertFrom-StringData` cmdlet is permitted. -- Cmdlets that you permit in a Data section by using the `-SupportedCommand` +- Cmdlets that you permit in a `DATA` section by using the `-SupportedCommand` parameter. -When you use the `ConvertFrom-StringData` cmdlet in a Data section, you can +When you use the `ConvertFrom-StringData` cmdlet in a `DATA` section, you can enclose the key-value pairs in single-quoted or double-quoted strings or in single-quoted or double-quoted here-strings. However, strings that contain variables and subexpressions must be enclosed in single-quoted strings or in -single-quoted here-strings so that the variables are not expanded and the -subexpressions are not executable. +single-quoted here-strings so that the variables aren't expanded and the +subexpressions aren't executable. ### -SupportedCommand -The `-SupportedCommand` parameter allows you to indicate that a cmdlet or -function generates only data. It is designed to allow users to include cmdlets -and functions in a data section that they have written or tested. +The **SupportedCommand** parameter allows you to indicate that a cmdlet or +function generates only data. It's designed to allow users to include cmdlets +and functions in a `DATA` section that they have written or tested. -The value of `-SupportedCommand` is a comma-separated list of one or more +The value of **SupportedCommand** is a comma-separated list of one or more cmdlet or function names. -For example, the following data section includes a user-written cmdlet, +For example, the following `DATA` section includes a user-written cmdlet, `Format-Xml`, that formats data in an XML file: ```powershell @@ -96,16 +96,16 @@ DATA -supportedCommand Format-Xml } ``` -### Using a Data Section +### Using a `DATA` Section -To use the content of a Data section, assign it to a variable and use variable +To use the content of a `DATA` section, assign it to a variable and use variable notation to access the content. -For example, the following data section contains a `ConvertFrom-StringData` +For example, the following `DATA` section contains a `ConvertFrom-StringData` command that converts the here-string into a hash table. The hash table is assigned to the `$TextMsgs` variable. -The `$TextMsgs` variable is not part of the data section. +The `$TextMsgs` variable isn't part of the `DATA` section. ```powershell $TextMsgs = DATA { @@ -124,7 +124,8 @@ $TextMsgs.Text001 $TextMsgs.Text002 ``` -Alternately, you can put the variable name in the definition of the Data section. For example: +Alternately, you can put the variable name in the definition of the `DATA` +section. For example: ```powershell DATA TextMsgs { @@ -200,12 +201,23 @@ DATA -supportedCommand Format-XML { ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_If](about_If.md) -- [about_Operators](about_Operators.md) -- [about_Quoting_Rules](about_Quoting_Rules.md) -- [about_Script_Internationalization](about_Script_Internationalization.md) -- [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData) -- [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData) +- [about_Automatic_Variables][01] +- [about_Comparison_Operators][02] +- [about_Hash_Tables][03] +- [about_If][04] +- [about_Operators][05] +- [about_Quoting_Rules][06] +- [about_Script_Internationalization][07] +- [ConvertFrom-StringData][08] +- [Import-LocalizedData][09] + + +[01]: about_Automatic_Variables.md +[02]: about_Comparison_Operators.md +[03]: about_Hash_Tables.md +[04]: about_If.md +[05]: about_Operators.md +[06]: about_Quoting_Rules.md +[07]: about_Script_Internationalization.md +[08]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData +[09]: xref:Microsoft.PowerShell.Utility.Import-LocalizedData diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md index acb2706a3bcb..6e5be6210427 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 03/30/2021 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -161,8 +161,24 @@ Vanilla Strawberry-Blueberry ``` -Negative values are ignored. +Negative values return the amount of substrings requested starting +from the end of the input string. +> [!NOTE] +> Support for negative values was added in PowerShell 7. + +```powershell +$c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" +$c -split ",", -5 +``` + +```Output +Mercury,Venus,Earth,Mars +Jupiter +Saturn +Uranus +Neptune +``` ### \ @@ -216,26 +232,17 @@ The RegexMatch options are: SimpleMatch. - **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit operator is specified. -- **CultureInvariant**: Ignores cultural differences in language - when evaluating the delimiter. Valid only with RegexMatch. -- **IgnorePatternWhitespace**: Ignores unescaped whitespace and - comments marked with the number sign (#). Valid only with - RegexMatch. -- **Multiline**: Multiline mode forces `^` and `$` to match the beginning - end of every line instead of the beginning and end of the input string. -- **Singleline**: Singleline mode treats the input string as a *SingleLine*. - It forces the `.` character to match every character (including newlines), +- **CultureInvariant**: Ignores cultural differences in language when + evaluating the delimiter. Valid only with RegexMatch. +- **IgnorePatternWhitespace**: Ignores unescaped whitespace and comments marked + with the hash character (`#`). Valid only with RegexMatch. +- **Multiline**: Multiline mode forces `^` and `$` to match the beginning end + of every line instead of the beginning and end of the input string. +- **Singleline**: Singleline mode treats the input string as a *SingleLine*. It + forces the `.` character to match every character (including newlines), instead of matching every character EXCEPT the newline `\n`. -- **ExplicitCapture**: Ignores non-named match groups so that only - explicit capture groups are returned in the result list. Valid - only with RegexMatch. - -> [!NOTE] -> SingleLine is the default behavior. Singleline and Multiline -> cannot be used together with the options parameter. This was resolved in -> PowerShell 6.0. -> The work around is by using *Mode-Modifiers* in your regular expression. -> You can read more about mode modifiers in [Regular Expression Options](/dotnet/standard/base-types/regular-expression-options) +- **ExplicitCapture**: Ignores non-named match groups so that only explicit + capture groups are returned in the result list. Valid only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS @@ -390,6 +397,19 @@ b c,d,e,f,g,h ``` +The following statement splits a string into three substrings +starting from the end of the string. + +```powershell +"a,b,c,d,e,f,g,h" -split ",", -3 +``` + +```Output +a,b,c,d,e,f +g +h +``` + The following statement splits two strings into three substrings. (The limit is applied to each string independently.) @@ -423,7 +443,7 @@ $a = @' $a -split "^\d", 0, "multiline" ``` -```output +```Output The first line. diff --git a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index 58adbf198d96..f95fc7a56c37 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -2,8 +2,8 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 -online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-stringdata?view=powershell-5.1&WT.mc_id=ps-gethelp +ms.date: 01/09/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-stringdata?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertFrom-StringData --- @@ -36,7 +36,7 @@ machine translation tools. That is, the cmdlet can interpret backslashes (`\`) a in the string data by using the [Regex.Unescape Method](/dotnet/api/system.text.regularexpressions.regex.unescape), instead of the PowerShell backtick character (`` ` ``) that would normally signal the end of a line in a script. -Inside the here-string, the backtick character does not work. You can also preserve a literal +Inside the here-string, the backtick character doesn't work. You can also preserve a literal backslash in your results by escaping it with a preceding backslash, like this: `\\`. Unescaped backslash characters, such as those that are commonly used in file paths, can render as illegal escape sequences in your results. @@ -46,14 +46,14 @@ escape sequences in your results. ### Example 1: Convert a single-quoted here-string to a hash table This example converts a single-quoted here-string of user messages into a hash table. In a -single-quoted string, values are not substituted for variables and expressions are not evaluated. +single-quoted string, values aren't substituted for variables and expressions aren't evaluated. The `ConvertFrom-StringData` cmdlet converts the value in the `$Here` variable to a hash table. ```powershell $Here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. -Msg3 = The specified variable does not exist. +Msg3 = The specified variable doesn't exist. '@ ConvertFrom-StringData -StringData $Here ``` @@ -61,7 +61,7 @@ ConvertFrom-StringData -StringData $Here ```Output Name Value ---- ----- -Msg3 The specified variable does not exist. +Msg3 The specified variable doesn't exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. ``` @@ -92,8 +92,8 @@ Name Disks.ps1 The value of the **StringData** parameter is a here-string, instead of a variable that contains a here-string. Either format is valid. The here-string includes a comment about one of the strings. -`ConvertFrom-StringData` ignores single-line comments, but the `#` character must be the first -non-whitespace character on the line. All characters on the line after the `#` are ignored. +`ConvertFrom-StringData` ignores single-line comments, but the hash character (`#`) must be the +first non-whitespace character on the line. ### Example 3: Convert a string to a hash table @@ -115,9 +115,9 @@ Top Red To satisfy the condition that each key-value pair must be on a separate line, the string uses the PowerShell newline character (`` `n ``) to separate the pairs. -### Example 4: Use ConvertFrom-StringData in the DATA section of a script +### Example 4: Use in the `DATA` section of a script -This example shows a `ConvertFrom-StringData` command used in the **DATA** section of a script. +This example shows a `ConvertFrom-StringData` command used in the `DATA` section of a script. The statements below the **DATA** section display the text to the user. ```powershell @@ -138,7 +138,7 @@ Text002 The $MyNotebook variable contains the name of the user's privat ``` Because the text includes variable names, it must be enclosed in a single-quoted string so that the -variables are interpreted literally and not expanded. Variables are not permitted in the **DATA** +variables are interpreted literally and not expanded. Variables aren't permitted in the `DATA` section. ### Example 5: Use the pipeline operator to pass a string @@ -151,7 +151,7 @@ and the result in the `$Hash` variable. $Here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. -Msg3 = The specified variable does not exist. +Msg3 = The specified variable doesn't exist. '@ $Hash = $Here | ConvertFrom-StringData $Hash @@ -160,7 +160,7 @@ $Hash ```Output Name Value ---- ----- -Msg3 The specified variable does not exist. +Msg3 The specified variable doesn't exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. ``` @@ -168,7 +168,7 @@ Msg1 The string parameter is required. ### Example 6: Use escape characters to add new lines and return characters This example shows the use of escape characters to create new lines and return characters in source -data. The escape sequence `\n` is used to create new lines within a block of text that is associated +data. The escape sequence `\n` is used to create new lines within a block of text that's associated with a name or item in the resulting hash table. ```powershell @@ -187,7 +187,7 @@ Value : Let there be some more test made of my metal, Name : Vincentio Value : Heaven doth with us as we with torches do, Not light them for themselves; for if our virtues - Did not go forth of us, 'twere all alike + Didn't go forth of us, 'twere all alike As if we had them not. ``` @@ -218,10 +218,10 @@ The value of this parameter must be a string that contains one or more key-value key-value pair must be on a separate line, or each pair must be separated by newline characters (`` `n ``). -You can include comments in the string, but the comments cannot be on the same line as a key-value -pair. `ConvertFrom-StringData` ignores single-line comments. The `#` character must be the first -non-whitespace character on the line. All characters on the line after the `#` are ignored. The -comments are not included in the hash table. +You can include comments in the string, but the comments can't be on the same line as a key-value +pair. `ConvertFrom-StringData` ignores single-line comments. The hash character (`#`) must be the +first non-whitespace character on the line. All characters on the line after the hash character +(`#`) are ignored. The comments aren't included in the hash table. A here-string is a string consisting of one or more lines. Quotation marks within the here-string are interpreted literally as part of the string data. For more information, see diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Export-Alias.md b/reference/5.1/Microsoft.PowerShell.Utility/Export-Alias.md index f58b538295c5..95f7e31f7be5 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Export-Alias.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Export-Alias.md @@ -18,23 +18,27 @@ Exports information about currently defined aliases to a file. ### ByPath (Default) ``` -Export-Alias [-Path] [[-Name] ] [-PassThru] [-As ] [-Append] [-Force] - [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] [] +Export-Alias [-Path] [[-Name] ] [-PassThru] [-As ] [-Append] + [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] + [] ``` ### ByLiteralPath ``` -Export-Alias -LiteralPath [[-Name] ] [-PassThru] [-As ] [-Append] - [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] [] +Export-Alias -LiteralPath [[-Name] ] [-PassThru] [-As ] + [-Append] [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] + [] ``` ## DESCRIPTION -The `Export-Alias` cmdlet exports the aliases in the current session to a file. -If the output file does not exist, the cmdlet will create it. +The `Export-Alias` cmdlet exports the aliases in the current session to a file. If the output file +does not exist, the cmdlet will create it. -`Export-Alias` can export the aliases in a particular scope or all scopes, it can generate the data in CSV format or as a series of Set-Alias commands that you can add to a session or to a PowerShell profile. +`Export-Alias` can export the aliases in a particular scope or all scopes, it can generate the data +in CSV format or as a series of Set-Alias commands that you can add to a session or to a PowerShell +profile. ## EXAMPLES @@ -54,7 +58,8 @@ Export-Alias -Path "alias.csv" -NoClobber This command exports the aliases in the current session to an Alias.csv file. -Because the **NoClobber** parameter is specified, the command will fail if an Alias.csv file already exists in the current directory. +Because the **NoClobber** parameter is specified, the command will fail if an Alias.csv file already +exists in the current directory. ### Example 3: Append aliases to a file @@ -64,9 +69,11 @@ Export-Alias -Path "alias.csv" -Append -Description "Appended Aliases" -Force This command appends the aliases in the current session to the Alias.csv file. -The command uses the **Description** parameter to add a description to the comments at the top of the file. +The command uses the **Description** parameter to add a description to the comments at the top of +the file. -The command also uses the **Force** parameter to overwrite any existing Alias.csv files, even if they have the read-only attribute. +The command also uses the **Force** parameter to overwrite any existing Alias.csv files, even if +they have the read-only attribute. ### Example 4: Export aliases as a script @@ -79,23 +86,27 @@ Invoke-Command -Session $S -FilePath .\alias.ps1 This example shows how to use the script file format that `Export-Alias` generates. -The first command exports the aliases in the session to the Alias.ps1 file. -It uses the **As** parameter with a value of Script to generate a file that contains a Set-Alias command for each alias. +The first command exports the aliases in the session to the Alias.ps1 file. It uses the **As** +parameter with a value of Script to generate a file that contains a Set-Alias command for each +alias. The second command adds the aliases in the Alias.ps1 file to the CurrentUser-CurrentHost profile. -The path to the profile is saved in the `$Profile` variable. -The command uses the `Get-Content` cmdlet to get the aliases from the Alias.ps1 file and the `Add-Content` cmdlet to add them to the profile. -For more information, see [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). +The path to the profile is saved in the `$Profile` variable. The command uses the `Get-Content` +cmdlet to get the aliases from the Alias.ps1 file and the `Add-Content` cmdlet to add them to the +profile. For more information, see +[about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). -The third and fourth commands add the aliases in the Alias.ps1 file to a remote session on the Server01 computer. -The third command uses the `New-PSSession` cmdlet to create the session. -The fourth command uses the **FilePath** parameter of the `Invoke-Command` cmdlet to run the Alias.ps1 file in the new session. +The third and fourth commands add the aliases in the Alias.ps1 file to a remote session on the +Server01 computer. The third command uses the `New-PSSession` cmdlet to create the session. The +fourth command uses the **FilePath** parameter of the `Invoke-Command` cmdlet to run the Alias.ps1 +file in the new session. ## PARAMETERS ### -Append -Indicates that this cmdlet appends the output to the specified file, rather than overwriting the existing contents of that file. +Indicates that this cmdlet appends the output to the specified file, rather than overwriting the +existing contents of that file. ```yaml Type: System.Management.Automation.SwitchParameter @@ -115,11 +126,9 @@ Specifies the output format. CSV is the default. The acceptable values for this parameter are: -- CSV. -Comma-separated value (CSV) format. -- Script. -Creates a `Set-Alias` command for each exported alias. -If you name the output file with a .ps1 file name extension, you can run it as a script to add the aliases to any session. +- CSV. Comma-separated value (CSV) format. +- Script. Creates a `Set-Alias` command for each exported alias. If you name the output file with a + .ps1 file name extension, you can run it as a script to add the aliases to any session. ```yaml Type: Microsoft.PowerShell.Commands.ExportAliasFormat @@ -136,8 +145,8 @@ Accept wildcard characters: False ### -Description -Specifies the description of the exported file. -The description appears as a comment at the top of the file, following the header information. +Specifies the description of the exported file. The description appears as a comment at the top of +the file, following the header information. ```yaml Type: System.String @@ -157,8 +166,9 @@ Forces the command to run without asking for user confirmation. Overwrites the output file, even if the read-only attribute is set on the file. -By default, `Export-Alias` overwrites files without warning, unless the read-only or hidden attribute is set or the **NoClobber** parameter is used in the command. -The **NoClobber** parameter takes precedence over the **Force** parameter when both are used in a command. +By default, `Export-Alias` overwrites files without warning, unless the read-only or hidden +attribute is set or the **NoClobber** parameter is used in the command. The **NoClobber** parameter +takes precedence over the **Force** parameter when both are used in a command. The **Force** parameter cannot force `Export-Alias` to overwrite files with the hidden attribute. @@ -176,11 +186,10 @@ Accept wildcard characters: False ### -LiteralPath -Specifies the path to the output file. -Unlike **Path**, the value of the **LiteralPath** parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +Specifies the path to the output file. Unlike **Path**, the value of the **LiteralPath** parameter +is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes +escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not +to interpret any characters as escape sequences. ```yaml Type: System.String @@ -196,8 +205,7 @@ Accept wildcard characters: False ### -Name -Specifies the names as an array of the aliases to export. -Wildcards are permitted. +Specifies the names as an array of the aliases to export. Wildcards are permitted. By default, `Export-Alias` exports all aliases in the session or scope. @@ -215,12 +223,14 @@ Accept wildcard characters: True ### -NoClobber -Indicates that this cmdlet prevents `Export-Alias` from overwriting any files, even if the **Force** parameter is used in the command. +Indicates that this cmdlet prevents `Export-Alias` from overwriting any files, even if the **Force** +parameter is used in the command. -If the **NoClobber** parameter is omitted, `Export-Alias` will overwrite an existing file without warning, unless the read-only attribute is set on the file. -*NoClobber* takes precedence over the **Force** parameter, which permits `Export-Alias` to overwrite a file with the read-only attribute. +If the **NoClobber** parameter is omitted, `Export-Alias` will overwrite an existing file without +warning, unless the read-only attribute is set on the file. **NoClobber** takes precedence over the +**Force** parameter, which permits `Export-Alias` to overwrite a file with the read-only attribute. -*NoClobber* does not prevent the **Append** parameter from adding content to an existing file. +**NoClobber** does not prevent the **Append** parameter from adding content to an existing file. ```yaml Type: System.Management.Automation.SwitchParameter @@ -236,8 +246,8 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the item with which you are working. -By default, this cmdlet does not generate any output. +Returns an object representing the item with which you are working. By default, this cmdlet does not +generate any output. ```yaml Type: System.Management.Automation.SwitchParameter @@ -253,8 +263,8 @@ Accept wildcard characters: False ### -Path -Specifies the path to the output file. -Wildcards are permitted, but the resulting path value must resolve to a single file name. +Specifies the path to the output file. Wildcards are permitted, but the resulting path value must +resolve to a single file name. ```yaml Type: System.String @@ -270,16 +280,17 @@ Accept wildcard characters: True ### -Scope -Specifies the scope from which the aliases should be exported. -The acceptable values for this parameter are: +Specifies the scope from which the aliases should be exported. The acceptable values for this +parameter are: -- Global -- Local -- Script -- A number relative to the current scope (0 through the number of scopes where 0 is the current scope and 1 is its parent) +- `Global` +- `Local` +- `Script` +- A number relative to the current scope (0 through the number of scopes where 0 is the current + scope and 1 is its parent) -The default value is Local. -For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). +The default value is `Local`. For more information, see +[about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). ```yaml Type: System.String @@ -328,7 +339,10 @@ 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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md b/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md index b71a56b4bdfa..c41a2051f7fd 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/import-csv?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Import-Csv @@ -42,7 +42,7 @@ delimiter. You can also use the `ConvertTo-Csv` and `ConvertFrom-Csv` cmdlets to convert objects to CSV strings (and back). These cmdlets are the same as the `Export-CSV` and `Import-Csv` cmdlets, except -that they do not deal with files. +that they work with data from the pipeline instead of from files. If a header row entry in a CSV file contains an empty or null value, PowerShell inserts a default header row name and displays a warning message. @@ -141,8 +141,8 @@ properties in the resulting imported object. ```powershell Start-Job -ScriptBlock { Get-Process } | Export-Csv -Path .\Jobs.csv -NoTypeInformation $Header = 'State', 'MoreData', 'StatusMessage', 'Location', 'Command', 'StateInfo', 'Finished', - 'InstanceId', 'Id', 'Name', 'ChildJobs', 'BeginTime', 'EndTime', 'JobType', 'Output', 'Error', - 'Progress', 'Verbose', 'Debug', 'Warning', 'Information' + 'InstanceId', 'Id', 'Name', 'ChildJobs', 'BeginTime', 'EndTime', 'JobType', 'Output', + 'Error', 'Progress', 'Verbose', 'Debug', 'Warning', 'Information' # Delete the default header from file $A = Get-Content -Path .\Jobs.csv $A = $A[1..($A.Count - 1)] @@ -247,7 +247,7 @@ objects are stored in the `$A` variable. The `Get-Member` cmdlet shows the prope **Header** parameter. The `Where-Object` cmdlet selects objects with the **TopicTitle** property that includes **alias**. -### Example 6: Import a CSV that is missing a value +### Example 6: Import a CSV that's missing a value This example shows how the `Import-Csv` cmdlet in PowerShell responds when the header row in a CSV file includes a null or empty value. `Import-Csv` substitutes a default name for the missing header @@ -269,7 +269,7 @@ Import-Csv -Path .\Projects.csv ``` ```Output -WARNING: One or more headers were not specified. Default names starting with "H" have been used in +WARNING: One or more headers weren't specified. Default names starting with "H" have been used in place of any missing headers. ProjectID ProjectName H1 Completed @@ -279,24 +279,9 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` -```powershell -(Import-Csv -Path .\Projects.csv).H1 -``` - -```Output -WARNING: One or more headers were not specified. Default names starting with "H" have been used in -place of any missing headers. -Redmond -FarEast -Europe -``` - -To create your Projects.csv file, use the values shown in the example's `Get-Content` output. - -The `Get-Content` cmdlet displays the Projects.csv file. The header row is missing a value between -**ProjectName** and **Completed**. The `Import-Csv` cmdlet imports the Projects.csv file and -displays a warning message because **H1** is a default header name. The `(Import-Csv -Path -.\Projects.csv).H1` command gets the **H1** property values and displays a warning. +The `Get-Content` cmdlet displays the `Projects.csv` file. The header row is missing a value between +**ProjectName** and **Completed**. The `Import-Csv` cmdlet imports the `Projects.csv` file and +displays a warning message because **H1** is a default header name. ## PARAMETERS @@ -309,8 +294,8 @@ Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose i quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double quotation marks. -If you specify a character other than the actual string delimiter in the file, `Import-Csv` cannot -create the objects from the CSV strings and will return the CSV strings. +If you specify a character other than the actual string delimiter in the file, `Import-Csv` can't +create the objects from the CSV strings and returns the full CSV strings. ```yaml Type: System.Char @@ -357,7 +342,7 @@ Accept wildcard characters: False Specifies an alternate column header row for the imported file. The column header determines the property names of the objects created by `Import-Csv`. -Enter column headers as a character-separated list. Do not enclose the header string in quotation +Enter column headers as a character-separated list. Don't enclose the header string in quotation marks. Enclose each column header in single quotation marks. If you enter fewer column headers than there are data columns, the remaining data columns are @@ -382,7 +367,7 @@ Accept wildcard characters: False ### -LiteralPath Specifies the path to the CSV file to import. Unlike **Path**, the value of the **LiteralPath** -parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path +parameter is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -457,7 +442,7 @@ Windows PowerShell includes the following aliases for `Import-Csv`: - `ipcsv` -Because the imported objects are CSV versions of the object type, they are not recognized and +Because the imported objects are CSV versions of the object type, they're not recognized and formatted by the PowerShell type formatting entries that format the non-CSV versions of the object type. @@ -476,7 +461,7 @@ If the column header row is missing a value or contains a null or empty value, ` In the CSV file, each object is represented by a character-separated list of the property values of the object. The property values are converted to strings by using the **ToString()** method of the -object, so they are represented by the name of the property value. `Export-Csv` does not export the +object, so they're represented by the name of the property value. `Export-Csv` doesn't export the methods of the object. ## RELATED LINKS diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 69727f8bc5ff..6ba018dee95f 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -1,7 +1,7 @@ --- -description: Describes how to write comment-based help topics for functions and scripts. +description: Describes how to write comment-based help content for functions and scripts. Locale: en-US -ms.date: 07/05/2022 +ms.date: 01/09/2025 no-loc: [.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, .INPUTS, .OUTPUTS, .NOTES, .LINK, .COMPONENT, .ROLE, .FUNCTIONALITY, .FORWARDHELPTARGETNAME, .FORWARDHELPCATEGORY, .REMOTEHELPRUNSPACE, .EXTERNALHELP] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -10,47 +10,49 @@ title: about_Comment_Based_Help # about_Comment_Based_Help ## Short description -Describes how to write comment-based help topics for functions and scripts. +Describes how to write comment-based help content for functions and scripts. ## Long description -You can write comment-based help topics for functions and scripts by using +You can write comment-based help content for functions and scripts by using special help comment keywords. -The [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) cmdlet displays -comment-based help in the same format in which it displays the cmdlet help -topics that are generated from XML files. Users can use all of the parameters -of `Get-Help`, such as **Detailed**, **Full**, **Examples**, and **Online**, to -display the contents of comment-based help. +The [Get-Help][06] cmdlet displays comment-based help in the same format in +which it displays the cmdlet help content that are generated from XML files. +Users can use all of the parameters of `Get-Help`, such as **Detailed**, +**Full**, **Examples**, and **Online**, to display the contents of +comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function or script, -use the `.ExternalHelp` keyword. Without this keyword, `Get-Help` cannot find -XML-based help topics for functions or scripts. +use the `.EXTERNALHELP` keyword. Without this keyword, `Get-Help` can't find +XML-based help content for functions or scripts. -This topic explains how to write help topics for functions and scripts. For -information about how to display help topics for functions and scripts, see -[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help). +This topic explains how to write help content for functions and scripts. For +information about how to display help content for functions and scripts, see +[Get-Help][06]. -The [Update-Help](xref:Microsoft.PowerShell.Core.Update-Help) and -[Save-Help](xref:Microsoft.PowerShell.Core.Save-Help) cmdlets work only on XML -files. Updatable Help does not support comment-based help topics. +The [Update-Help][08] and [Save-Help][07] cmdlets work only on XML files. +Updatable Help doesn't support comment-based help content. ## Syntax for comment-based help +To create Comment-based help content, you can use either style of comments: +single-line comments or block comments. + The syntax for comment-based help is as follows: -``` +```Syntax # . # ``` or -``` +```Syntax <# -. - + . + #> ``` @@ -60,26 +62,26 @@ symbols to create a comment block. All the lines within the comment block are interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a -comment-based help topic follows a comment that is not part of the help -topic, there must be at least one blank line between the last non-help -comment line and the beginning of the comment-based help. +comment-based help topic follows a comment that's not part of the help topic, +there must be at least one blank line between the last non-help comment line +and the beginning of the comment-based help. Keywords define each section of comment-based help. Each comment-based help keyword is preceded by a dot `.`. The keywords can appear in any order. The -keyword names are not case-sensitive. +keyword names aren't case-sensitive. For example, the `.Description` keyword precedes a description of a function or script. -``` +```powershell <# .Description Get-Function displays the name and syntax of all functions in the session. #> ``` -The comment block must contain at least one keyword. Some of the keywords, -such as `.EXAMPLE`, can appear many times in the same comment block. The help +The comment block must contain at least one keyword. Some of the keywords, such +as `.EXAMPLE`, can appear many times in the same comment block. The help content for each keyword begins on the line after the keyword and can span multiple lines. @@ -89,34 +91,32 @@ Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - At the end of the function body. -- Before the `function` keyword. There cannot be more than one blank line +- Before the `function` keyword. There can't be more than one blank line between the last line of the function help and the `function` keyword. For example: ```powershell -function Get-Function -{ -<# -. - -#> +function Get-Function { + <# + . + + #> - # function logic + # function logic } ``` or ```powershell -function Get-Function -{ - # function logic +function Get-Function { + # function logic -<# -. - -#> + <# + . + + #> } ``` @@ -124,8 +124,8 @@ or ```powershell <# -. - + . + #> function Get-Function { } ``` @@ -154,8 +154,6 @@ For example: . #> - - function Get-Function { } ``` @@ -163,37 +161,18 @@ or ```powershell function Get-Function { } - <# . #> ``` -## Syntax for comment-based help in script modules - -In a script module `.psm1`, comment-based help uses the syntax for functions, -not the syntax for scripts. You cannot use the script syntax to provide help -for all functions defined in a script module. - -For example, if you are using the `.ExternalHelp` keyword to identify the -XML-based help files for the functions in a script module, you must add an -`.ExternalHelp` comment to each function. - -```powershell -# .ExternalHelp -function -{ - ... -} -``` - ## Comment-based help keywords -The following are valid comment-based help keywords. They are listed in the -order in which they typically appear in a help topic along with their intended -use. These keywords can appear in any order in the comment-based help, and -they are not case-sensitive. +The following are valid comment-based help keywords. These keywords can appear +in any order in the comment-based help, and they aren't case-sensitive. The +keywords are listed in in this article inthe order that they typically appear +in a help topic. ### .SYNOPSIS @@ -216,7 +195,7 @@ PowerShell interprets all text between the `.PARAMETER` line and the next keyword or the end of the comment block as part of the parameter description. The description can include paragraph breaks. -``` +```Syntax .PARAMETER ``` @@ -285,7 +264,7 @@ when you use the **Online** parameter of `Get-Help`. The URI must begin with ### .COMPONENT The name of the technology or feature that the function or script uses, or to -which it is related. The **Component** parameter of `Get-Help` uses this value +which it's related. The **Component** parameter of `Get-Help` uses this value to filter the search results returned by `Get-Help`. ### .ROLE @@ -302,7 +281,7 @@ results returned by `Get-Help`. ### .FORWARDHELPTARGETNAME Redirects to the help topic for the specified command. You can redirect users -to any help topic, including help topics for a function, script, cmdlet, or +to any help topic, including help content for a function, script, cmdlet, or provider. ```powershell @@ -324,8 +303,8 @@ this keyword to avoid conflicts when there are commands with the same name. Specifies a session that contains the help topic. Enter a variable that contains a **PSSession** object. This keyword is used by the -[Export-PSSession](xref:Microsoft.PowerShell.Utility.Export-PSSession) -cmdlet to find the help topics for the exported commands. +[Export-PSSession][09] cmdlet to find the help content for the exported +commands. ```powershell # .REMOTEHELPRUNSPACE @@ -339,26 +318,26 @@ Specifies an XML-based help file for the script or function. # .EXTERNALHELP ``` -The `.ExternalHelp` keyword is required when a function or script is documented -in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +The `.EXTERNALHELP` keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` can't find the XML-based help file for the function or script. -The `.ExternalHelp` keyword takes precedence over other comment-based help -keywords. If `.ExternalHelp` is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches the value -of the `.ExternalHelp` keyword. +The `.EXTERNALHELP` keyword takes precedence over other comment-based help +keywords. If `.EXTERNALHELP` is present, `Get-Help` doesn't display +comment-based help, even if it can't find a help topic that matches the value +of the `.EXTERNALHELP` keyword. -If the function is exported by a module, set the value of the `.ExternalHelp` +If the function is exported by a module, set the value of the `.EXTERNALHELP` keyword to a filename without a path. `Get-Help` looks for the specified file name in a language-specific subdirectory of the module directory. There are no requirements for the name of the XML-based help file for a function, but a best practice is to use the following format: -``` +```Syntax -help.xml ``` -If the function is not included in a module, include a path to the XML-based +If the function isn't included in a module, include a path to the XML-based help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in @@ -366,42 +345,42 @@ accordance with the language fallback standards established for Windows, just as it does in a module directory. For more information about the cmdlet help XML-based help file format, see -[How to Write Cmdlet Help](/powershell/scripting/developer/help/writing-comment-based-help-topics). +[How to Write Cmdlet Help][01]. ## Autogenerated content -The name, syntax, parameter list, parameter attribute table, common -parameters, and remarks are automatically generated by the `Get-Help` cmdlet. +The name, syntax, parameter list, parameter attribute table, common parameters, +and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The **Name** section of a function help topic is taken from the function name in -the function syntax. The **Name** of a script help topic is taken from the -script filename. To change the name or its capitalization, change the -function syntax or the script filename. +The **Name** section of a function help topic is taken from the function name +in the function syntax. The **Name** of a script help topic is taken from the +script filename. To change the name or its capitalization, change the function +syntax or the script filename. ### Syntax The **Syntax** section of the help topic is generated from the function or script syntax. To add detail to the help topic syntax, such as the .NET type of -a parameter, add the detail to the syntax. If you do not specify a parameter +a parameter, add the detail to the syntax. If you don't specify a parameter type, the **Object** type is inserted as the default value. ### Parameter List -The parameter list in the help topic is generated from the function or -script syntax and from the descriptions that you add by using the `.Parameter` +The parameter list in the help topic is generated from the function or script +syntax and from the descriptions that you add by using the `.Parameter` keyword. The function parameters appear in the **Parameters** section of the -help topic in the same order that they appear in the function or script -syntax. The spelling and capitalization of parameter names is also taken from -the syntax. It is not affected by the parameter name specified by the -`.Parameter` keyword. +help topic in the same order that they appear in the function or script syntax. +The spelling and capitalization of parameter names is also taken from the +syntax. It isn't affected by the parameter name specified by the `.Parameter` +keyword. ### Common Parameters -The **Common parameters** are added to the syntax and parameter list of the help -topic, even if they have no effect. For more information about the common -parameters, see [about_CommonParameters](about_CommonParameters.md). +The **Common parameters** are added to the syntax and parameter list of the +help topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters][02]. ### Parameter Attribute Table @@ -410,14 +389,14 @@ use the **Full** or **Parameter** parameter of `Get-Help`. The value of the **Required**, **Position**, and **Default** value attributes is taken from the function or script syntax. -Default values and a value for **Accept Wildcard characters** do not appear in -the parameter attribute table even when they are defined in the function or +Default values and a value for **Accept Wildcard characters** don't appear in +the parameter attribute table even when they're defined in the function or script. To help users, provide this information in the parameter description. ### Remarks The **Remarks** section of the help topic is automatically generated from the -function or script name. You cannot change or affect its content. +function or script name. You can't change or affect its content. ## Examples @@ -450,7 +429,7 @@ Specifies the extension. "Txt" is the default. .INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. .OUTPUTS @@ -535,7 +514,7 @@ This cmdlet supports the common parameters: -Verbose, -Debug, "get-help about_commonparameters". INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. OUTPUTS @@ -599,7 +578,7 @@ file name or extension. .INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. .OUTPUTS @@ -635,7 +614,7 @@ Set-Item ### Comment-based Help for a Script The following sample script includes comment-based help. Notice the blank lines -between the closing `#>` and the `Param` statement. In a script that does not +between the closing `#>` and the `Param` statement. In a script that doesn't have a `Param` statement, there must be at least two blank lines between the final comment in the help topic and the first function declaration. Without these blank lines, `Get-Help` associates the help topic with the function, not @@ -662,11 +641,11 @@ saves the output in the local directory. .INPUTS -None. You cannot pipe objects to Update-Month.ps1. +None. You can't pipe objects to Update-Month.ps1. .OUTPUTS -None. Update-Month.ps1 does not generate any output. +None. Update-Month.ps1 doesn't generate any output. .EXAMPLE @@ -688,8 +667,8 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not in a -directory that is listed in the `$env:Path` environment variable, the +The following command gets the script help. Because the script isn't in a +directory that's listed in the `$env:Path` environment variable, the `Get-Help` command that gets the script help must specify the script path. ```powershell @@ -745,11 +724,11 @@ This cmdlet supports the common parameters: -Verbose, -Debug, # INPUTS -None. You cannot pipe objects to Update-Month.ps1. +None. You can't pipe objects to Update-Month.ps1. # OUTPUTS -None. Update-Month.ps1 does not generate any output. +None. Update-Month.ps1 doesn't generate any output. Example 1 @@ -769,57 +748,54 @@ C:\Reports\2009\January.csv ### Redirecting to an XML File -You can write XML-based help topics for functions and scripts. Although +You can write XML-based help content for functions and scripts. Although comment-based help is easier to implement, XML-based help is required for -Updatable Help and to provide help topics in multiple languages. +Updatable Help and to provide help content in multiple languages. The following example shows the first few lines of the Update-Month.ps1 script. -The script uses the `.ExternalHelp` keyword to specify the path to an XML-based +The script uses the `.EXTERNALHELP` keyword to specify the path to an XML-based help topic for the script. -Note that the value of the `.ExternalHelp` keyword appears on the same -line as the keyword. Any other placement is ineffective. +Note that the value of the `.EXTERNALHELP` keyword appears on the same line as +the keyword. Any other placement is ineffective. ```powershell -# .ExternalHelp C:\MyScripts\Update-Month-Help.xml +# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml param ([string]$InputPath, [string]$OutPutPath) function Get-Data { } ... ``` -The following examples show three valid placements of the `.ExternalHelp` +The following examples show three valid placements of the `.EXTERNALHELP` keyword in a function. ```powershell -function Add-Extension -{ -# .ExternalHelp C:\ps-test\Add-Extension.xml +function Add-Extension { + # .EXTERNALHELP C:\ps-test\Add-Extension.xml -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name } ``` ```powershell -function Add-Extension -{ -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name +function Add-Extension { + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name -# .ExternalHelp C:\ps-test\Add-Extension.xml + # .EXTERNALHELP C:\ps-test\Add-Extension.xml } ``` ```powershell -# .ExternalHelp C:\ps-test\Add-Extension.xml -function Add-Extension -{ -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name +# .EXTERNALHELP C:\ps-test\Add-Extension.xml +function Add-Extension { + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name } ``` @@ -832,19 +808,18 @@ the help function uses the `.ForwardHelpTargetName` and `.ForwardHelpCategory` keywords to redirect the user to the `Get-Help` cmdlet help topic. ```powershell -function help -{ +function help { + <# + .FORWARDHELPTARGETNAME Get-Help + .FORWARDHELPCATEGORY Cmdlet + #> -<# -.FORWARDHELPTARGETNAME Get-Help -.FORWARDHELPCATEGORY Cmdlet -#> -[CmdletBinding(DefaultParameterSetName='AllUsersView')] -param( -[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)] -[System.String] -${Name}, -... + [CmdletBinding(DefaultParameterSetName='AllUsersView')] + param( + [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)] + [System.String] + ${Name}, + ... ``` The following command uses this feature: @@ -866,7 +841,18 @@ Displays information about PowerShell cmdlets and concepts. ## See also -- [about_Functions](about_Functions.md) -- [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) -- [about_Scripts](about_Scripts.md) -- [Writing Comment-Based Help Topics](/powershell/scripting/developer/help/writing-comment-based-help-topics) +- [about_Functions][04] +- [about_Functions_Advanced_Parameters][03] +- [about_Scripts][05] +- [Writing Comment-Based help content][01] + + +[01]: /powershell/scripting/developer/help/writing-comment-based-help-topics +[02]: about_CommonParameters.md +[03]: about_Functions_Advanced_Parameters.md +[04]: about_Functions.md +[05]: about_Scripts.md +[06]: xref:Microsoft.PowerShell.Core.Get-Help +[07]: xref:Microsoft.PowerShell.Core.Save-Help +[08]: xref:Microsoft.PowerShell.Core.Update-Help +[09]: xref:Microsoft.PowerShell.Utility.Export-PSSession diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Data_Sections.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Data_Sections.md index 91f358464775..674b62cb835e 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Data_Sections.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Data_Sections.md @@ -1,7 +1,7 @@ --- description: Explains Data sections, which isolate text strings and other read-only data from script logic. Locale: en-US -ms.date: 04/23/2019 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_data_sections?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Data_Sections @@ -9,14 +9,15 @@ title: about_Data_Sections # about_Data_Sections ## Short description -Explains Data sections, which isolate text strings and other read-only + +Explains `DATA` sections, which isolate text strings and other read-only data from script logic. ## Long description -Scripts that are designed for PowerShell can have one or more Data sections -that contain only data. You can include one or more Data sections in any -script, function, or advanced function. The content of the Data section is +Scripts that are designed for PowerShell can have one or more `DATA` sections +that contain only data. You can include one or more `DATA` sections in any +script, function, or advanced function. The content of the `DATA` section is restricted to a specified subset of the PowerShell scripting language. Separating data from code logic makes it easier to identify and manage both @@ -24,24 +25,23 @@ logic and data. It lets you have separate string resource files for text, such as error messages and Help strings. It also isolates the code logic, which facilitates security and validation tests. -In PowerShell, the Data section is used to support script internationalization. -You can use Data sections to make it easier to isolate, locate, and process -strings that will be translated into many user interface (UI) languages. +In PowerShell, you can use the `DATA` section to support script +internationalization. You can use `DATA` sections to make it easier to isolate, +locate, and process strings that can be translated into other languages. -The Data section is a PowerShell 2.0 feature. Scripts with Data sections will -not run in PowerShell 1.0 without revision. +The `DATA` section was added in PowerShell 2.0 feature. ### Syntax -The syntax for a Data section is as follows: +The syntax for a `DATA` section is as follows: -``` +```Syntax DATA [] [-supportedCommand ] { } ``` -The Data keyword is required. It is not case-sensitive. The permitted content +The `DATA` keyword is required. It isn't case-sensitive. The permitted content is limited to the following elements: - All PowerShell operators, except `-match` @@ -65,28 +65,28 @@ is limited to the following elements: '@ ``` -- Cmdlets that are permitted in a Data section. By default, only the +- Cmdlets that are permitted in a `DATA` section. By default, only the `ConvertFrom-StringData` cmdlet is permitted. -- Cmdlets that you permit in a Data section by using the `-SupportedCommand` +- Cmdlets that you permit in a `DATA` section by using the `-SupportedCommand` parameter. -When you use the `ConvertFrom-StringData` cmdlet in a Data section, you can +When you use the `ConvertFrom-StringData` cmdlet in a `DATA` section, you can enclose the key-value pairs in single-quoted or double-quoted strings or in single-quoted or double-quoted here-strings. However, strings that contain variables and subexpressions must be enclosed in single-quoted strings or in -single-quoted here-strings so that the variables are not expanded and the -subexpressions are not executable. +single-quoted here-strings so that the variables aren't expanded and the +subexpressions aren't executable. ### -SupportedCommand -The `-SupportedCommand` parameter allows you to indicate that a cmdlet or -function generates only data. It is designed to allow users to include cmdlets -and functions in a data section that they have written or tested. +The **SupportedCommand** parameter allows you to indicate that a cmdlet or +function generates only data. It's designed to allow users to include cmdlets +and functions in a `DATA` section that they have written or tested. -The value of `-SupportedCommand` is a comma-separated list of one or more +The value of **SupportedCommand** is a comma-separated list of one or more cmdlet or function names. -For example, the following data section includes a user-written cmdlet, +For example, the following `DATA` section includes a user-written cmdlet, `Format-Xml`, that formats data in an XML file: ```powershell @@ -96,16 +96,16 @@ DATA -supportedCommand Format-Xml } ``` -### Using a Data Section +### Using a `DATA` Section -To use the content of a Data section, assign it to a variable and use variable +To use the content of a `DATA` section, assign it to a variable and use variable notation to access the content. -For example, the following data section contains a `ConvertFrom-StringData` +For example, the following `DATA` section contains a `ConvertFrom-StringData` command that converts the here-string into a hash table. The hash table is assigned to the `$TextMsgs` variable. -The `$TextMsgs` variable is not part of the data section. +The `$TextMsgs` variable isn't part of the `DATA` section. ```powershell $TextMsgs = DATA { @@ -124,7 +124,8 @@ $TextMsgs.Text001 $TextMsgs.Text002 ``` -Alternately, you can put the variable name in the definition of the Data section. For example: +Alternately, you can put the variable name in the definition of the `DATA` +section. For example: ```powershell DATA TextMsgs { @@ -200,12 +201,23 @@ DATA -supportedCommand Format-XML { ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_If](about_If.md) -- [about_Operators](about_Operators.md) -- [about_Quoting_Rules](about_Quoting_Rules.md) -- [about_Script_Internationalization](about_Script_Internationalization.md) -- [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData) -- [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData) +- [about_Automatic_Variables][01] +- [about_Comparison_Operators][02] +- [about_Hash_Tables][03] +- [about_If][04] +- [about_Operators][05] +- [about_Quoting_Rules][06] +- [about_Script_Internationalization][07] +- [ConvertFrom-StringData][08] +- [Import-LocalizedData][09] + + +[01]: about_Automatic_Variables.md +[02]: about_Comparison_Operators.md +[03]: about_Hash_Tables.md +[04]: about_If.md +[05]: about_Operators.md +[06]: about_Quoting_Rules.md +[07]: about_Script_Internationalization.md +[08]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData +[09]: xref:Microsoft.PowerShell.Utility.Import-LocalizedData diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md index 940c2a2a24a5..9f2aafddb756 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 03/30/2021 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -232,19 +232,17 @@ The RegexMatch options are: SimpleMatch. - **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit operator is specified. -- **CultureInvariant**: Ignores cultural differences in language - when evaluating the delimiter. Valid only with RegexMatch. -- **IgnorePatternWhitespace**: Ignores unescaped whitespace and - comments marked with the number sign (#). Valid only with - RegexMatch. -- **Multiline**: Multiline mode forces `^` and `$` to match the beginning - end of every line instead of the beginning and end of the input string. -- **Singleline**: Singleline mode treats the input string as a *SingleLine*. - It forces the `.` character to match every character (including newlines), +- **CultureInvariant**: Ignores cultural differences in language when + evaluating the delimiter. Valid only with RegexMatch. +- **IgnorePatternWhitespace**: Ignores unescaped whitespace and comments marked + with the hash character (`#`). Valid only with RegexMatch. +- **Multiline**: Multiline mode forces `^` and `$` to match the beginning end + of every line instead of the beginning and end of the input string. +- **Singleline**: Singleline mode treats the input string as a *SingleLine*. It + forces the `.` character to match every character (including newlines), instead of matching every character EXCEPT the newline `\n`. -- **ExplicitCapture**: Ignores non-named match groups so that only - explicit capture groups are returned in the result list. Valid - only with RegexMatch. +- **ExplicitCapture**: Ignores non-named match groups so that only explicit + capture groups are returned in the result list. Valid only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS diff --git a/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index 427855b35451..d92d29191707 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-stringdata?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertFrom-StringData @@ -15,8 +15,6 @@ Converts a string containing one or more key and value pairs to a hash table. ## SYNTAX -### All - ``` ConvertFrom-StringData [-StringData] [[-Delimiter] ] [] ``` @@ -38,7 +36,7 @@ machine translation tools. That is, the cmdlet can interpret backslashes (`\`) a in the string data by using the [Regex.Unescape Method](/dotnet/api/system.text.regularexpressions.regex.unescape), instead of the PowerShell backtick character (`` ` ``) that would normally signal the end of a line in a script. -Inside the here-string, the backtick character does not work. You can also preserve a literal +Inside the here-string, the backtick character doesn't work. You can also preserve a literal backslash in your results by escaping it with a preceding backslash, like this: `\\`. Unescaped backslash characters, such as those that are commonly used in file paths, can render as illegal escape sequences in your results. @@ -50,14 +48,14 @@ PowerShell 7 adds the **Delimiter** parameter. ### Example 1: Convert a single-quoted here-string to a hash table This example converts a single-quoted here-string of user messages into a hash table. In a -single-quoted string, values are not substituted for variables and expressions are not evaluated. +single-quoted string, values aren't substituted for variables and expressions aren't evaluated. The `ConvertFrom-StringData` cmdlet converts the value in the `$Here` variable to a hash table. ```powershell $Here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. -Msg3 = The specified variable does not exist. +Msg3 = The specified variable doesn't exist. '@ ConvertFrom-StringData -StringData $Here ``` @@ -65,7 +63,7 @@ ConvertFrom-StringData -StringData $Here ```Output Name Value ---- ----- -Msg3 The specified variable does not exist. +Msg3 The specified variable doesn't exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. ``` @@ -121,8 +119,8 @@ Name Disks.ps1 The value of the **StringData** parameter is a here-string, instead of a variable that contains a here-string. Either format is valid. The here-string includes a comment about one of the strings. -`ConvertFrom-StringData` ignores single-line comments, but the `#` character must be the first -non-whitespace character on the line. All characters on the line after the `#` are ignored. +`ConvertFrom-StringData` ignores single-line comments, but the hash character (`#`) must be the +first non-whitespace character on the line. ### Example 4: Convert a string to a hash table @@ -144,9 +142,9 @@ Top Red To satisfy the condition that each key-value pair must be on a separate line, the string uses the PowerShell newline character (`` `n ``) to separate the pairs. -### Example 5: Use ConvertFrom-StringData in the DATA section of a script +### Example 5: Use in the `DATA` section of a script -This example shows a `ConvertFrom-StringData` command used in the **DATA** section of a script. +This example shows a `ConvertFrom-StringData` command used in the `DATA` section of a script. The statements below the **DATA** section display the text to the user. ```powershell @@ -167,7 +165,7 @@ Text002 The $MyNotebook variable contains the name of the user's privat ``` Because the text includes variable names, it must be enclosed in a single-quoted string so that the -variables are interpreted literally and not expanded. Variables are not permitted in the **DATA** +variables are interpreted literally and not expanded. Variables aren't permitted in the `DATA` section. ### Example 6: Use the pipeline operator to pass a string @@ -180,7 +178,7 @@ and the result in the `$Hash` variable. $Here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. -Msg3 = The specified variable does not exist. +Msg3 = The specified variable doesn't exist. '@ $Hash = $Here | ConvertFrom-StringData $Hash @@ -189,7 +187,7 @@ $Hash ```Output Name Value ---- ----- -Msg3 The specified variable does not exist. +Msg3 The specified variable doesn't exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. ``` @@ -197,7 +195,7 @@ Msg1 The string parameter is required. ### Example 7: Use escape characters to add new lines and return characters This example shows the use of escape characters to create new lines and return characters in source -data. The escape sequence `\n` is used to create new lines within a block of text that is associated +data. The escape sequence `\n` is used to create new lines within a block of text that's associated with a name or item in the resulting hash table. ```powershell @@ -216,7 +214,7 @@ Value : Let there be some more test made of my metal, Name : Vincentio Value : Heaven doth with us as we with torches do, Not light them for themselves; for if our virtues - Did not go forth of us, 'twere all alike + Didn't go forth of us, 'twere all alike As if we had them not. ``` @@ -264,10 +262,10 @@ The value of this parameter must be a string that contains one or more key-value key-value pair must be on a separate line, or each pair must be separated by newline characters (`` `n ``). -You can include comments in the string, but the comments cannot be on the same line as a key-value -pair. `ConvertFrom-StringData` ignores single-line comments. The `#` character must be the first -non-whitespace character on the line. All characters on the line after the `#` are ignored. The -comments are not included in the hash table. +You can include comments in the string, but the comments can't be on the same line as a key-value +pair. `ConvertFrom-StringData` ignores single-line comments. The hash character (`#`) must be the +first non-whitespace character on the line. All characters on the line after the hash character +(`#`) are ignored. The comments aren't included in the hash table. A here-string is a string consisting of one or more lines. Quotation marks within the here-string are interpreted literally as part of the string data. For more information, see diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Export-Alias.md b/reference/7.4/Microsoft.PowerShell.Utility/Export-Alias.md index b12f39b3add0..9e8248bf084a 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Export-Alias.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Export-Alias.md @@ -18,23 +18,27 @@ Exports information about currently defined aliases to a file. ### ByPath (Default) ``` -Export-Alias [-Path] [[-Name] ] [-PassThru] [-As ] [-Append] [-Force] - [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] [] +Export-Alias [-Path] [[-Name] ] [-PassThru] [-As ] [-Append] + [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] + [] ``` ### ByLiteralPath ``` -Export-Alias -LiteralPath [[-Name] ] [-PassThru] [-As ] [-Append] - [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] [] +Export-Alias -LiteralPath [[-Name] ] [-PassThru] [-As ] + [-Append] [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] + [] ``` ## DESCRIPTION -The `Export-Alias` cmdlet exports the aliases in the current session to a file. -If the output file does not exist, the cmdlet will create it. +The `Export-Alias` cmdlet exports the aliases in the current session to a file. If the output file +does not exist, the cmdlet will create it. -`Export-Alias` can export the aliases in a particular scope or all scopes, it can generate the data in CSV format or as a series of Set-Alias commands that you can add to a session or to a PowerShell profile. +`Export-Alias` can export the aliases in a particular scope or all scopes, it can generate the data +in CSV format or as a series of Set-Alias commands that you can add to a session or to a PowerShell +profile. ## EXAMPLES @@ -54,7 +58,8 @@ Export-Alias -Path "alias.csv" -NoClobber This command exports the aliases in the current session to an Alias.csv file. -Because the **NoClobber** parameter is specified, the command will fail if an Alias.csv file already exists in the current directory. +Because the **NoClobber** parameter is specified, the command will fail if an Alias.csv file already +exists in the current directory. ### Example 3: Append aliases to a file @@ -64,9 +69,11 @@ Export-Alias -Path "alias.csv" -Append -Description "Appended Aliases" -Force This command appends the aliases in the current session to the Alias.csv file. -The command uses the **Description** parameter to add a description to the comments at the top of the file. +The command uses the **Description** parameter to add a description to the comments at the top of +the file. -The command also uses the **Force** parameter to overwrite any existing Alias.csv files, even if they have the read-only attribute. +The command also uses the **Force** parameter to overwrite any existing Alias.csv files, even if +they have the read-only attribute. ### Example 4: Export aliases as a script @@ -79,23 +86,27 @@ Invoke-Command -Session $S -FilePath .\alias.ps1 This example shows how to use the script file format that `Export-Alias` generates. -The first command exports the aliases in the session to the Alias.ps1 file. -It uses the **As** parameter with a value of Script to generate a file that contains a Set-Alias command for each alias. +The first command exports the aliases in the session to the Alias.ps1 file. It uses the **As** +parameter with a value of Script to generate a file that contains a Set-Alias command for each +alias. The second command adds the aliases in the Alias.ps1 file to the CurrentUser-CurrentHost profile. -The path to the profile is saved in the `$Profile` variable. -The command uses the `Get-Content` cmdlet to get the aliases from the Alias.ps1 file and the `Add-Content` cmdlet to add them to the profile. -For more information, see [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). +The path to the profile is saved in the `$Profile` variable. The command uses the `Get-Content` +cmdlet to get the aliases from the Alias.ps1 file and the `Add-Content` cmdlet to add them to the +profile. For more information, see +[about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). -The third and fourth commands add the aliases in the Alias.ps1 file to a remote session on the Server01 computer. -The third command uses the `New-PSSession` cmdlet to create the session. -The fourth command uses the **FilePath** parameter of the `Invoke-Command` cmdlet to run the Alias.ps1 file in the new session. +The third and fourth commands add the aliases in the Alias.ps1 file to a remote session on the +Server01 computer. The third command uses the `New-PSSession` cmdlet to create the session. The +fourth command uses the **FilePath** parameter of the `Invoke-Command` cmdlet to run the Alias.ps1 +file in the new session. ## PARAMETERS ### -Append -Indicates that this cmdlet appends the output to the specified file, rather than overwriting the existing contents of that file. +Indicates that this cmdlet appends the output to the specified file, rather than overwriting the +existing contents of that file. ```yaml Type: System.Management.Automation.SwitchParameter @@ -115,11 +126,9 @@ Specifies the output format. CSV is the default. The acceptable values for this parameter are: -- CSV. -Comma-separated value (CSV) format. -- Script. -Creates a `Set-Alias` command for each exported alias. -If you name the output file with a .ps1 file name extension, you can run it as a script to add the aliases to any session. +- CSV. Comma-separated value (CSV) format. +- Script. Creates a `Set-Alias` command for each exported alias. If you name the output file with a + .ps1 file name extension, you can run it as a script to add the aliases to any session. ```yaml Type: Microsoft.PowerShell.Commands.ExportAliasFormat @@ -136,8 +145,8 @@ Accept wildcard characters: False ### -Description -Specifies the description of the exported file. -The description appears as a comment at the top of the file, following the header information. +Specifies the description of the exported file. The description appears as a comment at the top of +the file, following the header information. ```yaml Type: System.String @@ -157,8 +166,9 @@ Forces the command to run without asking for user confirmation. Overwrites the output file, even if the read-only attribute is set on the file. -By default, `Export-Alias` overwrites files without warning, unless the read-only or hidden attribute is set or the **NoClobber** parameter is used in the command. -The **NoClobber** parameter takes precedence over the **Force** parameter when both are used in a command. +By default, `Export-Alias` overwrites files without warning, unless the read-only or hidden +attribute is set or the **NoClobber** parameter is used in the command. The **NoClobber** parameter +takes precedence over the **Force** parameter when both are used in a command. The **Force** parameter cannot force `Export-Alias` to overwrite files with the hidden attribute. @@ -176,11 +186,10 @@ Accept wildcard characters: False ### -LiteralPath -Specifies the path to the output file. -Unlike **Path**, the value of the **LiteralPath** parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +Specifies the path to the output file. Unlike **Path**, the value of the **LiteralPath** parameter +is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes +escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not +to interpret any characters as escape sequences. ```yaml Type: System.String @@ -196,8 +205,7 @@ Accept wildcard characters: False ### -Name -Specifies the names as an array of the aliases to export. -Wildcards are permitted. +Specifies the names as an array of the aliases to export. Wildcards are permitted. By default, `Export-Alias` exports all aliases in the session or scope. @@ -215,12 +223,14 @@ Accept wildcard characters: True ### -NoClobber -Indicates that this cmdlet prevents `Export-Alias` from overwriting any files, even if the **Force** parameter is used in the command. +Indicates that this cmdlet prevents `Export-Alias` from overwriting any files, even if the **Force** +parameter is used in the command. -If the **NoClobber** parameter is omitted, `Export-Alias` will overwrite an existing file without warning, unless the read-only attribute is set on the file. -*NoClobber* takes precedence over the **Force** parameter, which permits `Export-Alias` to overwrite a file with the read-only attribute. +If the **NoClobber** parameter is omitted, `Export-Alias` will overwrite an existing file without +warning, unless the read-only attribute is set on the file. **NoClobber** takes precedence over the +**Force** parameter, which permits `Export-Alias` to overwrite a file with the read-only attribute. -*NoClobber* does not prevent the **Append** parameter from adding content to an existing file. +**NoClobber** does not prevent the **Append** parameter from adding content to an existing file. ```yaml Type: System.Management.Automation.SwitchParameter @@ -236,8 +246,8 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the item with which you are working. -By default, this cmdlet does not generate any output. +Returns an object representing the item with which you are working. By default, this cmdlet does not +generate any output. ```yaml Type: System.Management.Automation.SwitchParameter @@ -253,8 +263,8 @@ Accept wildcard characters: False ### -Path -Specifies the path to the output file. -Wildcards are permitted, but the resulting path value must resolve to a single file name. +Specifies the path to the output file. Wildcards are permitted, but the resulting path value must +resolve to a single file name. ```yaml Type: System.String @@ -270,16 +280,17 @@ Accept wildcard characters: True ### -Scope -Specifies the scope from which the aliases should be exported. -The acceptable values for this parameter are: +Specifies the scope from which the aliases should be exported. The acceptable values for this +parameter are: -- Global -- Local -- Script -- A number relative to the current scope (0 through the number of scopes where 0 is the current scope and 1 is its parent) +- `Global` +- `Local` +- `Script` +- A number relative to the current scope (0 through the number of scopes where 0 is the current + scope and 1 is its parent) -The default value is Local. -For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). +The default value is `Local`. For more information, see +[about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). ```yaml Type: System.String @@ -328,7 +339,10 @@ 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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md b/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md index 9ca2e5c43db7..372a68495796 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 03/15/2023 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/import-csv?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Import-Csv @@ -56,7 +56,7 @@ delimiter. You can also use the `ConvertTo-Csv` and `ConvertFrom-Csv` cmdlets to convert objects to CSV strings (and back). These cmdlets are the same as the `Export-CSV` and `Import-Csv` cmdlets, except -that they do not deal with files. +that they work with data from the pipeline instead of from files. If a header row entry in a CSV file contains an empty or null value, PowerShell inserts a default header row name and displays a warning message. @@ -260,7 +260,7 @@ objects are stored in the `$A` variable. The `Get-Member` cmdlet shows the prope **Header** parameter. The `Where-Object` cmdlet selects objects with the **TopicTitle** property that includes **alias**. -### Example 6: Import a CSV that is missing a value +### Example 6: Import a CSV that's missing a value This example shows how the `Import-Csv` cmdlet in PowerShell responds when the header row in a CSV file includes a null or empty value. `Import-Csv` substitutes a default name for the missing header @@ -282,7 +282,7 @@ Import-Csv -Path .\Projects.csv ``` ```Output -WARNING: One or more headers were not specified. Default names starting with "H" have been used in +WARNING: One or more headers weren't specified. Default names starting with "H" have been used in place of any missing headers. ProjectID ProjectName H1 Completed @@ -292,24 +292,9 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` -```powershell -(Import-Csv -Path .\Projects.csv).H1 -``` - -```Output -WARNING: One or more headers were not specified. Default names starting with "H" have been used in -place of any missing headers. -Redmond -FarEast -Europe -``` - -To create your Projects.csv file, use the values shown in the example's `Get-Content` output. - -The `Get-Content` cmdlet displays the Projects.csv file. The header row is missing a value between -**ProjectName** and **Completed**. The `Import-Csv` cmdlet imports the Projects.csv file and -displays a warning message because **H1** is a default header name. The `(Import-Csv -Path -.\Projects.csv).H1` command gets the **H1** property values and displays a warning. +The `Get-Content` cmdlet displays the `Projects.csv` file. The header row is missing a value between +**ProjectName** and **Completed**. The `Import-Csv` cmdlet imports the `Projects.csv` file and +displays a warning message because **H1** is a default header name. ## PARAMETERS @@ -322,8 +307,8 @@ Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose i quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double quotation marks. -If you specify a character other than the actual string delimiter in the file, `Import-Csv` cannot -create the objects from the CSV strings and will return the CSV strings. +If you specify a character other than the actual string delimiter in the file, `Import-Csv` can't +create the objects from the CSV strings and returns the full CSV strings. ```yaml Type: System.Char @@ -386,7 +371,7 @@ Accept wildcard characters: False Specifies an alternate column header row for the imported file. The column header determines the property names of the objects created by `Import-Csv`. -Enter column headers as a character-separated list. Do not enclose the header string in quotation +Enter column headers as a character-separated list. Don't enclose the header string in quotation marks. Enclose each column header in single quotation marks. If you enter fewer column headers than there are data columns, the remaining data columns are @@ -411,7 +396,7 @@ Accept wildcard characters: False ### -LiteralPath Specifies the path to the CSV file to import. Unlike **Path**, the value of the **LiteralPath** -parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path +parameter is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -487,7 +472,7 @@ PowerShell includes the following aliases for `Import-Csv`: - All platforms: - `ipcsv` -Because the imported objects are CSV versions of the object type, they are not recognized and +Because the imported objects are CSV versions of the object type, they're not recognized and formatted by the PowerShell type formatting entries that format the non-CSV versions of the object type. @@ -506,13 +491,13 @@ If the column header row is missing a value or contains a null or empty value, ` In the CSV file, each object is represented by a character-separated list of the property values of the object. The property values are converted to strings by using the **ToString()** method of the -object, so they are represented by the name of the property value. `Export-Csv` does not export the +object, so they're represented by the name of the property value. `Export-Csv` doesn't export the methods of the object. -`Import-Csv` also supports the W3C Extended Log format. Lines starting with `#` are treated as -comments and ignored unless the comment starts with `#Fields:` and contains delimited list of column -names. In that case, the cmdlet uses those column names. This is the standard format for Windows IIS -and other web server logs. For more information, see +`Import-Csv` also supports the W3C Extended Log format. Lines starting with the hash character (`#`) +are treated as comments and ignored unless the comment starts with `#Fields:` and contains delimited +list of column names. In that case, the cmdlet uses those column names. This is the standard format +for Windows IIS and other web server logs. For more information, see [Extended Log File Format](https://www.w3.org/TR/WD-logfile.html). ## RELATED LINKS diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index dc02ac212b81..ba9bb52e92cc 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -1,7 +1,7 @@ --- -description: Describes how to write comment-based help topics for functions and scripts. +description: Describes how to write comment-based help content for functions and scripts. Locale: en-US -ms.date: 07/05/2022 +ms.date: 01/09/2025 no-loc: [.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, .INPUTS, .OUTPUTS, .NOTES, .LINK, .COMPONENT, .ROLE, .FUNCTIONALITY, .FORWARDHELPTARGETNAME, .FORWARDHELPCATEGORY, .REMOTEHELPRUNSPACE, .EXTERNALHELP] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -10,48 +10,49 @@ title: about_Comment_Based_Help # about_Comment_Based_Help ## Short description - -Describes how to write comment-based help topics for functions and scripts. +Describes how to write comment-based help content for functions and scripts. ## Long description -You can write comment-based help topics for functions and scripts by using +You can write comment-based help content for functions and scripts by using special help comment keywords. -The [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) cmdlet displays -comment-based help in the same format in which it displays the cmdlet help -topics that are generated from XML files. Users can use all of the parameters -of `Get-Help`, such as **Detailed**, **Full**, **Examples**, and **Online**, to -display the contents of comment-based help. +The [Get-Help][06] cmdlet displays comment-based help in the same format in +which it displays the cmdlet help content that are generated from XML files. +Users can use all of the parameters of `Get-Help`, such as **Detailed**, +**Full**, **Examples**, and **Online**, to display the contents of +comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function or script, -use the `.ExternalHelp` keyword. Without this keyword, `Get-Help` cannot find -XML-based help topics for functions or scripts. +use the `.EXTERNALHELP` keyword. Without this keyword, `Get-Help` can't find +XML-based help content for functions or scripts. -This topic explains how to write help topics for functions and scripts. For -information about how to display help topics for functions and scripts, see -[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help). +This topic explains how to write help content for functions and scripts. For +information about how to display help content for functions and scripts, see +[Get-Help][06]. -The [Update-Help](xref:Microsoft.PowerShell.Core.Update-Help) and -[Save-Help](xref:Microsoft.PowerShell.Core.Save-Help) cmdlets work only on XML -files. Updatable Help does not support comment-based help topics. +The [Update-Help][08] and [Save-Help][07] cmdlets work only on XML files. +Updatable Help doesn't support comment-based help content. ## Syntax for comment-based help +To create Comment-based help content, you can use either style of comments: +single-line comments or block comments. + The syntax for comment-based help is as follows: -``` +```Syntax # . # ``` or -``` +```Syntax <# -. - + . + #> ``` @@ -61,26 +62,26 @@ symbols to create a comment block. All the lines within the comment block are interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a -comment-based help topic follows a comment that is not part of the help -topic, there must be at least one blank line between the last non-help -comment line and the beginning of the comment-based help. +comment-based help topic follows a comment that's not part of the help topic, +there must be at least one blank line between the last non-help comment line +and the beginning of the comment-based help. Keywords define each section of comment-based help. Each comment-based help keyword is preceded by a dot `.`. The keywords can appear in any order. The -keyword names are not case-sensitive. +keyword names aren't case-sensitive. For example, the `.Description` keyword precedes a description of a function or script. -``` +```powershell <# .Description Get-Function displays the name and syntax of all functions in the session. #> ``` -The comment block must contain at least one keyword. Some of the keywords, -such as `.EXAMPLE`, can appear many times in the same comment block. The help +The comment block must contain at least one keyword. Some of the keywords, such +as `.EXAMPLE`, can appear many times in the same comment block. The help content for each keyword begins on the line after the keyword and can span multiple lines. @@ -90,34 +91,32 @@ Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - At the end of the function body. -- Before the `function` keyword. There cannot be more than one blank line +- Before the `function` keyword. There can't be more than one blank line between the last line of the function help and the `function` keyword. For example: ```powershell -function Get-Function -{ -<# -. - -#> +function Get-Function { + <# + . + + #> - # function logic + # function logic } ``` or ```powershell -function Get-Function -{ - # function logic +function Get-Function { + # function logic -<# -. - -#> + <# + . + + #> } ``` @@ -125,8 +124,8 @@ or ```powershell <# -. - + . + #> function Get-Function { } ``` @@ -155,8 +154,6 @@ For example: . #> - - function Get-Function { } ``` @@ -164,37 +161,18 @@ or ```powershell function Get-Function { } - <# . #> ``` -## Syntax for comment-based help in script modules - -In a script module `.psm1`, comment-based help uses the syntax for functions, -not the syntax for scripts. You cannot use the script syntax to provide help -for all functions defined in a script module. - -For example, if you are using the `.ExternalHelp` keyword to identify the -XML-based help files for the functions in a script module, you must add an -`.ExternalHelp` comment to each function. - -```powershell -# .ExternalHelp -function -{ - ... -} -``` - ## Comment-based help keywords -The following are valid comment-based help keywords. They are listed in the -order in which they typically appear in a help topic along with their intended -use. These keywords can appear in any order in the comment-based help, and -they are not case-sensitive. +The following are valid comment-based help keywords. These keywords can appear +in any order in the comment-based help, and they aren't case-sensitive. The +keywords are listed in in this article inthe order that they typically appear +in a help topic. ### .SYNOPSIS @@ -217,7 +195,7 @@ PowerShell interprets all text between the `.PARAMETER` line and the next keyword or the end of the comment block as part of the parameter description. The description can include paragraph breaks. -``` +```Syntax .PARAMETER ``` @@ -286,7 +264,7 @@ when you use the **Online** parameter of `Get-Help`. The URI must begin with ### .COMPONENT The name of the technology or feature that the function or script uses, or to -which it is related. The **Component** parameter of `Get-Help` uses this value +which it's related. The **Component** parameter of `Get-Help` uses this value to filter the search results returned by `Get-Help`. ### .ROLE @@ -303,7 +281,7 @@ results returned by `Get-Help`. ### .FORWARDHELPTARGETNAME Redirects to the help topic for the specified command. You can redirect users -to any help topic, including help topics for a function, script, cmdlet, or +to any help topic, including help content for a function, script, cmdlet, or provider. ```powershell @@ -325,8 +303,8 @@ this keyword to avoid conflicts when there are commands with the same name. Specifies a session that contains the help topic. Enter a variable that contains a **PSSession** object. This keyword is used by the -[Export-PSSession](xref:Microsoft.PowerShell.Utility.Export-PSSession) -cmdlet to find the help topics for the exported commands. +[Export-PSSession][09] cmdlet to find the help content for the exported +commands. ```powershell # .REMOTEHELPRUNSPACE @@ -340,26 +318,26 @@ Specifies an XML-based help file for the script or function. # .EXTERNALHELP ``` -The `.ExternalHelp` keyword is required when a function or script is documented -in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +The `.EXTERNALHELP` keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` can't find the XML-based help file for the function or script. -The `.ExternalHelp` keyword takes precedence over other comment-based help -keywords. If `.ExternalHelp` is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches the value -of the `.ExternalHelp` keyword. +The `.EXTERNALHELP` keyword takes precedence over other comment-based help +keywords. If `.EXTERNALHELP` is present, `Get-Help` doesn't display +comment-based help, even if it can't find a help topic that matches the value +of the `.EXTERNALHELP` keyword. -If the function is exported by a module, set the value of the `.ExternalHelp` +If the function is exported by a module, set the value of the `.EXTERNALHELP` keyword to a filename without a path. `Get-Help` looks for the specified file name in a language-specific subdirectory of the module directory. There are no requirements for the name of the XML-based help file for a function, but a best practice is to use the following format: -``` +```Syntax -help.xml ``` -If the function is not included in a module, include a path to the XML-based +If the function isn't included in a module, include a path to the XML-based help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in @@ -367,42 +345,42 @@ accordance with the language fallback standards established for Windows, just as it does in a module directory. For more information about the cmdlet help XML-based help file format, see -[How to Write Cmdlet Help](/powershell/scripting/developer/help/writing-comment-based-help-topics). +[How to Write Cmdlet Help][01]. ## Autogenerated content -The name, syntax, parameter list, parameter attribute table, common -parameters, and remarks are automatically generated by the `Get-Help` cmdlet. +The name, syntax, parameter list, parameter attribute table, common parameters, +and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The **Name** section of a function help topic is taken from the function name in -the function syntax. The **Name** of a script help topic is taken from the -script filename. To change the name or its capitalization, change the -function syntax or the script filename. +The **Name** section of a function help topic is taken from the function name +in the function syntax. The **Name** of a script help topic is taken from the +script filename. To change the name or its capitalization, change the function +syntax or the script filename. ### Syntax The **Syntax** section of the help topic is generated from the function or script syntax. To add detail to the help topic syntax, such as the .NET type of -a parameter, add the detail to the syntax. If you do not specify a parameter +a parameter, add the detail to the syntax. If you don't specify a parameter type, the **Object** type is inserted as the default value. ### Parameter List -The parameter list in the help topic is generated from the function or -script syntax and from the descriptions that you add by using the `.Parameter` +The parameter list in the help topic is generated from the function or script +syntax and from the descriptions that you add by using the `.Parameter` keyword. The function parameters appear in the **Parameters** section of the -help topic in the same order that they appear in the function or script -syntax. The spelling and capitalization of parameter names is also taken from -the syntax. It is not affected by the parameter name specified by the -`.Parameter` keyword. +help topic in the same order that they appear in the function or script syntax. +The spelling and capitalization of parameter names is also taken from the +syntax. It isn't affected by the parameter name specified by the `.Parameter` +keyword. ### Common Parameters -The **Common parameters** are added to the syntax and parameter list of the help -topic, even if they have no effect. For more information about the common -parameters, see [about_CommonParameters](about_CommonParameters.md). +The **Common parameters** are added to the syntax and parameter list of the +help topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters][02]. ### Parameter Attribute Table @@ -411,14 +389,14 @@ use the **Full** or **Parameter** parameter of `Get-Help`. The value of the **Required**, **Position**, and **Default** value attributes is taken from the function or script syntax. -Default values and a value for **Accept Wildcard characters** do not appear in -the parameter attribute table even when they are defined in the function or +Default values and a value for **Accept Wildcard characters** don't appear in +the parameter attribute table even when they're defined in the function or script. To help users, provide this information in the parameter description. ### Remarks The **Remarks** section of the help topic is automatically generated from the -function or script name. You cannot change or affect its content. +function or script name. You can't change or affect its content. ## Examples @@ -451,7 +429,7 @@ Specifies the extension. "Txt" is the default. .INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. .OUTPUTS @@ -536,7 +514,7 @@ This cmdlet supports the common parameters: -Verbose, -Debug, "get-help about_commonparameters". INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. OUTPUTS @@ -600,7 +578,7 @@ file name or extension. .INPUTS -None. You cannot pipe objects to Add-Extension. +None. You can't pipe objects to Add-Extension. .OUTPUTS @@ -636,7 +614,7 @@ Set-Item ### Comment-based Help for a Script The following sample script includes comment-based help. Notice the blank lines -between the closing `#>` and the `Param` statement. In a script that does not +between the closing `#>` and the `Param` statement. In a script that doesn't have a `Param` statement, there must be at least two blank lines between the final comment in the help topic and the first function declaration. Without these blank lines, `Get-Help` associates the help topic with the function, not @@ -663,11 +641,11 @@ saves the output in the local directory. .INPUTS -None. You cannot pipe objects to Update-Month.ps1. +None. You can't pipe objects to Update-Month.ps1. .OUTPUTS -None. Update-Month.ps1 does not generate any output. +None. Update-Month.ps1 doesn't generate any output. .EXAMPLE @@ -675,11 +653,11 @@ PS> .\Update-Month.ps1 .EXAMPLE -PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -outputPath ` +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` C:\Reports\2009\January.csv #> @@ -689,8 +667,8 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not in a -directory that is listed in the `$env:Path` environment variable, the +The following command gets the script help. Because the script isn't in a +directory that's listed in the `$env:Path` environment variable, the `Get-Help` command that gets the script help must specify the script path. ```powershell @@ -746,11 +724,11 @@ This cmdlet supports the common parameters: -Verbose, -Debug, # INPUTS -None. You cannot pipe objects to Update-Month.ps1. +None. You can't pipe objects to Update-Month.ps1. # OUTPUTS -None. Update-Month.ps1 does not generate any output. +None. Update-Month.ps1 doesn't generate any output. Example 1 @@ -770,57 +748,54 @@ C:\Reports\2009\January.csv ### Redirecting to an XML File -You can write XML-based help topics for functions and scripts. Although +You can write XML-based help content for functions and scripts. Although comment-based help is easier to implement, XML-based help is required for -Updatable Help and to provide help topics in multiple languages. +Updatable Help and to provide help content in multiple languages. The following example shows the first few lines of the Update-Month.ps1 script. -The script uses the `.ExternalHelp` keyword to specify the path to an XML-based +The script uses the `.EXTERNALHELP` keyword to specify the path to an XML-based help topic for the script. -Note that the value of the `.ExternalHelp` keyword appears on the same -line as the keyword. Any other placement is ineffective. +Note that the value of the `.EXTERNALHELP` keyword appears on the same line as +the keyword. Any other placement is ineffective. ```powershell -# .ExternalHelp C:\MyScripts\Update-Month-Help.xml +# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml param ([string]$InputPath, [string]$OutPutPath) function Get-Data { } ... ``` -The following examples show three valid placements of the `.ExternalHelp` +The following examples show three valid placements of the `.EXTERNALHELP` keyword in a function. ```powershell -function Add-Extension -{ -# .ExternalHelp C:\ps-test\Add-Extension.xml +function Add-Extension { + # .EXTERNALHELP C:\ps-test\Add-Extension.xml -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name } ``` ```powershell -function Add-Extension -{ -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name +function Add-Extension { + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name -# .ExternalHelp C:\ps-test\Add-Extension.xml + # .EXTERNALHELP C:\ps-test\Add-Extension.xml } ``` ```powershell -# .ExternalHelp C:\ps-test\Add-Extension.xml -function Add-Extension -{ -param ([string] $name, [string]$extension = "txt") -$name = $name + "." + $extension -$name +# .EXTERNALHELP C:\ps-test\Add-Extension.xml +function Add-Extension { + param ([string] $name, [string]$extension = "txt") + $name = $name + "." + $extension + $name } ``` @@ -833,19 +808,18 @@ the help function uses the `.ForwardHelpTargetName` and `.ForwardHelpCategory` keywords to redirect the user to the `Get-Help` cmdlet help topic. ```powershell -function help -{ +function help { + <# + .FORWARDHELPTARGETNAME Get-Help + .FORWARDHELPCATEGORY Cmdlet + #> -<# -.FORWARDHELPTARGETNAME Get-Help -.FORWARDHELPCATEGORY Cmdlet -#> -[CmdletBinding(DefaultParameterSetName='AllUsersView')] -param( -[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)] -[System.String] -${Name}, -... + [CmdletBinding(DefaultParameterSetName='AllUsersView')] + param( + [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)] + [System.String] + ${Name}, + ... ``` The following command uses this feature: @@ -867,7 +841,18 @@ Displays information about PowerShell cmdlets and concepts. ## See also -- [about_Functions](about_Functions.md) -- [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) -- [about_Scripts](about_Scripts.md) -- [Writing Comment-Based Help Topics](/powershell/scripting/developer/help/writing-comment-based-help-topics) +- [about_Functions][04] +- [about_Functions_Advanced_Parameters][03] +- [about_Scripts][05] +- [Writing Comment-Based help content][01] + + +[01]: /powershell/scripting/developer/help/writing-comment-based-help-topics +[02]: about_CommonParameters.md +[03]: about_Functions_Advanced_Parameters.md +[04]: about_Functions.md +[05]: about_Scripts.md +[06]: xref:Microsoft.PowerShell.Core.Get-Help +[07]: xref:Microsoft.PowerShell.Core.Save-Help +[08]: xref:Microsoft.PowerShell.Core.Update-Help +[09]: xref:Microsoft.PowerShell.Utility.Export-PSSession diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Data_Sections.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Data_Sections.md index f285108e5225..24b3450c5489 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Data_Sections.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Data_Sections.md @@ -1,7 +1,7 @@ --- description: Explains Data sections, which isolate text strings and other read-only data from script logic. Locale: en-US -ms.date: 04/23/2019 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_data_sections?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Data_Sections @@ -10,14 +10,14 @@ title: about_Data_Sections ## Short description -Explains Data sections, which isolate text strings and other read-only +Explains `DATA` sections, which isolate text strings and other read-only data from script logic. ## Long description -Scripts that are designed for PowerShell can have one or more Data sections -that contain only data. You can include one or more Data sections in any -script, function, or advanced function. The content of the Data section is +Scripts that are designed for PowerShell can have one or more `DATA` sections +that contain only data. You can include one or more `DATA` sections in any +script, function, or advanced function. The content of the `DATA` section is restricted to a specified subset of the PowerShell scripting language. Separating data from code logic makes it easier to identify and manage both @@ -25,24 +25,23 @@ logic and data. It lets you have separate string resource files for text, such as error messages and Help strings. It also isolates the code logic, which facilitates security and validation tests. -In PowerShell, the Data section is used to support script internationalization. -You can use Data sections to make it easier to isolate, locate, and process -strings that will be translated into many user interface (UI) languages. +In PowerShell, you can use the `DATA` section to support script +internationalization. You can use `DATA` sections to make it easier to isolate, +locate, and process strings that can be translated into other languages. -The Data section is a PowerShell 2.0 feature. Scripts with Data sections will -not run in PowerShell 1.0 without revision. +The `DATA` section was added in PowerShell 2.0 feature. ### Syntax -The syntax for a Data section is as follows: +The syntax for a `DATA` section is as follows: -``` +```Syntax DATA [] [-supportedCommand ] { } ``` -The Data keyword is required. It is not case-sensitive. The permitted content +The `DATA` keyword is required. It isn't case-sensitive. The permitted content is limited to the following elements: - All PowerShell operators, except `-match` @@ -66,28 +65,28 @@ is limited to the following elements: '@ ``` -- Cmdlets that are permitted in a Data section. By default, only the +- Cmdlets that are permitted in a `DATA` section. By default, only the `ConvertFrom-StringData` cmdlet is permitted. -- Cmdlets that you permit in a Data section by using the `-SupportedCommand` +- Cmdlets that you permit in a `DATA` section by using the `-SupportedCommand` parameter. -When you use the `ConvertFrom-StringData` cmdlet in a Data section, you can +When you use the `ConvertFrom-StringData` cmdlet in a `DATA` section, you can enclose the key-value pairs in single-quoted or double-quoted strings or in single-quoted or double-quoted here-strings. However, strings that contain variables and subexpressions must be enclosed in single-quoted strings or in -single-quoted here-strings so that the variables are not expanded and the -subexpressions are not executable. +single-quoted here-strings so that the variables aren't expanded and the +subexpressions aren't executable. ### -SupportedCommand -The `-SupportedCommand` parameter allows you to indicate that a cmdlet or -function generates only data. It is designed to allow users to include cmdlets -and functions in a data section that they have written or tested. +The **SupportedCommand** parameter allows you to indicate that a cmdlet or +function generates only data. It's designed to allow users to include cmdlets +and functions in a `DATA` section that they have written or tested. -The value of `-SupportedCommand` is a comma-separated list of one or more +The value of **SupportedCommand** is a comma-separated list of one or more cmdlet or function names. -For example, the following data section includes a user-written cmdlet, +For example, the following `DATA` section includes a user-written cmdlet, `Format-Xml`, that formats data in an XML file: ```powershell @@ -97,16 +96,16 @@ DATA -supportedCommand Format-Xml } ``` -### Using a Data Section +### Using a `DATA` Section -To use the content of a Data section, assign it to a variable and use variable +To use the content of a `DATA` section, assign it to a variable and use variable notation to access the content. -For example, the following data section contains a `ConvertFrom-StringData` +For example, the following `DATA` section contains a `ConvertFrom-StringData` command that converts the here-string into a hash table. The hash table is assigned to the `$TextMsgs` variable. -The `$TextMsgs` variable is not part of the data section. +The `$TextMsgs` variable isn't part of the `DATA` section. ```powershell $TextMsgs = DATA { @@ -125,7 +124,8 @@ $TextMsgs.Text001 $TextMsgs.Text002 ``` -Alternately, you can put the variable name in the definition of the Data section. For example: +Alternately, you can put the variable name in the definition of the `DATA` +section. For example: ```powershell DATA TextMsgs { @@ -173,7 +173,7 @@ A single-quoted here-string that uses the `ConvertFrom-StringData` cmdlet: ```powershell DATA { - ConvertFrom-StringData -StringData @' + ConvertFrom-StringData -stringdata @' Text001 = Windows 7 Text002 = Windows Server 2008 R2 '@ @@ -184,7 +184,7 @@ A double-quoted here-string that uses the `ConvertFrom-StringData` cmdlet: ```powershell DATA { - ConvertFrom-StringData -StringData @" + ConvertFrom-StringData -stringdata @" Msg1 = To start, press any key. Msg2 = To exit, type "quit". "@ @@ -201,12 +201,23 @@ DATA -supportedCommand Format-XML { ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_If](about_If.md) -- [about_Operators](about_Operators.md) -- [about_Quoting_Rules](about_Quoting_Rules.md) -- [about_Script_Internationalization](about_Script_Internationalization.md) -- [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData) -- [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData) +- [about_Automatic_Variables][01] +- [about_Comparison_Operators][02] +- [about_Hash_Tables][03] +- [about_If][04] +- [about_Operators][05] +- [about_Quoting_Rules][06] +- [about_Script_Internationalization][07] +- [ConvertFrom-StringData][08] +- [Import-LocalizedData][09] + + +[01]: about_Automatic_Variables.md +[02]: about_Comparison_Operators.md +[03]: about_Hash_Tables.md +[04]: about_If.md +[05]: about_Operators.md +[06]: about_Quoting_Rules.md +[07]: about_Script_Internationalization.md +[08]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData +[09]: xref:Microsoft.PowerShell.Utility.Import-LocalizedData diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md index 6b064a02940a..a0249358bc8b 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 03/30/2021 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -9,7 +9,6 @@ title: about_Split # about_Split ## Short description - Explains how to use the Split operator to split one or more strings into substrings. @@ -233,19 +232,17 @@ The RegexMatch options are: SimpleMatch. - **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit operator is specified. -- **CultureInvariant**: Ignores cultural differences in language - when evaluating the delimiter. Valid only with RegexMatch. -- **IgnorePatternWhitespace**: Ignores unescaped whitespace and - comments marked with the number sign (#). Valid only with - RegexMatch. -- **Multiline**: Multiline mode forces `^` and `$` to match the beginning - end of every line instead of the beginning and end of the input string. -- **Singleline**: Singleline mode treats the input string as a *SingleLine*. - It forces the `.` character to match every character (including newlines), +- **CultureInvariant**: Ignores cultural differences in language when + evaluating the delimiter. Valid only with RegexMatch. +- **IgnorePatternWhitespace**: Ignores unescaped whitespace and comments marked + with the hash character (`#`). Valid only with RegexMatch. +- **Multiline**: Multiline mode forces `^` and `$` to match the beginning end + of every line instead of the beginning and end of the input string. +- **Singleline**: Singleline mode treats the input string as a *SingleLine*. It + forces the `.` character to match every character (including newlines), instead of matching every character EXCEPT the newline `\n`. -- **ExplicitCapture**: Ignores non-named match groups so that only - explicit capture groups are returned in the result list. Valid - only with RegexMatch. +- **ExplicitCapture**: Ignores non-named match groups so that only explicit + capture groups are returned in the result list. Valid only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS diff --git a/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index 77833f198866..b615a518ddf0 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-stringdata?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertFrom-StringData @@ -15,8 +15,6 @@ Converts a string containing one or more key and value pairs to a hash table. ## SYNTAX -### All - ``` ConvertFrom-StringData [-StringData] [[-Delimiter] ] [] ``` @@ -38,7 +36,7 @@ machine translation tools. That is, the cmdlet can interpret backslashes (`\`) a in the string data by using the [Regex.Unescape Method](/dotnet/api/system.text.regularexpressions.regex.unescape), instead of the PowerShell backtick character (`` ` ``) that would normally signal the end of a line in a script. -Inside the here-string, the backtick character does not work. You can also preserve a literal +Inside the here-string, the backtick character doesn't work. You can also preserve a literal backslash in your results by escaping it with a preceding backslash, like this: `\\`. Unescaped backslash characters, such as those that are commonly used in file paths, can render as illegal escape sequences in your results. @@ -50,14 +48,14 @@ PowerShell 7 adds the **Delimiter** parameter. ### Example 1: Convert a single-quoted here-string to a hash table This example converts a single-quoted here-string of user messages into a hash table. In a -single-quoted string, values are not substituted for variables and expressions are not evaluated. +single-quoted string, values aren't substituted for variables and expressions aren't evaluated. The `ConvertFrom-StringData` cmdlet converts the value in the `$Here` variable to a hash table. ```powershell $Here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. -Msg3 = The specified variable does not exist. +Msg3 = The specified variable doesn't exist. '@ ConvertFrom-StringData -StringData $Here ``` @@ -65,7 +63,7 @@ ConvertFrom-StringData -StringData $Here ```Output Name Value ---- ----- -Msg3 The specified variable does not exist. +Msg3 The specified variable doesn't exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. ``` @@ -121,8 +119,8 @@ Name Disks.ps1 The value of the **StringData** parameter is a here-string, instead of a variable that contains a here-string. Either format is valid. The here-string includes a comment about one of the strings. -`ConvertFrom-StringData` ignores single-line comments, but the `#` character must be the first -non-whitespace character on the line. All characters on the line after the `#` are ignored. +`ConvertFrom-StringData` ignores single-line comments, but the hash character (`#`) must be the +first non-whitespace character on the line. ### Example 4: Convert a string to a hash table @@ -144,9 +142,9 @@ Top Red To satisfy the condition that each key-value pair must be on a separate line, the string uses the PowerShell newline character (`` `n ``) to separate the pairs. -### Example 5: Use ConvertFrom-StringData in the DATA section of a script +### Example 5: Use in the `DATA` section of a script -This example shows a `ConvertFrom-StringData` command used in the **DATA** section of a script. +This example shows a `ConvertFrom-StringData` command used in the `DATA` section of a script. The statements below the **DATA** section display the text to the user. ```powershell @@ -167,7 +165,7 @@ Text002 The $MyNotebook variable contains the name of the user's privat ``` Because the text includes variable names, it must be enclosed in a single-quoted string so that the -variables are interpreted literally and not expanded. Variables are not permitted in the **DATA** +variables are interpreted literally and not expanded. Variables aren't permitted in the `DATA` section. ### Example 6: Use the pipeline operator to pass a string @@ -180,7 +178,7 @@ and the result in the `$Hash` variable. $Here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. -Msg3 = The specified variable does not exist. +Msg3 = The specified variable doesn't exist. '@ $Hash = $Here | ConvertFrom-StringData $Hash @@ -189,7 +187,7 @@ $Hash ```Output Name Value ---- ----- -Msg3 The specified variable does not exist. +Msg3 The specified variable doesn't exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. ``` @@ -197,7 +195,7 @@ Msg1 The string parameter is required. ### Example 7: Use escape characters to add new lines and return characters This example shows the use of escape characters to create new lines and return characters in source -data. The escape sequence `\n` is used to create new lines within a block of text that is associated +data. The escape sequence `\n` is used to create new lines within a block of text that's associated with a name or item in the resulting hash table. ```powershell @@ -216,7 +214,7 @@ Value : Let there be some more test made of my metal, Name : Vincentio Value : Heaven doth with us as we with torches do, Not light them for themselves; for if our virtues - Did not go forth of us, 'twere all alike + Didn't go forth of us, 'twere all alike As if we had them not. ``` @@ -264,10 +262,10 @@ The value of this parameter must be a string that contains one or more key-value key-value pair must be on a separate line, or each pair must be separated by newline characters (`` `n ``). -You can include comments in the string, but the comments cannot be on the same line as a key-value -pair. `ConvertFrom-StringData` ignores single-line comments. The `#` character must be the first -non-whitespace character on the line. All characters on the line after the `#` are ignored. The -comments are not included in the hash table. +You can include comments in the string, but the comments can't be on the same line as a key-value +pair. `ConvertFrom-StringData` ignores single-line comments. The hash character (`#`) must be the +first non-whitespace character on the line. All characters on the line after the hash character +(`#`) are ignored. The comments aren't included in the hash table. A here-string is a string consisting of one or more lines. Quotation marks within the here-string are interpreted literally as part of the string data. For more information, see diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Export-Alias.md b/reference/7.5/Microsoft.PowerShell.Utility/Export-Alias.md index 740663c0f225..d533077f14de 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Export-Alias.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Export-Alias.md @@ -18,23 +18,27 @@ Exports information about currently defined aliases to a file. ### ByPath (Default) ``` -Export-Alias [-Path] [[-Name] ] [-PassThru] [-As ] [-Append] [-Force] - [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] [] +Export-Alias [-Path] [[-Name] ] [-PassThru] [-As ] [-Append] + [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] + [] ``` ### ByLiteralPath ``` -Export-Alias -LiteralPath [[-Name] ] [-PassThru] [-As ] [-Append] - [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] [] +Export-Alias -LiteralPath [[-Name] ] [-PassThru] [-As ] + [-Append] [-Force] [-NoClobber] [-Description ] [-Scope ] [-WhatIf] [-Confirm] + [] ``` ## DESCRIPTION -The `Export-Alias` cmdlet exports the aliases in the current session to a file. -If the output file does not exist, the cmdlet will create it. +The `Export-Alias` cmdlet exports the aliases in the current session to a file. If the output file +does not exist, the cmdlet will create it. -`Export-Alias` can export the aliases in a particular scope or all scopes, it can generate the data in CSV format or as a series of Set-Alias commands that you can add to a session or to a PowerShell profile. +`Export-Alias` can export the aliases in a particular scope or all scopes, it can generate the data +in CSV format or as a series of Set-Alias commands that you can add to a session or to a PowerShell +profile. ## EXAMPLES @@ -54,7 +58,8 @@ Export-Alias -Path "alias.csv" -NoClobber This command exports the aliases in the current session to an Alias.csv file. -Because the **NoClobber** parameter is specified, the command will fail if an Alias.csv file already exists in the current directory. +Because the **NoClobber** parameter is specified, the command will fail if an Alias.csv file already +exists in the current directory. ### Example 3: Append aliases to a file @@ -64,9 +69,11 @@ Export-Alias -Path "alias.csv" -Append -Description "Appended Aliases" -Force This command appends the aliases in the current session to the Alias.csv file. -The command uses the **Description** parameter to add a description to the comments at the top of the file. +The command uses the **Description** parameter to add a description to the comments at the top of +the file. -The command also uses the **Force** parameter to overwrite any existing Alias.csv files, even if they have the read-only attribute. +The command also uses the **Force** parameter to overwrite any existing Alias.csv files, even if +they have the read-only attribute. ### Example 4: Export aliases as a script @@ -79,23 +86,27 @@ Invoke-Command -Session $S -FilePath .\alias.ps1 This example shows how to use the script file format that `Export-Alias` generates. -The first command exports the aliases in the session to the Alias.ps1 file. -It uses the **As** parameter with a value of Script to generate a file that contains a Set-Alias command for each alias. +The first command exports the aliases in the session to the Alias.ps1 file. It uses the **As** +parameter with a value of Script to generate a file that contains a Set-Alias command for each +alias. The second command adds the aliases in the Alias.ps1 file to the CurrentUser-CurrentHost profile. -The path to the profile is saved in the `$Profile` variable. -The command uses the `Get-Content` cmdlet to get the aliases from the Alias.ps1 file and the `Add-Content` cmdlet to add them to the profile. -For more information, see [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). +The path to the profile is saved in the `$Profile` variable. The command uses the `Get-Content` +cmdlet to get the aliases from the Alias.ps1 file and the `Add-Content` cmdlet to add them to the +profile. For more information, see +[about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). -The third and fourth commands add the aliases in the Alias.ps1 file to a remote session on the Server01 computer. -The third command uses the `New-PSSession` cmdlet to create the session. -The fourth command uses the **FilePath** parameter of the `Invoke-Command` cmdlet to run the Alias.ps1 file in the new session. +The third and fourth commands add the aliases in the Alias.ps1 file to a remote session on the +Server01 computer. The third command uses the `New-PSSession` cmdlet to create the session. The +fourth command uses the **FilePath** parameter of the `Invoke-Command` cmdlet to run the Alias.ps1 +file in the new session. ## PARAMETERS ### -Append -Indicates that this cmdlet appends the output to the specified file, rather than overwriting the existing contents of that file. +Indicates that this cmdlet appends the output to the specified file, rather than overwriting the +existing contents of that file. ```yaml Type: System.Management.Automation.SwitchParameter @@ -115,11 +126,9 @@ Specifies the output format. CSV is the default. The acceptable values for this parameter are: -- CSV. -Comma-separated value (CSV) format. -- Script. -Creates a `Set-Alias` command for each exported alias. -If you name the output file with a .ps1 file name extension, you can run it as a script to add the aliases to any session. +- CSV. Comma-separated value (CSV) format. +- Script. Creates a `Set-Alias` command for each exported alias. If you name the output file with a + .ps1 file name extension, you can run it as a script to add the aliases to any session. ```yaml Type: Microsoft.PowerShell.Commands.ExportAliasFormat @@ -136,8 +145,8 @@ Accept wildcard characters: False ### -Description -Specifies the description of the exported file. -The description appears as a comment at the top of the file, following the header information. +Specifies the description of the exported file. The description appears as a comment at the top of +the file, following the header information. ```yaml Type: System.String @@ -157,8 +166,9 @@ Forces the command to run without asking for user confirmation. Overwrites the output file, even if the read-only attribute is set on the file. -By default, `Export-Alias` overwrites files without warning, unless the read-only or hidden attribute is set or the **NoClobber** parameter is used in the command. -The **NoClobber** parameter takes precedence over the **Force** parameter when both are used in a command. +By default, `Export-Alias` overwrites files without warning, unless the read-only or hidden +attribute is set or the **NoClobber** parameter is used in the command. The **NoClobber** parameter +takes precedence over the **Force** parameter when both are used in a command. The **Force** parameter cannot force `Export-Alias` to overwrite files with the hidden attribute. @@ -176,11 +186,10 @@ Accept wildcard characters: False ### -LiteralPath -Specifies the path to the output file. -Unlike **Path**, the value of the **LiteralPath** parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +Specifies the path to the output file. Unlike **Path**, the value of the **LiteralPath** parameter +is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes +escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not +to interpret any characters as escape sequences. ```yaml Type: System.String @@ -196,8 +205,7 @@ Accept wildcard characters: False ### -Name -Specifies the names as an array of the aliases to export. -Wildcards are permitted. +Specifies the names as an array of the aliases to export. Wildcards are permitted. By default, `Export-Alias` exports all aliases in the session or scope. @@ -215,12 +223,14 @@ Accept wildcard characters: True ### -NoClobber -Indicates that this cmdlet prevents `Export-Alias` from overwriting any files, even if the **Force** parameter is used in the command. +Indicates that this cmdlet prevents `Export-Alias` from overwriting any files, even if the **Force** +parameter is used in the command. -If the **NoClobber** parameter is omitted, `Export-Alias` will overwrite an existing file without warning, unless the read-only attribute is set on the file. -*NoClobber* takes precedence over the **Force** parameter, which permits `Export-Alias` to overwrite a file with the read-only attribute. +If the **NoClobber** parameter is omitted, `Export-Alias` will overwrite an existing file without +warning, unless the read-only attribute is set on the file. **NoClobber** takes precedence over the +**Force** parameter, which permits `Export-Alias` to overwrite a file with the read-only attribute. -*NoClobber* does not prevent the **Append** parameter from adding content to an existing file. +**NoClobber** does not prevent the **Append** parameter from adding content to an existing file. ```yaml Type: System.Management.Automation.SwitchParameter @@ -236,8 +246,8 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the item with which you are working. -By default, this cmdlet does not generate any output. +Returns an object representing the item with which you are working. By default, this cmdlet does not +generate any output. ```yaml Type: System.Management.Automation.SwitchParameter @@ -253,8 +263,8 @@ Accept wildcard characters: False ### -Path -Specifies the path to the output file. -Wildcards are permitted, but the resulting path value must resolve to a single file name. +Specifies the path to the output file. Wildcards are permitted, but the resulting path value must +resolve to a single file name. ```yaml Type: System.String @@ -270,16 +280,17 @@ Accept wildcard characters: True ### -Scope -Specifies the scope from which the aliases should be exported. -The acceptable values for this parameter are: +Specifies the scope from which the aliases should be exported. The acceptable values for this +parameter are: -- Global -- Local -- Script -- A number relative to the current scope (0 through the number of scopes where 0 is the current scope and 1 is its parent) +- `Global` +- `Local` +- `Script` +- A number relative to the current scope (0 through the number of scopes where 0 is the current + scope and 1 is its parent) -The default value is Local. -For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). +The default value is `Local`. For more information, see +[about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). ```yaml Type: System.String @@ -328,7 +339,10 @@ 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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md b/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md index 08fc3f3550dc..5abfd86eae3c 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 03/15/2023 +ms.date: 01/09/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/import-csv?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Import-Csv @@ -56,7 +56,7 @@ delimiter. You can also use the `ConvertTo-Csv` and `ConvertFrom-Csv` cmdlets to convert objects to CSV strings (and back). These cmdlets are the same as the `Export-CSV` and `Import-Csv` cmdlets, except -that they do not deal with files. +that they work with data from the pipeline instead of from files. If a header row entry in a CSV file contains an empty or null value, PowerShell inserts a default header row name and displays a warning message. @@ -260,7 +260,7 @@ objects are stored in the `$A` variable. The `Get-Member` cmdlet shows the prope **Header** parameter. The `Where-Object` cmdlet selects objects with the **TopicTitle** property that includes **alias**. -### Example 6: Import a CSV that is missing a value +### Example 6: Import a CSV that's missing a value This example shows how the `Import-Csv` cmdlet in PowerShell responds when the header row in a CSV file includes a null or empty value. `Import-Csv` substitutes a default name for the missing header @@ -282,7 +282,7 @@ Import-Csv -Path .\Projects.csv ``` ```Output -WARNING: One or more headers were not specified. Default names starting with "H" have been used in +WARNING: One or more headers weren't specified. Default names starting with "H" have been used in place of any missing headers. ProjectID ProjectName H1 Completed @@ -292,24 +292,9 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` -```powershell -(Import-Csv -Path .\Projects.csv).H1 -``` - -```Output -WARNING: One or more headers were not specified. Default names starting with "H" have been used in -place of any missing headers. -Redmond -FarEast -Europe -``` - -To create your Projects.csv file, use the values shown in the example's `Get-Content` output. - -The `Get-Content` cmdlet displays the Projects.csv file. The header row is missing a value between -**ProjectName** and **Completed**. The `Import-Csv` cmdlet imports the Projects.csv file and -displays a warning message because **H1** is a default header name. The `(Import-Csv -Path -.\Projects.csv).H1` command gets the **H1** property values and displays a warning. +The `Get-Content` cmdlet displays the `Projects.csv` file. The header row is missing a value between +**ProjectName** and **Completed**. The `Import-Csv` cmdlet imports the `Projects.csv` file and +displays a warning message because **H1** is a default header name. ## PARAMETERS @@ -322,8 +307,8 @@ Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose i quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double quotation marks. -If you specify a character other than the actual string delimiter in the file, `Import-Csv` cannot -create the objects from the CSV strings and will return the CSV strings. +If you specify a character other than the actual string delimiter in the file, `Import-Csv` can't +create the objects from the CSV strings and returns the full CSV strings. ```yaml Type: System.Char @@ -386,7 +371,7 @@ Accept wildcard characters: False Specifies an alternate column header row for the imported file. The column header determines the property names of the objects created by `Import-Csv`. -Enter column headers as a character-separated list. Do not enclose the header string in quotation +Enter column headers as a character-separated list. Don't enclose the header string in quotation marks. Enclose each column header in single quotation marks. If you enter fewer column headers than there are data columns, the remaining data columns are @@ -411,7 +396,7 @@ Accept wildcard characters: False ### -LiteralPath Specifies the path to the CSV file to import. Unlike **Path**, the value of the **LiteralPath** -parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path +parameter is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -487,7 +472,7 @@ PowerShell includes the following aliases for `Import-Csv`: - All platforms: - `ipcsv` -Because the imported objects are CSV versions of the object type, they are not recognized and +Because the imported objects are CSV versions of the object type, they're not recognized and formatted by the PowerShell type formatting entries that format the non-CSV versions of the object type. @@ -506,13 +491,13 @@ If the column header row is missing a value or contains a null or empty value, ` In the CSV file, each object is represented by a character-separated list of the property values of the object. The property values are converted to strings by using the **ToString()** method of the -object, so they are represented by the name of the property value. `Export-Csv` does not export the +object, so they're represented by the name of the property value. `Export-Csv` doesn't export the methods of the object. -`Import-Csv` also supports the W3C Extended Log format. Lines starting with `#` are treated as -comments and ignored unless the comment starts with `#Fields:` and contains delimited list of column -names. In that case, the cmdlet uses those column names. This is the standard format for Windows IIS -and other web server logs. For more information, see +`Import-Csv` also supports the W3C Extended Log format. Lines starting with the hash character (`#`) +are treated as comments and ignored unless the comment starts with `#Fields:` and contains delimited +list of column names. In that case, the cmdlet uses those column names. This is the standard format +for Windows IIS and other web server logs. For more information, see [Extended Log File Format](https://www.w3.org/TR/WD-logfile.html). ## RELATED LINKS diff --git a/reference/docs-conceptual/lang-spec/chapter-03.md b/reference/docs-conceptual/lang-spec/chapter-03.md index 55318dc1f0de..9243e65841cc 100644 --- a/reference/docs-conceptual/lang-spec/chapter-03.md +++ b/reference/docs-conceptual/lang-spec/chapter-03.md @@ -328,19 +328,19 @@ Unless dot source notation ([§3.5.5][§3.5.5]) is used, each of the following c Consider the following example: ```powershell -# start of script +# Start of script $x = 2; $y = 3 Get-Power $x $y -#function defined in script - -function Get-Power([int]$x, [int]$y) -{ -if ($y -gt 0) { return $x * (Get-Power $x (--$y)) } - -else { return 1 } +# Function defined in script +function Get-Power([int]$x, [int]$y) { + if ($y -gt 0) { + return $x * (Get-Power $x (--$y)) + } else { + return 1 + } } -# end of script +# End of script ``` The scope of the variables `$x` and `$y` created in the script is the body of that script, including diff --git a/reference/docs-conceptual/learn/ps101/05-formatting-aliases-providers-comparison.md b/reference/docs-conceptual/learn/ps101/05-formatting-aliases-providers-comparison.md index 558f10346808..0e1062f54475 100644 --- a/reference/docs-conceptual/learn/ps101/05-formatting-aliases-providers-comparison.md +++ b/reference/docs-conceptual/learn/ps101/05-formatting-aliases-providers-comparison.md @@ -1,22 +1,25 @@ --- description: This chapter introduces the concepts of output formatting, command aliases, providers, and comparison operations. ms.custom: Contributor-mikefrobbins -ms.date: 11/16/2022 +ms.date: 01/09/2025 ms.reviewer: mirobb title: Formatting, aliases, providers, comparison --- + # Chapter 5 - Formatting, aliases, providers, comparison -## Requirements +## Prerequisites -The SQL Server PowerShell module is required by some of the examples shown in this chapter. The -module installs as part of [SQL Server Management Studio (SSMS)][SSMS]. It's also used in -subsequent chapters. Download and install it on your Windows 10 lab environment computer. +The **SqlServer** PowerShell module is required by some examples shown in this chapter. For more +information about the **SqlServer** PowerShell module and installation instructions, see +[SQL Server PowerShell overview][sql-server-powershell]. It's also used in subsequent chapters. +Download and install it on your Windows lab environment computer. ## Format Right In Chapter 4, you learned to filter as far to the left as possible. The rule for manually formatting -a command's output is similar to that rule except it needs to occur as far to the right as possible. +a command's output is similar to that rule, except it needs to occur as far to the right as +possible. The most common format commands are `Format-Table` and `Format-List`. `Format-Wide` and `Format-Custom` can also be used, but are less common. @@ -25,7 +28,8 @@ As mentioned in Chapter 3, a command that returns more than four properties defa unless custom formatting is used. ```powershell -Get-Service -Name w32time | Select-Object -Property Status, DisplayName, Can* +Get-Service -Name w32time | + Select-Object -Property Status, DisplayName, Can* ``` ```Output @@ -40,13 +44,14 @@ Use the `Format-Table` cmdlet to manually override the formatting and show the o instead of a list. ```powershell -Get-Service -Name w32time | Select-Object -Property Status, DisplayName, Can* | -Format-Table +Get-Service -Name w32time | + Select-Object -Property Status, DisplayName, Can* | + Format-Table ``` ```Output - Status DisplayName CanPauseAndContinue CanShutdown CanStop - ------ ----------- ------------------- ----------- ------- +Status DisplayName CanPauseAndContinue CanShutdown CanStop +------ ----------- ------------------- ----------- ------- Running Windows Time False True True ``` @@ -68,6 +73,10 @@ Use the `Format-List` cmdlet to override the default formatting and return the r Get-Service -Name w32time | Format-List ``` +Notice that simply piping `Get-Service` to `Format-List` made it return additional properties. This +doesn't occur with every command because of how the format for that particular command is set up +behind the scenes. + ```Output Name : w32time DisplayName : Windows Time @@ -77,13 +86,9 @@ ServicesDependedOn : {} CanPauseAndContinue : False CanShutdown : True CanStop : True -ServiceType : Win32ShareProcess +ServiceType : Win32OwnProcess, Win32ShareProcess ``` -Notice that simply piping `Get-Service` to `Format-List` made it return additional properties. This -doesn't occur with every command because of the way the formatting for that particular command is -set up behind the scenes. - The number one thing to be aware of with the format cmdlets is they produce format objects that are different than normal objects in PowerShell. @@ -96,63 +101,67 @@ Get-Service -Name w32time | Format-List | Get-Member Name MemberType Definition ---- ---------- ---------- -Equals Method bool Equals(System.Object obj) +Equals Method bool Equals(System.Obj... GetHashCode Method int GetHashCode() GetType Method type GetType() ToString Method string ToString() -autosizeInfo Property Microsoft.PowerShell.Commands.Inter... -ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef21dd47e99d3c9... -groupingEntry Property Microsoft.PowerShell.Commands.Inter... -pageFooterEntry Property Microsoft.PowerShell.Commands.Inter... -pageHeaderEntry Property Microsoft.PowerShell.Commands.Inter... -shapeInfo Property Microsoft.PowerShell.Commands.Inter... +autosizeInfo Property Microsoft.PowerShell.C... +ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef... +groupingEntry Property Microsoft.PowerShell.C... +pageFooterEntry Property Microsoft.PowerShell.C... +pageHeaderEntry Property Microsoft.PowerShell.C... +shapeInfo Property Microsoft.PowerShell.C... + TypeName: Microsoft.PowerShell.Commands.Internal.Format.GroupStartData Name MemberType Definition ---- ---------- ---------- -Equals Method bool Equals(System.Object obj) +Equals Method bool Equals(System.Obj... GetHashCode Method int GetHashCode() GetType Method type GetType() ToString Method string ToString() -ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef21dd47e99d3c9... -groupingEntry Property Microsoft.PowerShell.Commands.Inter... -shapeInfo Property Microsoft.PowerShell.Commands.Inter... +ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef... +groupingEntry Property Microsoft.PowerShell.C... +shapeInfo Property Microsoft.PowerShell.C... + TypeName: Microsoft.PowerShell.Commands.Internal.Format.FormatEntryData Name MemberType Definition ---- ---------- ---------- -Equals Method bool Equals(System.Object obj) +Equals Method bool Equals(System.Obj... GetHashCode Method int GetHashCode() GetType Method type GetType() ToString Method string ToString() -ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef21dd47e99d3c9... -formatEntryInfo Property Microsoft.PowerShell.Commands.Inter... +ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef... +formatEntryInfo Property Microsoft.PowerShell.C... outOfBand Property bool outOfBand {get;set;} -writeStream Property Microsoft.PowerShell.Commands.Inter... +writeStream Property Microsoft.PowerShell.C... + TypeName: Microsoft.PowerShell.Commands.Internal.Format.GroupEndData Name MemberType Definition ---- ---------- ---------- -Equals Method bool Equals(System.Object obj) +Equals Method bool Equals(System.Obj... GetHashCode Method int GetHashCode() GetType Method type GetType() ToString Method string ToString() -ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef21dd47e99d3c9... -groupingEntry Property Microsoft.PowerShell.Commands.Inter... +ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef... +groupingEntry Property Microsoft.PowerShell.C... + TypeName: Microsoft.PowerShell.Commands.Internal.Format.FormatEndData Name MemberType Definition ---- ---------- ---------- -Equals Method bool Equals(System.Object obj) +Equals Method bool Equals(System.Obj... GetHashCode Method int GetHashCode() GetType Method type GetType() ToString Method string ToString() -ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef21dd47e99d3c9... -groupingEntry Property Microsoft.PowerShell.Commands.Inter... +ClassId2e4f51ef21dd47e99d3c952918aff9cd Property string ClassId2e4f51ef... +groupingEntry Property Microsoft.PowerShell.C... ``` What this means is format commands can't be piped to most other commands. They can be piped to some @@ -172,8 +181,8 @@ Get-Alias -Name gcm ``` ```Output -CommandType Name Version Source ------------ ---- ------- ------ +CommandType Name Version +----------- ---- ------- Alias gcm -> Get-Command ``` @@ -184,75 +193,73 @@ Get-Alias -Name gcm, gm ``` ```Output -CommandType Name Version Source ------------ ---- ------- ------ +CommandType Name Version +----------- ---- ------- Alias gcm -> Get-Command Alias gm -> Get-Member ``` -You'll often see the **Name** parameter omitted since it's a positional parameter. +You often see the **Name** parameter omitted since it's a positional parameter. ```powershell Get-Alias gm ``` ```Output -CommandType Name Version Source ------------ ---- ------- ------ +CommandType Name Version +----------- ---- ------- Alias gm -> Get-Member ``` -If you want to find aliases for a command, you'll need to use the **Definition** parameter. +If you want to find aliases for a command, you need to use the **Definition** parameter. ```powershell Get-Alias -Definition Get-Command, Get-Member ``` ```Output -CommandType Name Version Source ------------ ---- ------- ------ +CommandType Name Version +----------- ---- ------- Alias gcm -> Get-Command Alias gm -> Get-Member ``` -The **Definition** parameter can't be used positionally so it must be specified. +The **Definition** parameter can't be used positionally, so it must be specified. -Aliases can save you a few keystrokes and they're fine when you're typing commands into the console. +Aliases can save you a few keystrokes, and they're fine when you type commands into the console. They shouldn't be used in scripts or any code that you're saving or sharing with others. As mentioned earlier in this book, using full cmdlet and parameter names is self-documenting and easier to understand. -Use caution when creating your own aliases because they'll only exist in your current PowerShell +Use caution when creating your own aliases because they only exist in your current PowerShell session on your computer. ## Providers -A provider in PowerShell is an interface that allows file system like access to a datastore. There -are a number of built-in providers in PowerShell. +A provider in PowerShell is an interface that allows file system-like access to a data store. There +are several built-in providers in PowerShell. ```powershell Get-PSProvider ``` +As you can see in the following results, there are built-in providers for the registry, aliases, +environment variables, the file system, functions, variables, certificates, and WSMan. + ```Output -Name Capabilities Drives ----- ------------ ------ -Registry ShouldProcess, Transactions {HKLM, HKCU} -Alias ShouldProcess {Alias} -Environment ShouldProcess {Env} -FileSystem Filter, ShouldProcess, Credentials {C, A, D} -Function ShouldProcess {Function} -Variable ShouldProcess {Variable} -Certificate ShouldProcess {Cert} -WSMan Credentials {WSMan} +Name Capabilities Drives +---- ------------ ------ +Registry ShouldProcess, Transactions {HKLM, HKCU} +Alias ShouldProcess {Alias} +Environment ShouldProcess {Env} +FileSystem Filter, ShouldProcess, Cr... {C, D} +Function ShouldProcess {Function} +Variable ShouldProcess {Variable} ``` -As you can see in the previous results, there are built-in providers for the registry, aliases, -environment variables, the file system, functions, variables, certificates, and WSMan. - -The actual drives that these providers use to expose their datastore can be determined with the -`Get-PSDrive` cmdlet. The `Get-PSDrive` cmdlet not only displays drives exposed by providers, but it -also displays Windows logical drives including drives mapped to network shares. +The actual drives that these providers use to expose their data store can be determined with the +`Get-PSDrive` cmdlet. The `Get-PSDrive` cmdlet not only displays drives exposed by providers but +also displays Windows logical drives, including drives mapped to network shares. ```powershell Get-PSDrive @@ -261,9 +268,8 @@ Get-PSDrive ```Output Name Used (GB) Free (GB) Provider Root ---- --------- --------- -------- ---- -A FileSystem A:\ Alias Alias -C 14.41 112.10 FileSystem C:\ +C 18.56 107.62 FileSystem C:\ Cert Certificate \ D FileSystem D:\ Env Environment @@ -274,10 +280,10 @@ Variable Variable WSMan WSMan ``` -Third-party modules such as the Active Directory PowerShell module and the SQLServer PowerShell -module both add their own PowerShell provider and PSDrive. +Third-party modules such as the **ActiveDirectory** PowerShell module and the **SqlServer** +PowerShell module both add their own PowerShell provider and PSDrive. -Import the Active Directory and SQL Server PowerShell modules. +Import the **ActiveDirectory** and **SqlServer** PowerShell modules. ```powershell Import-Module -Name ActiveDirectory, SQLServer @@ -289,6 +295,9 @@ Check to see if any additional PowerShell providers were added. Get-PSProvider ``` +Notice that in the following set of results, two new PowerShell providers now exist, one for Active +Directory and another one for SQL Server. + ```Output Name Capabilities Drives ---- ------------ ------ @@ -302,9 +311,6 @@ ActiveDirectory Include, Exclude, Filter, Shoul... {AD} SqlServer Credentials {SQLSERVER} ``` -Notice that in the previous set of results, two new PowerShell providers now exist, one for Active -Directory and another one for SQL Server. - A PSDrive for each of those modules was also added. ```powershell @@ -341,36 +347,36 @@ Get-ChildItem -Path Cert:\LocalMachine\CA Thumbprint Subject ---------- ------- FEE449EE0E3965A5246F000E87FDE2A065FD89D4 CN=Root Agency -D559A586669B08F46A30A133F8A9ED3D038E2EA8 OU=www.verisign.com/CPS Incorporated LIABI... -109F1CAED645BB78B3EA2B94C0697C740733031C CN=Microsoft Windows Hardware Compatibility,... +D559A586669B08F46A30A133F8A9ED3D038E2EA8 OU=www.verisign.com/CPS Incorp.... +109F1CAED645BB78B3EA2B94C0697C740733031C CN=Microsoft Windows Hardware C... ``` ## Comparison Operators -PowerShell contains a number of comparison operators that are used to compare values or find values -that match certain patterns. Table 5-1 contains a list of comparison operators in PowerShell. - -| Operator | Definition | -| -------------- | ------------------------------------------------------------ | -| `-eq` | Equal to | -| `-ne` | Not equal to | -| `-gt` | Greater than | -| `-ge` | Greater than or equal to | -| `-lt` | Less than | -| `-le` | Less than or equal to | -| `-Like` | Match using the `*` wildcard character | -| `-NotLike` | Does not match using the `*` wildcard character | -| `-Match` | Matches the specified regular expression | -| `-NotMatch` | Does not match the specified regular expression | -| `-Contains` | Determines if a collection contains a specified value | -| `-NotContains` | Determines if a collection does not contain a specific value | -| `-In` | Determines if a specified value is in a collection | -| `-NotIn` | Determines if a specified value is not in a collection | -| `-Replace` | Replaces the specified value | - -All of the operators listed in Table 5-1 are case-insensitive. Place a `c` in front of the operator -listed in Table 5-1 to make it case-sensitive. For example, `-ceq` is the case-sensitive version of -the `-eq` comparison operator. +PowerShell contains various comparison operators that are used to compare values or find values that +match certain patterns. The following table contains a list of comparison operators in PowerShell. + +All the operators listed in the table are case-insensitive. To make them case-sensitive, place a `c` +in front of the operator. For example, `-ceq` is the case-sensitive version of the equals (`-eq`) +comparison operator. + +| Operator | Definition | +| -------------- | ----------------------------------------------------------- | +| `-eq` | Equal to | +| `-ne` | Not equal to | +| `-gt` | Greater than | +| `-ge` | Greater than or equal to | +| `-lt` | Less than | +| `-le` | Less than or equal to | +| `-Like` | Match using the `*` wildcard character | +| `-NotLike` | Doesn't match using the `*` wildcard character | +| `-Match` | Matches the specified regular expression | +| `-NotMatch` | Doesn't match the specified regular expression | +| `-Contains` | Determines if a collection contains a specified value | +| `-NotContains` | Determines if a collection doesn't contain a specific value | +| `-In` | Determines if a specified value is in a collection | +| `-NotIn` | Determines if a specified value isn't in a collection | +| `-Replace` | Replaces the specified value | Proper case "PowerShell" is equal to lower case "powershell" using the equals comparison operator. @@ -436,7 +442,7 @@ True ``` The `-Like` and `-Match` operators can be confusing, even for experienced PowerShell users. `-Like` -is used with wildcard the characters `*` and `?` to perform "like" matches. +is used with the wildcard characters `*` and `?` to perform "like" matches. ```powershell 'PowerShell' -like '*shell' @@ -462,9 +468,6 @@ Use the range operator to store the numbers 1 through 10 in a variable. $Numbers = 1..10 ``` -```Output -``` - Determine if the `$Numbers` variable includes 15. ```powershell @@ -491,12 +494,14 @@ True $Numbers -notcontains 15 ``` +The previous example returns the **Boolean** true because it's true that the `$Numbers` variable +doesn't contain 15. + ```Output True ``` -The previous example returns the **Boolean** true because it's true that the `$Numbers` variable -doesn't contain 15. It does however contain the number 10 so it's false when it's tested. +It does, however, contain the number 10, so it's false when tested. ```powershell $Numbers -notcontains 10 @@ -506,8 +511,8 @@ $Numbers -notcontains 10 False ``` -The "in" comparison operator was first introduced in PowerShell version 3.0. It's used to determine -if a value is "in" an array. The `$Numbers` variable is an array since it contains multiple values. +The `-in` comparison operator was first introduced in PowerShell version 3.0. It's used to determine +if a value is _in_ an array. The `$Numbers` variable is an array since it contains multiple values. ```powershell 15 -in $Numbers @@ -528,7 +533,7 @@ opposite direction. True ``` -15 isn't in the `$Numbers` array so false is returned in the following example. +Fifteen isn't in the `$Numbers` array, so false is returned in the following example. ```powershell 15 -in $Numbers @@ -544,25 +549,28 @@ Just like the `-contains` operator, `not` reverses the logic for the `-in` opera 10 -notin $Numbers ``` +The previous example returns false because the `$Numbers` array does include 10 and the condition +tests to determine if it doesn't contain 10. + ```Output False ``` -The previous example returns false because the `$Numbers` array does include 10 and the condition -was testing to determine if it didn't contain 10. - -15 is "not in" the `$Numbers` array so it returns the **Boolean** true. +Determine if fifteen isn't in the `$Numbers` array. ```powershell 15 -notin $Numbers ``` +15 is "not in" the `$Numbers` array so it returns the **Boolean** true. + ```Output True ``` The `-replace` operator does just want you would think. It's used to replace something. Specifying -one value replaces that value with nothing. In the following example, I replace "Shell" with nothing. +one value replaces that value with nothing. In the following example, you replace "Shell" with +nothing. ```powershell 'PowerShell' -replace 'Shell' @@ -572,9 +580,9 @@ one value replaces that value with nothing. In the following example, I replace Power ``` -If you want to replace a value with a different value, specify the new value after the pattern you -want to replace. SQL Saturday in Baton Rouge is an event that I try to speak at every year. In the -following example, I replace the word "Saturday" with the abbreviation "Sat". +If you want to replace a value with a different one, specify the new one after the pattern you want +to replace. SQL Saturday in Baton Rouge is an event I try to speak at every year. In the following +example, the word "Saturday" is replaced with the abbreviation "Sat". ```powershell 'SQL Saturday - Baton Rouge' -Replace 'saturday','Sat' @@ -584,7 +592,7 @@ following example, I replace the word "Saturday" with the abbreviation "Sat". SQL Sat - Baton Rouge ``` -There are also methods like **Replace()** that can be used to replace things similar to the way the +There are also methods like **Replace()** that can be used to replace things similar to how the replace operator works. However, the `-Replace` operator is case-insensitive by default, and the **Replace()** method is case-sensitive. @@ -592,13 +600,15 @@ replace operator works. However, the `-Replace` operator is case-insensitive by 'SQL Saturday - Baton Rouge'.Replace('saturday','Sat') ``` +Notice that the word "Saturday" isn't replaced. This is because it's specified in a different case +than the original. + ```Output SQL Saturday - Baton Rouge ``` -Notice that the word "Saturday" wasn't replaced in the previous example. This is because it was -specified in a different case than the original. When the word "Saturday" is specified in the same -case as the original, the **Replace()** method does replace it as expected. +When the word "Saturday" is specified in the same case as the original, the **Replace()** method +performs the replacement as expected. ```powershell 'SQL Saturday - Baton Rouge'.Replace('Saturday','Sat') @@ -608,44 +618,49 @@ case as the original, the **Replace()** method does replace it as expected. SQL Sat - Baton Rouge ``` -Be careful when using methods to transform data because you can run into unforeseen problems, such -as failing the _Turkey Test_. For an example, see the blog article titled -[Using Pester to Test PowerShell Code with Other Cultures][Using Pester to Test PowerShell Code with Other Cultures]. My recommendation is to use an -operator instead of a method whenever possible to avoid these types of problems. +Be careful when using methods to transform data because you can encounter unforeseen problems, such +as failing the _Turkey Test_. For an example, see my blog article, +[Using Pester to Test PowerShell Code with Other Cultures][pester-test-other-cultures]. I recommend +using operators instead of methods whenever possible to avoid these types of problems. -While the comparison operators can be used as shown in the previous examples, I normally find myself -using them with the `Where-Object` cmdlet to perform some type of filtering. +While the comparison operators can be used, as shown in the previous examples, I typically use them +with the `Where-Object` cmdlet to perform filtering. ## Summary -In this chapter, you've learned a number of different topics to include Formatting Right, Aliases, -Providers, and Comparison Operators. +You learned several topics in this chapter, including Formatting Right, Aliases, Providers, and +Comparison Operators. ## Review -1. Why is it necessary to perform Formatting as far to the right as possible? +1. Why is it necessary to perform formatting as far to the right as possible? 1. How do you determine what the actual cmdlet is for the `%` alias? 1. Why shouldn't you use aliases in scripts you save or code you share with others? 1. Perform a directory listing on the drives that are associated with one of the registry providers. 1. What's one of the main benefits of using the replace operator instead of the replace method? -## Recommended Reading +## References + +- [Format-Table][format-table] +- [Format-List][format-list] +- [Format-Wide][format-wide] +- [about_Aliases][about-aliases] +- [about_Providers][about-providers] +- [about_Comparison_Operators][about-comparison-operators] +- [about_Arrays][about-arrays] -- [Format-Table][Format-Table] -- [Format-List][Format-List] -- [Format-Wide][Format-Wide] -- [about_Aliases][about_Aliases] -- [about_Providers][about_Providers] -- [about_Comparison_Operators][about_Comparison_Operators] -- [about_Arrays][about_Arrays] +## Next steps + +In the next chapter, you'll learn about flow control, scripting, loops, and conditional logic. -[SSMS]: /sql/ssms/download-sql-server-management-studio-ssms -[Format-Table]: /powershell/module/microsoft.powershell.utility/format-table -[Format-List]: /powershell/module/microsoft.powershell.utility/format-list -[Format-Wide]: /powershell/module/microsoft.powershell.utility/format-wide -[about_Aliases]: /powershell/module/microsoft.powershell.core/about/about_aliases -[about_Providers]: /powershell/module/microsoft.powershell.core/about/about_providers -[about_Comparison_Operators]: /powershell/module/microsoft.powershell.core/about/about_comparison_operators -[about_Arrays]: /powershell/module/microsoft.powershell.core/about/about_arrays -[Using Pester to Test PowerShell Code with Other Cultures]: https://mikefrobbins.com/2015/10/22/using-pester-to-test-powershell-code-with-other-cultures/ + +[sql-server-powershell]: /sql/powershell/download-sql-server-ps-module +[format-table]: /powershell/module/microsoft.powershell.utility/format-table +[format-list]: /powershell/module/microsoft.powershell.utility/format-list +[format-wide]: /powershell/module/microsoft.powershell.utility/format-wide +[about-aliases]: /powershell/module/microsoft.powershell.core/about/about_aliases +[about-providers]: /powershell/module/microsoft.powershell.core/about/about_providers +[about-comparison-operators]: /powershell/module/microsoft.powershell.core/about/about_comparison_operators +[about-arrays]: /powershell/module/microsoft.powershell.core/about/about_arrays +[pester-test-other-cultures]: https://mikefrobbins.com/2015/10/22/using-pester-to-test-powershell-code-with-other-cultures/ diff --git a/reference/docs-conceptual/learn/ps101/09-functions.md b/reference/docs-conceptual/learn/ps101/09-functions.md index de38cdb90d04..415e62da6903 100644 --- a/reference/docs-conceptual/learn/ps101/09-functions.md +++ b/reference/docs-conceptual/learn/ps101/09-functions.md @@ -1,7 +1,7 @@ --- description: PowerShell functions allow you to create tools that can be reused in scripts. ms.custom: Contributor-mikefrobbins -ms.date: 11/16/2022 +ms.date: 01/09/2025 ms.reviewer: mirobb title: Functions --- @@ -570,12 +570,12 @@ computer name if a value is not provided. ## Verbose Output -While inline comments are useful, especially if you're writing some complex code, they never get -seen by users unless they look into the code itself. +While comments are useful, especially if you're writing some complex code, they never get seen by +users unless they look into the code itself. -The function shown in the following example has an inline comment in the `foreach` loop. While this -particular comment may not be that difficult to locate, imagine if the function included hundreds of -lines of code. +The function shown in the following example has a in the `foreach` loop. While this particular +comment may not be that difficult to locate, imagine if the function included hundreds of lines of +code. ```powershell function Test-MrVerboseOutput { @@ -587,15 +587,15 @@ function Test-MrVerboseOutput { ) foreach ($Computer in $ComputerName) { - #Attempting to perform some action on $Computer <<-- Don't use - #inline comments like this, use write verbose instead. + # Attempting to perform some action on $Computer Write-Output $Computer } } ``` -A better option is to use `Write-Verbose` instead of inline comments. +Rather than using comments like this, a better option is to use `Write-Verbose` so that the +information can be seen by the user if they want it. ```powershell function Test-MrVerboseOutput { @@ -614,14 +614,13 @@ function Test-MrVerboseOutput { } ``` -When the function is called without the **Verbose** parameter, the verbose output won't be -displayed. +When you call the function without the **Verbose** parameter, the verbose output isn't displayed. ```powershell Test-MrVerboseOutput -ComputerName Server01, Server02 ``` -When it's called with the **Verbose** parameter, the verbose output will be displayed. +When it's called with the **Verbose** parameter, the function displays the verbose output. ```powershell Test-MrVerboseOutput -ComputerName Server01, Server02 -Verbose