Skip to content

Commit

Permalink
Document new Export-Csv and ConvertTo-Cs behavior and cleanup docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@markekraus @juanpablojofre
markekraus authored and juanpablojofre committed Oct 25, 2017
1 parent 2c1c076 commit a3e883a
Show file tree
Hide file tree
Showing 2 changed files with 144 additions and 137 deletions.
103 changes: 47 additions & 56 deletions reference/6/Microsoft.PowerShell.Utility/ConvertTo-Csv.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,32 +17,33 @@ Converts objects into a series of comma-separated value (CSV) variable-length st

### Delimiter (Default)
```
ConvertTo-Csv [-InputObject] <PSObject> [[-Delimiter] <Char>] [-NoTypeInformation]
[-InformationAction <ActionPreference>] [-InformationVariable <String>] [<CommonParameters>]
ConvertTo-Csv [-InputObject] <PSObject> [[-Delimiter] <Char>] [-IncludeTypeInformation] [-NoTypeInformation]
```

### UseCulture
```
ConvertTo-Csv [-InputObject] <PSObject> [-UseCulture] [-NoTypeInformation]
[-InformationAction <ActionPreference>] [-InformationVariable <String>] [<CommonParameters>]
ConvertTo-Csv [-InputObject] <PSObject> [-UseCulture] [-IncludeTypeInformation] [-NoTypeInformation]
```

## DESCRIPTION
The **ConvertTo-CSV** cmdlet returns a series of comma-separated (CSV) strings that represents the objects that you submit.
You can then use the ConvertFrom-Csv cmdlet to re-create objects from the CSV strings.
The `ConvertTo-CSV` cmdlet returns a series of comma-separated (CSV) strings that represents the objects that you submit.
You can then use the `ConvertFrom-Csv` cmdlet to re-create objects from the CSV strings.
The resulting objects are CSV versions of the original objects that consist of string representations of the property values and no methods.

You can also use the Export-Csv and Import-Csv cmdlets to convert objects to CSV strings and back.
**Export-CSV** is the same as **ConvertTo-CSV**, except that it saves the CSV strings to a file.
You can also use the `Export-Csv` and `Import-Csv` cmdlets to convert objects to CSV strings and back.
`Export-CSV` is the same as `ConvertTo-CSV`, except that it saves the CSV strings to a file.

You can use the parameters of the **ConvertTo-CSV** cmdlet to specify a delimiter other than a comma or to direct **ConvertTo-CSV** to use the default delimiter for the current culture.
You can use the parameters of the `ConvertTo-CSV` cmdlet to specify a delimiter other than a comma or to direct `ConvertTo-CSV` to use the default delimiter for the current culture.

## EXAMPLES

### Example 1: Convert an object to CSV
```powershell
Get-Process powershell | ConvertTo-Csv
```
PS C:\> Get-Process powershell | ConvertTo-Csv
#TYPE System.Diagnostics.Process

Result:
```none
"__NounName","Name","Handles","VM","WS","PM","NPM","Path","Company","CPU","FileVersion","ProductVersion","Description",
"Product","BasePriority","ExitCode","HasExited","ExitTime","Handle","HandleCount","Id","MachineName","MainWindowHandle"
,"MainWindowTitle","MainModule","MaxWorkingSet","MinWorkingSet","Modules","NonpagedSystemMemorySize","NonpagedSystemMem
Expand All @@ -63,44 +64,43 @@ cs.ProcessModuleCollection","21692","21692","63197184","63197184","320080","3200
```

This command converts a single process object to CSV format.
The command uses the Get-Process cmdlet to get the PowerShell process on the local computer.
It uses a pipeline operator (|) to send the command to the **ConvertTo-CSV** cmdlet, which converts it to a series of comma-separated strings.
The command uses the `Get-Process` cmdlet to get the PowerShell process on the local computer.
It uses a pipeline operator (`|`) to send the command to the `ConvertTo-CSV` cmdlet, which converts it to a series of comma-separated strings.

### Example 2: Convert a DateTime object to CSV
```
PS C:\> $Date = Get-Date
PS C:\> ConvertTo-Csv -InputObject $Date -Delimiter ";" -NoTypeInformation
```powershell
$Date = Get-Date
ConvertTo-Csv -InputObject $Date -Delimiter ";"
```

This example converts a **DateTime** object to CSV format.
This example converts a `DateTime` object to CSV format.

The first command uses the Get-Date cmdlet to get the current date.
It saves it in the $Date variable.
The first command uses the `Get-Date` cmdlet to get the current date.
It saves it in the `$Date` variable.

The second command uses the **ConvertTo-CSV** cmdlet to convert the **DateTime** object in the $Date variable to CSV format.
The command uses the *InputObject* parameter to specify the object to be converted.
It uses the *Delimiter* parameter to specify the delimiter that separates the object properties.
It uses the *NoTypeInformation* parameter to suppress the #TYPE string.
The second command uses the `ConvertTo-CSV` cmdlet to convert the `DateTime` object in the `$Date` variable to CSV format.
The command uses the `-InputObject` parameter to specify the object to be converted.
It uses the `-Delimiter` parameter to specify the delimiter that separates the object properties.

### Example 3: Convert the PowerShell event log to CSV
```
PS C:\> Get-EventLog -Log "windows powershell" | ConvertTo-Csv -UseCulture
```powershell
Get-EventLog -Log "windows powershell" | ConvertTo-Csv -UseCulture
```

