From 8aac8cb3f048fa76950e4270b0f68b5db577b538 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 9 Jan 2025 11:44:29 -0600 Subject: [PATCH 1/2] Fix formatting and standardize terms for comments --- .../About/about_Comment_Based_Help.md | 296 ++++++++--------- .../About/about_Data_Sections.md | 86 ++--- .../About/about_Split.md | 64 ++-- .../ConvertFrom-StringData.md | 38 +-- .../Import-Csv.md | 35 +- .../About/about_Comment_Based_Help.md | 296 ++++++++--------- .../About/about_Data_Sections.md | 86 ++--- .../About/about_Split.md | 24 +- .../ConvertFrom-StringData.md | 38 ++- .../Import-Csv.md | 39 +-- .../About/about_Comment_Based_Help.md | 301 +++++++++--------- .../About/about_Data_Sections.md | 89 +++--- .../About/about_Split.md | 25 +- .../ConvertFrom-StringData.md | 38 ++- .../Import-Csv.md | 39 +-- .../learn/ps101/09-functions.md | 23 +- 16 files changed, 761 insertions(+), 756 deletions(-) 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/Import-Csv.md b/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md index b71a56b4bdfa..26fdca6d62fb 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,6 +279,8 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` +The following command gets the **H1** property values and displays a warning. + ```powershell (Import-Csv -Path .\Projects.csv).H1 ``` @@ -291,12 +293,11 @@ FarEast Europe ``` -To create your Projects.csv file, use the values shown in the example's `Get-Content` output. +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 +310,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 +358,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 +383,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 +458,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 +477,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/Import-Csv.md b/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md index 9ca2e5c43db7..b3fc4eb676b6 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,6 +292,8 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` +The following command gets the **H1** property values and displays a warning. + ```powershell (Import-Csv -Path .\Projects.csv).H1 ``` @@ -304,12 +306,11 @@ FarEast Europe ``` -To create your Projects.csv file, use the values shown in the example's `Get-Content` output. +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 +323,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 +387,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 +412,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 +488,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 +507,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/Import-Csv.md b/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md index 08fc3f3550dc..f8a988530cd0 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,6 +292,8 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` +The following command gets the **H1** property values and displays a warning. + ```powershell (Import-Csv -Path .\Projects.csv).H1 ``` @@ -304,12 +306,11 @@ FarEast Europe ``` -To create your Projects.csv file, use the values shown in the example's `Get-Content` output. +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 +323,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 +387,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 +412,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 +488,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 +507,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/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 From 589cbb4f11eba62e7769bd548f8f31d3bc269c6b Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 9 Jan 2025 11:52:19 -0600 Subject: [PATCH 2/2] Fix schema violation --- .../Microsoft.PowerShell.Utility/Import-Csv.md | 16 ---------------- .../Microsoft.PowerShell.Utility/Import-Csv.md | 16 ---------------- .../Microsoft.PowerShell.Utility/Import-Csv.md | 16 ---------------- 3 files changed, 48 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md b/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md index 26fdca6d62fb..c41a2051f7fd 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md @@ -279,22 +279,6 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` -The following command gets the **H1** property values and displays a warning. - -```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. diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md b/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md index b3fc4eb676b6..372a68495796 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Import-Csv.md @@ -292,22 +292,6 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` -The following command gets the **H1** property values and displays a warning. - -```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. diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md b/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md index f8a988530cd0..5abfd86eae3c 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Import-Csv.md @@ -292,22 +292,6 @@ ProjectID ProjectName H1 Completed 469 Marketing Europe False ``` -The following command gets the **H1** property values and displays a warning. - -```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.