Skip to content

Commit 0a55ed6

Browse files
Update CSV cmdlet -Delimiter parameter description (#12617)
* Update CSV cmdlet -Delimiter param description This clarifies the deserialization behavior when the specified delimiter doesn't match the actual delimiter in the input data. Before this change, the verbiage for Import/ConvertFrom-Csv implied one or more strings would be returned, which isn't the case. This also adds the existing note regarding escaped special characters to all docs. Previously, this was only present in Import-Csv docs, but is applicable to/useful for all CSV cmdlets. * Apply suggestions from review --------- Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com>
1 parent 6c4d0ff commit 0a55ed6

File tree

16 files changed

+193
-102
lines changed

16 files changed

+193
-102
lines changed

reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,15 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 11/18/2025
5+
ms.date: 12/27/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-csv?view=powershell-5.1&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
title: ConvertFrom-Csv
99
---
1010
# ConvertFrom-Csv
1111

1212
## SYNOPSIS
13+
1314
Converts object properties in character-separated value (CSV) format into CSV versions of the
1415
original objects.
1516

@@ -145,7 +146,7 @@ the **InputObject** parameter and converts the CSV strings from the `$Services`
145146

146147
When the **UseCulture** parameter is used, be sure that the current culture's default list
147148
separator matches the delimiter used in the CSV strings. Otherwise, `ConvertFrom-Csv` can't
148-
generate objects from the CSV strings.
149+
can't parse each column into distinct properties.
149150

150151
### Example 5: Convert CSV data in W3C Extended Log Format
151152

@@ -176,12 +177,17 @@ time cs-method cs-uri
176177

177178
### -Delimiter
178179

179-
Specifies the delimiter that separates the property values in the CSV strings. The default is a
180-
comma (`,`). Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose it in
181-
single quotation marks.
180+
Specifies the delimiter that separates the property values in the CSV data. The default is a comma
181+
(`,`).
182+
183+
Enter a character, such as a colon (`:`). To specify a semicolon (`;`), enclose it in single
184+
quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double
185+
quotation marks.
182186

183-
If you specify a character other than the actual string delimiter in the file, `ConvertFrom-Csv`
184-
can't create the objects from the CSV strings and returns the CSV strings.
187+
If the specified character doesn't match the actual delimiter in the CSV data, `ConvertFrom-Csv`
188+
can't parse each column into distinct properties. In this case, it outputs one **PSCustomObject**
189+
per row, each containing a single property whose name is the full header and whose value is the row
190+
text.
185191

186192
```yaml
187193
Type: System.Char

reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Csv.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 03/14/2023
5+
ms.date: 12/27/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-csv?view=powershell-5.1&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
title: ConvertTo-Csv
@@ -11,6 +11,7 @@ title: ConvertTo-Csv
1111
# ConvertTo-Csv
1212

1313
## SYNOPSIS
14+
1415
Converts .NET objects into a series of character-separated value (CSV) strings.
1516

1617
## SYNTAX
@@ -109,7 +110,10 @@ information header from the CSV output.
109110
### -Delimiter
110111

111112
Specifies the delimiter to separate the property values in CSV strings. The default is a comma
112-
(`,`). Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose it in single
113+
(`,`).
114+
115+
Enter a character, such as a colon (`:`). To specify a semicolon (`;`), enclose it in single
116+
quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double
113117
quotation marks.
114118

115119
```yaml

reference/5.1/Microsoft.PowerShell.Utility/Export-Csv.md

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 03/14/2023
5+
ms.date: 12/27/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/export-csv?view=powershell-5.1&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
aliases:
@@ -13,6 +13,7 @@ title: Export-Csv
1313
# Export-Csv
1414

1515
## SYNOPSIS
16+
1617
Converts objects into a series of character-separated value (CSV) strings and saves the strings to a
1718
file.
1819

@@ -142,11 +143,12 @@ Get-Content -Path .\Processes.csv
142143
The `Get-Culture` cmdlet uses the nested properties **TextInfo** and **ListSeparator** and displays
143144
the current culture's default list separator. The `Get-Process` cmdlet gets **Process** objects. The
144145
process objects are sent down the pipeline to the `Export-Csv` cmdlet. `Export-Csv` converts the
145-
process objects to a series of CSV strings. The **Path** parameter specifies that the `Processes.csv`
146-
file is saved in the current directory. The **UseCulture** parameter uses the current culture's
147-
default list separator as the delimiter. The **NoTypeInformation** parameter removes the **#TYPE**
148-
information header from the CSV output and is not required in PowerShell 6. The `Get-Content` cmdlet
149-
uses the **Path** parameter to display the file located in the current directory.
146+
process objects to a series of CSV strings. The **Path** parameter specifies that the
147+
`Processes.csv` file is saved in the current directory. The **UseCulture** parameter uses the
148+
current culture's default list separator as the delimiter. The **NoTypeInformation** parameter
149+
removes the **#TYPE** information header from the CSV output and is not required in PowerShell 6.
150+
The `Get-Content` cmdlet uses the **Path** parameter to display the file located in the current
151+
directory.
150152

151153
### Example 5: Export processes with type information
152154

@@ -176,10 +178,15 @@ This example describes how to export objects to a CSV file and use the **Append*
176178
objects to an existing file.
177179

178180
```powershell
179-
$AppService = (Get-Service -DisplayName *Application* | Select-Object -Property DisplayName, Status)
181+
$AppService = Get-Service -DisplayName *Application* |
182+
Select-Object -Property DisplayName, Status
183+
180184
$AppService | Export-Csv -Path .\Services.Csv -NoTypeInformation
181185
Get-Content -Path .\Services.Csv
182-
$WinService = (Get-Service -DisplayName *Windows* | Select-Object -Property DisplayName, Status)
186+
187+
$WinService = Get-Service -DisplayName *Windows* |
188+
Select-Object -Property DisplayName, Status
189+
183190
$WinService | Export-Csv -Path .\Services.csv -NoTypeInformation -Append
184191
Get-Content -Path .\Services.Csv
185192
```
@@ -218,7 +225,8 @@ unexpected output is received, troubleshoot the pipeline syntax.
218225

219226
```powershell
220227
Get-Date | Select-Object -Property DateTime, Day, DayOfWeek, DayOfYear |
221-
Export-Csv -Path .\DateTime.csv -NoTypeInformation
228+
Export-Csv -Path .\DateTime.csv -NoTypeInformation
229+
222230
Get-Content -Path .\DateTime.csv
223231
```
224232

@@ -229,7 +237,8 @@ Get-Content -Path .\DateTime.csv
229237

230238
```powershell
231239
Get-Date | Format-Table -Property DateTime, Day, DayOfWeek, DayOfYear |
232-
Export-Csv -Path .\FTDateTime.csv -NoTypeInformation
240+
Export-Csv -Path .\FTDateTime.csv -NoTypeInformation
241+
233242
Get-Content -Path .\FTDateTime.csv
234243
```
235244

@@ -245,10 +254,10 @@ Get-Content -Path .\FTDateTime.csv
245254
The `Get-Date` cmdlet gets the **DateTime** object. The object is sent down the pipeline to the
246255
`Select-Object` cmdlet. `Select-Object` uses the **Property** parameter to select a subset of object
247256
properties. The object is sent down the pipeline to the `Export-Csv` cmdlet. `Export-Csv` converts
248-
the object to a CSV format. The **Path** parameter specifies that the `DateTime.csv` file is saved in
249-
the current directory. The **NoTypeInformation** parameter removes the **#TYPE** information header
250-
from the CSV output and is not required in PowerShell 6. The `Get-Content` cmdlet uses the **Path**
251-
parameter to display the CSV file located in the current directory.
257+
the object to a CSV format. The **Path** parameter specifies that the `DateTime.csv` file is saved
258+
in the current directory. The **NoTypeInformation** parameter removes the **#TYPE** information
259+
header from the CSV output and is not required in PowerShell 6. The `Get-Content` cmdlet uses the
260+
**Path** parameter to display the CSV file located in the current directory.
252261

253262
When the `Format-Table` cmdlet is used within the pipeline to select properties unexpected results
254263
are received. `Format-Table` sends table format objects down the pipeline to the `Export-Csv` cmdlet
@@ -372,8 +381,11 @@ Accept wildcard characters: False
372381
373382
### -Delimiter
374383
375-
Specifies a delimiter to separate the property values. The default is a comma (`,`). Enter a
376-
character, such as a colon (`:`). To specify a semicolon (`;`), enclose it in quotation marks.
384+
Specifies a delimiter to separate the property values. The default is a comma (`,`).
385+
386+
Enter a character, such as a colon (`:`). To specify a semicolon (`;`), enclose it in single
387+
quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double
388+
quotation marks.
377389

378390
```yaml
379391
Type: System.Char

reference/5.1/Microsoft.PowerShell.Utility/Import-Csv.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 01/09/2025
5+
ms.date: 12/27/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/import-csv?view=powershell-5.1&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
aliases:
@@ -13,6 +13,7 @@ title: Import-Csv
1313
# Import-Csv
1414

1515
## SYNOPSIS
16+
1617
Creates table-like custom objects from the items in a character-separated value (CSV) file.
1718

1819
## SYNTAX
@@ -271,8 +272,8 @@ Import-Csv -Path .\Projects.csv
271272
```
272273

273274
```Output
274-
WARNING: One or more headers weren't specified. Default names starting with "H" have been used in
275-
place of any missing headers.
275+
WARNING: One or more headers weren't specified. Default names starting with "H" have been
276+
used in place of any missing headers.
276277
277278
ProjectID ProjectName H1 Completed
278279
--------- ----------- -- ---------
@@ -292,12 +293,14 @@ displays a warning message because **H1** is a default header name.
292293
Specifies the delimiter that separates the property values in the CSV file. The default is a comma
293294
(`,`).
294295

295-
Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose it in single
296+
Enter a character, such as a colon (`:`). To specify a semicolon (`;`), enclose it in single
296297
quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double
297298
quotation marks.
298299

299-
If you specify a character other than the actual string delimiter in the file, `Import-Csv` can't
300-
create the objects from the CSV strings and returns the full CSV strings.
300+
If the specified character doesn't match the actual delimiter in the CSV data, `Import-Csv` can't
301+
parse each column into distinct properties. In this case, it outputs one **PSCustomObject** per
302+
row, each containing a single property whose name is the full header and whose value is the row
303+
text.
301304

302305
```yaml
303306
Type: System.Char

reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,15 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 11/18/2025
5+
ms.date: 12/27/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-csv?view=powershell-7.4&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
title: ConvertFrom-Csv
99
---
1010
# ConvertFrom-Csv
1111

1212
## SYNOPSIS
13+
1314
Converts object properties in character-separated value (CSV) format into CSV versions of the
1415
original objects.
1516

@@ -145,7 +146,7 @@ the **InputObject** parameter and converts the CSV strings from the `$Services`
145146

146147
When the **UseCulture** parameter is used, be sure that the current culture's default list
147148
separator matches the delimiter used in the CSV strings. Otherwise, `ConvertFrom-Csv` can't
148-
generate objects from the CSV strings.
149+
can't parse each column into distinct properties.
149150

150151
### Example 5: Convert CSV data in W3C Extended Log Format
151152

@@ -177,12 +178,17 @@ time cs-method cs-uri
177178

178179
### -Delimiter
179180

180-
Specifies the delimiter that separates the property values in the CSV strings. The default is a
181-
comma (`,`). Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose it in
182-
single quotation marks.
181+
Specifies the delimiter that separates the property values in the CSV data. The default is a comma
182+
(`,`).
183+
184+
Enter a character, such as a colon (`:`). To specify a semicolon (`;`), enclose it in single
185+
quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double
186+
quotation marks.
183187

184-
If you specify a character other than the actual string delimiter in the file, `ConvertFrom-Csv`
185-
can't create the objects from the CSV strings and returns the CSV strings.
188+
If the specified character doesn't match the actual delimiter in the CSV data, `ConvertFrom-Csv`
189+
can't parse each column into distinct properties. In this case, it outputs one **PSCustomObject**
190+
per row, each containing a single property whose name is the full header and whose value is the row
191+
text.
186192

187193
```yaml
188194
Type: System.Char

reference/7.4/Microsoft.PowerShell.Utility/ConvertTo-Csv.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
33
Locale: en-US
44
Module Name: Microsoft.PowerShell.Utility
5-
ms.date: 03/14/2023
5+
ms.date: 12/27/2025
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-csv?view=powershell-7.4&WT.mc_id=ps-gethelp
77
schema: 2.0.0
88
title: ConvertTo-Csv
@@ -11,6 +11,7 @@ title: ConvertTo-Csv
1111
# ConvertTo-Csv
1212

1313
## SYNOPSIS
14+
1415
Converts .NET objects into a series of character-separated value (CSV) strings.
1516

1617
## SYNTAX
@@ -186,7 +187,10 @@ only the key is converted to CSV.
186187
### -Delimiter
187188

188189
Specifies the delimiter to separate the property values in CSV strings. The default is a comma
189-
(`,`). Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose it in single
190+
(`,`).
191+
192+
Enter a character, such as a colon (`:`). To specify a semicolon (`;`), enclose it in single
193+
quotation marks. To specify escaped special characters such as tab (`` `t ``), enclose it in double
190194
quotation marks.
191195

192196
```yaml

0 commit comments

Comments
 (0)