This command converts the Windows PowerShell event log on the local computer to a series of CSV strings.

The command uses the Get-EventLog cmdlet to get the events in the Windows PowerShell log.
A pipeline operator (|) sends the events to the **ConvertTo-CSV** cmdlet, which converts the events to CSV format.
The command uses the *UseCulture* parameter, which uses the list separator for the current culture as the delimiter.
The command uses the `Get-EventLog` cmdlet to get the events in the Windows PowerShell log.
A pipeline operator (`|`) sends the events to the `ConvertTo-CSV` cmdlet, which converts the events to CSV format.
The command uses the `-UseCulture` parameter, which uses the list separator for the current culture as the delimiter.

## PARAMETERS

### -Delimiter
Specifies a delimiter to separate the property values.
The default is a comma (,).
Enter a character, such as a colon (:).
The default is a comma (`,`).
Enter a character, such as a colon (`:`).

To specify a semicolon (;), enclose it in quotation marks.
To specify a semicolon (`;`), enclose it in quotation marks.
Otherwise, it will be interpreted as the command delimiter.

```yaml
Expand All @@ -115,25 +115,16 @@ Accept pipeline input: False
Accept wildcard characters: False
```
### -InformationAction
To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.```yaml
Type: ActionPreference
Parameter Sets: (All)
Aliases: infa
Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend
### -IncludeTypeInformation
Indicates that this cmdlet includes the type information in the output.
When supplied, the first line of the output contains `#TYPE` followed by the fully-qualified name of the type of the object.

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```
This parameter was introduced in PowerShell 6.0.

### -InformationVariable
To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.```yaml
Type: String
```yaml
Type: SwitchParameter
Parameter Sets: (All)
Aliases: iv
Aliases: ITI
Required: False
Position: Named
Expand All @@ -145,7 +136,7 @@ Accept wildcard characters: False
### -InputObject
Specifies the objects to export as CSV strings.
Enter a variable that contains the objects or type a command or expression that gets the objects.
You can also pipe objects to **ConvertTo-CSV**.
You can also pipe objects to `ConvertTo-CSV`.

```yaml
Type: PSObject
Expand All @@ -161,7 +152,7 @@ Accept wildcard characters: False

### -NoTypeInformation
Omits the type information header from the output.
By default, the string in the output contains #TYPE followed by the fully-qualified name of the object type.
This behavior is default beginning with PowerShell 6.0. This parameter is included for backwards compatibility.

```yaml
Type: SwitchParameter
Expand All @@ -177,7 +168,7 @@ Accept wildcard characters: False

### -UseCulture
Uses the list separator for the current culture as the data delimiter.
The default is a comma (,).
The default is a comma (`,`).

This parameter is very useful in scripts that are being distributed to users worldwide.
To find the list separator for a culture, use the following command: `(Get-Culture).TextInfo.ListSeparator`.
Expand All @@ -200,27 +191,27 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
## INPUTS

### System.Management.Automation.PSObject
You can pipe any object that has an Extended Type System (ETS) adapter to **ConvertTo-CSV**.
You can pipe any object that has an Extended Type System (ETS) adapter to `ConvertTo-CSV`.

## OUTPUTS

### System.String
The CSV output is returned as a collection of strings.

## NOTES
* In CSV format, each object is represented by a comma-separated list of its property value. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. **ConvertTo-CSV** does not export the methods of the object.
* In CSV format, each object is represented by a comma-separated list of its property value. The property values are converted to strings (by using the `ToString()` method of the object), so they are generally represented by the name of the property value. `ConvertTo-CSV` does not export the methods of the object.

The format of the resulting CSV strings is as follows:

- The first string consists of #TYPE followed by the fully-qualified name of the object type, such as #TYPE System.Diagnostics.Process.
To suppress this string, use the *NoTypeInformation* parameter.
- If `-IncludeTypeInformation` is supplied, the first string consists of #TYPE followed by the fully-qualified name of the object type, such as `#TYPE System.Diagnostics.Process`.

- The next string represents the column headers.
- The next string (or first string if `-IncludeTypeInformation` is not supplied) represents the column headers.
It contains a comma-separated list of the names of all the properties of the first object.

- The remaining strings consist of comma-separated lists of the property values of each object.

* When you submit multiple objects to **ConvertTo-CSV**, **ConvertTo-CSV** orders the strings based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is Null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are ignored.
* When you submit multiple objects to `ConvertTo-CSV`, `ConvertTo-CSV` orders the strings based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is Null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are ignored.
* Beginning with PowerShell 6.0 the default behavior of `ConvertTo-CSV` is to no longer include type information in the CSV and `-NoTypeInformation` is implied. `-IncludeTypeInformation` can be used to include the Type Information and emulate the default behavior of `ConvertTo-CSV` prior to PowerShell 6.0.

## RELATED LINKS

Expand Down
Loading

0 comments on commit a3e883a

Please sign in to comment.