Pipeline, Object, and DSL Workflows

PSWriteOffice supports several script shapes because a one-line export and a multi-section report are different jobs. Choose the smallest surface that still makes the document structure clear.

Quick jobs: use the pipeline

When PowerShell objects already have the rows you want, send them directly to an export command:

$services | Export-OfficeExcel -Path '.\Services.xlsx' -WorksheetName 'Services' -TableName 'Services'

This is the closest fit for inventory exports, query results, and data passed from modules such as DbaClientX. Start here unless the workbook needs several sheets, formulas, charts, or carefully placed content.

Incremental jobs: keep the document object

Use an object when normal PowerShell control flow decides what to add. Create the document with -NoSave, pass it through composition commands, then save and close it once.

$document = New-OfficeWord -Path '.\Access-Review.docx' -NoSave
$heading = $document | Add-OfficeWordParagraph -Text 'Access review' -Style Heading1 -PassThru
$heading | Add-OfficeWordText -Text ' — weekly summary' -Color '#475569'

Add-OfficeWordTable -Document $document -InputObject $findings -Style GridTable4Accent1
$document | Save-OfficeWord
$document | Close-OfficeWord

The same model works for Excel:

$workbook = New-OfficeExcel -Path '.\Projects.xlsx' -NoSave
$sheet = $workbook | Add-OfficeExcelSheet -Name 'Projects' -PassThru
$sheet | Set-OfficeExcelCell -Address A1 -Value 'Delivery portfolio'
Add-OfficeExcelTable -Worksheet $sheet -InputObject $projects -StartRow 3 -TableName 'Projects' -AutoFit
$workbook | Save-OfficeExcel
$workbook | Close-OfficeExcel

PowerPoint and Markdown also expose explicit presentation or document targets. See the Word, Excel, PowerPoint, and Markdown object recipes for complete scripts.

Complete authored documents: use the DSL

Use the DSL when the script owns the whole artifact and its nested structure is easier to read as one composition block:

PdfNew -Path '.\Service-Report.pdf' {
    PdfTheme Report
    PdfHeading 'Service report'
    PdfParagraph 'Prepared for the weekly operations review.'
    PdfTable -InputObject $services
}

Choose either short aliases or canonical New-Office* and Add-Office* names for a block. Do not mix both styles in the same example. Saved constructors are quiet; add -PassThru only when another command needs the saved file.

PDF flowing content is composed through its DSL. Canvas, stamp, and page-overlay commands handle fixed coordinates after a PDF exists. See position PDF content for those cases.

Existing files: open, target, save, close

Do not rebuild a document when the task is a bounded update. Open the existing file, identify the native object to change, write a new result while developing, and close the document:

$document = Get-OfficeWord -Path '.\Proposal.docx'
$paragraph = Find-OfficeWordText -Document $document -Text '{{CustomerName}}' | Select-Object -First 1
Set-OfficeWordText -Paragraph $paragraph -Text 'Contoso'
$document | Save-OfficeWord -Path '.\Proposal-Contoso.docx'
$document | Close-OfficeWord

The exact target differs by format—paragraph, cell, slide, page, form field, or annotation—but the lifecycle stays recognizable.

A practical rule

All of these routes use the same OfficeIMO engines. They are complementary public surfaces, not separate feature sets.