TB

MoppleIT Tech Blog

Welcome to my personal blog where I share thoughts, ideas, and experiences.

Model Your Data with Classes and Enums in PowerShell: Safer Scripts, Clearer APIs, Pipeline-Friendly Outputs

Published on December 01, 2025 | Category: Tutorial | Tags: PowerShell, classes, enums, DevOps, best practices

Dynamic objects are great for quick scripts, but when your automation grows (deployments, provisioning, data pipelines), weakly typed data becomes a risk. You can make changes safer by giving your data a type and rules. In PowerShell 5+ (and PowerShell 7+), classes and enums let you model your domain, enforce valid states, and keep outputs pipeline-friendly.

In this post, youll see how to define enums for valid states, create small classes that validate in constructors, and expose ToRecord() methods so your outputs remain easy to filter, format, convert to JSON, and pass across remoting sessions. The result: fewer bugs, clearer APIs, safer refactors, and predictable behavior.

Why Types and Rules Matter in PowerShell

PowerShell is flexible, but that flexibility can hide data issues until production. Stronger models help you:

  • Fail fast with clear errors when inputs are invalid.
  • Make breaking changes obvious (rename a property and the compiler/runtime alerts you).
  • Communicate intent to teammates and future you, with self-documenting code.
  • Keep CI/CD pipelines stable by enforcing invariants around your data.

Enums encode valid states. Classes encode shape, rules, and behavior. A ToRecord() method bridges the gap between typed internals and the pipelines love for [pscustomobject].

Modeling Data with Enums and Classes

Define Valid States with Enums

Enums restrict input to known values and give you readable states instead of magic strings.

enum OrderStatus { New; Processing; Done }

Compared to [ValidateSet] on a function parameter, enums also enforce correctness when you set values in code and across methods, not just at the command boundary.

Create a Small, Validating Class

Keep classes focused: required fields, strict typing, and validation in the constructor. Expose a ToRecord() method for pipeline-friendly output.

enum OrderStatus { New; Processing; Done }

class Order {
  [string]$Id
  [OrderStatus]$Status
  [datetime]$CreatedUtc

  Order([string]$id, [string]$status) {
    if ([string]::IsNullOrWhiteSpace($id)) { throw "Id is required." }
    try { $this.Status = [OrderStatus]$status } catch { throw ("Invalid status: {0}" -f $status) }
    $this.Id = $id
    $this.CreatedUtc = (Get-Date).ToUniversalTime()
  }

  [pscustomobject] ToRecord() {
    [pscustomobject]@{
      Id      = $this.Id
      Status  = $this.Status.ToString()
      Created = $this.CreatedUtc.ToString('o')
    }
  }
}

# Usage
$items = @([Order]::new('A100','New'), [Order]::new('A101','Processing'))
$items.ForEach({ $_.ToRecord() }) | Format-Table

Notes:

  • Validation: The constructor throws on invalid IDs or statuses, protecting downstream logic.
  • Serialization safety: Status.ToString() and CreatedUtc.ToString('o') ensure predictable JSON/CSV output (stringified enum, ISO-8601 timestamp).
  • Pipeline friendliness: ToRecord() returns a [pscustomobject], so you can Format-Table, ConvertTo-Json, or export without surprises.

Enforce Transitions with Methods

Put business rules where they belong: on the type. Heres an example enforcing a one-way terminal state.

class Order {
  [string]$Id
  [OrderStatus]$Status
  [datetime]$CreatedUtc

  Order([string]$id, [string]$status) {
    if ([string]::IsNullOrWhiteSpace($id)) { throw "Id is required." }
    try { $this.Status = [OrderStatus]$status } catch { throw ("Invalid status: {0}" -f $status) }
    $this.Id = $id
    $this.CreatedUtc = (Get-Date).ToUniversalTime()
  }

  [void] UpdateStatus([string]$status) {
    $new = $null
    try { $new = [OrderStatus]$status } catch { throw ("Invalid status: {0}" -f $status) }

    if ($this.Status -eq [OrderStatus]::Done -and $new -ne [OrderStatus]::Done) {
      throw "Order is Done and cannot transition back."
    }

    $this.Status = $new
  }

  [pscustomobject] ToRecord() {
    [pscustomobject]@{
      Id      = $this.Id
      Status  = $this.Status.ToString()
      Created = $this.CreatedUtc.ToString('o')
    }
  }
}

Keep the Pipeline Happy: ToRecord Everywhere

You can use strongly typed objects internally while emitting plain records at the edges. This keeps logs, JSON, and reports consistent, and it avoids friction with tools expecting standard PowerShell objects.

Function Boundaries

Accept typed input for safety and return records for interoperability.

function New-Order {
  [CmdletBinding()]
  param(
    [Parameter(Mandatory)] [string]$Id,
    [Parameter(Mandatory)] [ValidateSet('New','Processing','Done')] [string]$Status
  )
  $o = [Order]::new($Id, $Status)
  return $o.ToRecord()
}

function Update-OrderStatus {
  [CmdletBinding()]
  param(
    [Parameter(Mandatory, ValueFromPipeline)] [Order]$Order,
    [Parameter(Mandatory)] [ValidateSet('New','Processing','Done')] [string]$Status
  )
  process {
    $Order.UpdateStatus($Status)
    $Order.ToRecord()
  }
}

