Getting to Know the Power of ConvertTo-Csv

Welcome back to Wahman’s PowerShell Blog! Today, we’re going to take a deep dive into the ConvertTo-Csv cmdlet. This built-in PowerShell cmdlet is a super handy tool when it comes to converting objects into a series of comma-separated value (CSV) strings — especially useful for logging, exporting, or passing data between systems.

What does ConvertTo-Csv do?

In essence, ConvertTo-Csv takes .NET objects and represents them as a collection of CSV-formatted strings, making it easy to pipe, export, or analyze structured data. Whether you’re automating reporting tasks or simply need to serialize objects for later use, this cmdlet has you covered.

Let’s Jump Into Some Examples

Example 1: Basic CSV Conversion

Let’s start with a straightforward example where we convert a custom object into CSV.

$user = [PSCustomObject]@{
    FirstName = "Alice"
    LastName = "Johnson"
    Age = 30
}

$user | ConvertTo-Csv -NoTypeInformation

This will output:

"FirstName","LastName","Age"
"Alice","Johnson","30"

Example 2: Exporting a List of Services

What if you want to export details of running services for auditing?

Get-Service | Where-Object {$_.Status -eq 'Running'} | 
    Select-Object Name, DisplayName, Status | 
    ConvertTo-Csv -NoTypeInformation | 
    Out-File -FilePath "C:\Temp\RunningServices.csv"

This command chains filtering and formatting, and saves the CSV output to a file.

Example 3: Using CSV for Data Transfer

Let’s say you want to pass structured objects between scripts or systems using raw string output:

$computers = Get-ADComputer -Filter * | Select-Object Name, Enabled -First 5
$csvData = $computers | ConvertTo-Csv -NoTypeInformation

# Simulating sending this CSV string via a message queue or saving for later
$csvString = $csvData -join "`n"
Write-Output $csvString

This is great for lightweight, text-based data serialization across systems.

Example 4: Nesting and Objects with Arrays

For advanced scenarios, let’s look at a case where objects might contain arrays. PowerShell will represent these arrays as strings within the CSV, but be aware — consuming such data might require additional parsing.

$projects = @(
    [PSCustomObject]@{
        Project = "Alpha"
        TeamMembers = @("John", "Jane")
    },
    [PSCustomObject]@{
        Project = "Beta"
        TeamMembers = @("Alice", "Bob")
    }
)

$projects | ConvertTo-Csv -NoTypeInformation

Output:

"Project","TeamMembers"
"Alpha","System.Object[]"
"Beta","System.Object[]"

Oops! ☝️ This example highlights a limitation: arrays in properties get serialized poorly and must be flattened or converted to strings manually. You can fix it like this:

$projectsFixed = $projects | ForEach-Object {
    [PSCustomObject]@{
        Project = $_.Project
        TeamMembers = ($_.TeamMembers -join "; ")
    }
}

$projectsFixed | ConvertTo-Csv -NoTypeInformation

Now you’ll get:

"Project","TeamMembers"
"Alpha","John; Jane"
"Beta","Alice; Bob"

Wrap-Up

As we’ve seen, ConvertTo-Csv is an excellent cmdlet for converting and exporting structured data in PowerShell. Whether you’re working with small sets of objects or dealing with complex nested structures, CSV output is a familiar and versatile format.

Happy scripting, and I will see you in the next post!