Notice how the public functions operate on typed data internally while emitting [pscustomobject] for callers. This pattern lets you mix typed internals with standard automation surfaces.

JSON and CSV Friendly

When you use ToRecord(), your objects serialize predictably:

$orders = @(
  [Order]::new('A100','New'),
  [Order]::new('A101','Processing')
)

$orders.ForEach({ $_.ToRecord() }) |
  ConvertTo-Json -Depth 3 |
  Out-File orders.json

$orders.ForEach({ $_.ToRecord() }) | Export-Csv -Path orders.csv -NoTypeInformation

Tip: Enums may serialize to numeric values in some contexts. Explicitly calling .ToString() avoids ambiguity and improves readability.

Putting It to Work in DevOps and CI/CD

Module Layout

Keep your domain models with your module code so they load where needed.

# Module structure
My.Orders\
  My.Orders.psd1
  My.Orders.psm1   # contains enum+class definitions and public functions
  tests\My.Orders.Tests.ps1

Inside .psm1, place the enum and class definitions at the top, then your public functions. Export only the functions; classes and enums automatically load when the module is imported.

Validation at the Edges

Any data crossing boundaries (files, APIs, queues) should be validated on entry. Convert raw inputs into typed models early and fail fast.

# From CSV to typed Orders
a = Import-Csv .\incoming.csv | ForEach-Object {
  try { [Order]::new($_.Id, $_.Status) } catch { Write-Error $_; return }
}

# From JSON to typed Orders
$json = Get-Content .\incoming.json -Raw | ConvertFrom-Json
$typed = foreach ($r in $json) {
  try { [Order]::new($r.Id, $r.Status) } catch { Write-Error $_; continue }
}

Guardrails in CI

Use Pester to assert model invariants so regressions dont ship.

Describe 'Order model' {
  It 'rejects empty Id' {
    { [Order]::new('', 'New') } | Should -Throw
  }
  It 'rejects invalid status' {
    { [Order]::new('A100', 'Invalid') } | Should -Throw
  }
  It 'prevents transition after Done' {
    $o = [Order]::new('A200','Done')
    { $o.UpdateStatus('Processing') } | Should -Throw
  }
  It 'emits pipeline-friendly record' {
    $o = [Order]::new('A300','New')
    $rec = $o.ToRecord()
    $rec | Should -BeOfType psobject
    $rec.Status | Should -Be 'New'
  }
}

Advanced Tips and Real-World Considerations

Design for Immutability (Where You Can)

PowerShell classes dont have read-only properties, but you can adopt conventions:

  • Only set properties in the constructor.
  • Expose methods for controlled changes (like UpdateStatus).
  • Avoid public setters in critical objects by limiting where they are assigned.

Versioning and Compatibility

  • Classes must be available in the runspace that uses them. In remoting or jobs, ensure the module is imported.
  • When evolving a class, prefer additive changes. Removing or renaming properties can break callers; use ToRecord() to stabilize your outward contract as you refactor internals.

Performance

  • Classes and enums add minimal overhead compared to loose objects, and the correctness gains usually outweigh the cost.
  • For very large datasets, emit records early and avoid keeping large arrays of class instances in memory longer than needed.

Security and Robustness

  • Validate external input at the boundary. Constructor checks and parse/try-catch around enums protect you from malformed data.
  • Normalize timestamps in UTC and ISO 8601 so sorting and auditing are reliable across environments.

Interop with Other Tools

  • Wrap outputs with ToRecord() before calling ConvertTo-Json, Export-Csv, or sending data to REST APIs.
  • Prefer strings for enums and ISO strings for dates to reduce downstream parsing ambiguity in non-.NET tools.

End-to-End Example: Orders in a Deployment Pipeline

Imagine a deployment pipeline that reads work items, processes them, and posts results to a dashboard. Internally, it uses Order to validate and enforce transitions, but outputs ToRecord() for the dashboard and logs.

function Invoke-OrderProcessing {
  [CmdletBinding()]
  param(
    [Parameter(Mandatory, ValueFromPipeline)] [psobject]$InputRecord
  )
  process {
    $o = [Order]::new($InputRecord.Id, $InputRecord.Status)
    if ($o.Status -eq [OrderStatus]::New) { $o.UpdateStatus('Processing') }
    # ... do work ...
    $o.UpdateStatus('Done')
    $o.ToRecord()
  }
}

Import-Csv .\incoming.csv | Invoke-OrderProcessing | Tee-Object .\processed.csv | ConvertTo-Json -Depth 3

This pattern scales to tickets, environments, approvalsanything where state machines and invariants matter.

Wrap-Up

By modeling your data with enums and classes, you create safer, clearer, and more maintainable PowerShell automation. Validate in constructors, enforce transitions with methods, and keep the pipeline happy with ToRecord(). Youll ship fewer bugs, refactor with confidence, and produce consistent outputs for CI/CD, dashboards, and audits.

Build stronger models in PowerShell. Explore the PowerShell Advanced CookBook a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0: https://www.amazon.com/PowerShell-Advanced-Cookbook-scripting-advanced-ebook/dp/B0D5CPP2CQ/

#PowerShell #Classes #Enums #Scripting #BestPractices #PowerShellCookbook #DevOps

← All Posts Home →