Skip to main content

Search OfficeIMO

Enter a topic, API type, or PowerShell command.

Documentation Search all OfficeIMO/

PSWriteOffice DSL Cookbook

Edit on GitHub

Copy complete PowerShell recipes for Word, Excel, PowerPoint, PDF, Markdown, and multi-format document jobs.

The PSWriteOffice DSL is a set of scoped PowerShell commands for composing documents. With a content block, the outer New-Office* command publishes the completed document. Without a content block it returns a live document for explicit editing and saving. Nested blocks establish the active section, sheet, slide, page, or Markdown document so content commands do not need the document object repeated on every line.

If loops or conditions need to keep and pass explicit document objects, use the companion pipeline, object, and DSL workflow guide.

Choose one command style

Document lifecycle commands use their full names: New-OfficeWord, New-OfficeExcel, New-OfficePowerPoint and New-OfficePdf. Inside the content block, use concise content aliases or full command names.

DSL aliases

$rows = @(
    [pscustomobject]@{ Name = 'Alpha'; Status = 'Ready' }
    [pscustomobject]@{ Name = 'Beta'; Status = 'Review' }
)

New-OfficePdf -Path '.\Status.pdf' -Theme Modern {
    PdfHeading -Text 'Status' -Level 1
    PdfTable -InputObject $rows
}

Canonical cmdlets

New-OfficePdf -Path '.\Status-Canonical.pdf' -Theme Modern {
    Add-OfficePdfHeading -Text 'Status' -Level 1
    Add-OfficePdfTable -InputObject $rows
}

Both styles call the same content commands. PdfHeading maps to Add-OfficePdfHeading, PdfTable maps to Add-OfficePdfTable, and WordSection maps to Add-OfficeWordSection. Use -Theme on the constructor to select the document's visual defaults.

The same plain PowerShell objects can feed an Excel table, PowerPoint chart, PDF table, Word report, or Markdown document. Keep source collection and business calculations outside the DSL. Let the composition block describe the artifact.

Write a formatted line with one command

Pass several strings to WordText -Text when every segment uses the same formatting. The strings are appended to one paragraph:

New-OfficeWord -Path '.\Formatting.docx' {
    WordSection {
        WordText -Text @(
            'This is a text'
            ' that will show '
            'how WordText joins segments '
            'with the same formatting.'
        ) -Font Tahoma -Size 10pt -Color Blue
    }
}

Use a paragraph content block when formatting changes within the line:

WordParagraph {
    WordText 'Owner: ' -Bold
    WordText $finding.Owner
    WordText '    Due: ' -Bold
    WordText $finding.Due
    WordText '    Severity: ' -Bold
    WordText $finding.Severity -Color Crimson
}

The equivalent PDF line uses its own scoped text commands:

PdfParagraph {
    PdfText 'Owner: ' -Bold
    PdfText $finding.Owner
    PdfText '    Due: ' -Bold
    PdfText $finding.Due
}

Each text command applies formatting to the run it adds. Use the same pattern with ExcelCell { ExcelText ... } or PowerPointParagraph { PowerPointText ... }. Runs support bold, italic, underline, strike, foreground color, font, and size; the command reference documents each format's remaining style and link options.

Flowing versus positioned PDF text

A PdfText run is inline content in the normal document flow. It does not have its own starting coordinate. Use the page-level positioning surface when text must begin at a fixed X/Y location:

Add-OfficePdfStamp -Path '.\Report.pdf' -OutputPath '.\Positioned.pdf' -Content {
    PdfCanvasText -Content {
        PdfText 'Owner: ' -Bold
        PdfText 'Platform' -Color '#0F766E'
    } -X 36 -Y 24
}

Canvas coordinates use PDF points from the visual top-left. Add-OfficePdfStamp -X -Y is the shorter choice for one text or image stamp. Add-OfficePdfStamp -OverlayPath positions a complete imported PDF page. See Position text and graphics on PDF pages for the full decision guide and runnable recipe.

Control pipeline output

Saved DSL constructors are silent by default, so they do not need Out-Null or a suppression switch. Add -PassThru only when the next command needs the saved file:

$file = New-OfficePdf -Path '.\Status-Review.pdf' -PassThru {
    PdfHeading 'Status'
    PdfText 'Ready for review.'
}

$file | Select-Object Name, Length, LastWriteTime

Without a content block, New-OfficePdf returns a live document and writes no file. An optional -Path becomes its associated destination; Save-OfficePdf saves to that path or an explicit new one. Close-OfficePdf releases it without saving.

Word recipes

Use Word when the reader needs a flowing, editable report with sections, review features, fields, or forms.

Excel recipes

Use Excel when the data grid, formula model, filtering, chart interaction, or workbook navigation is part of the deliverable.

PowerPoint recipes

Use direct slide composition when the script owns placement. Use a deck plan when the content is semantic and the designer should choose layout variants.

PDF recipes

Use PDF for fixed-layout delivery. Keep an editable source artifact as well when the workflow needs later content changes.

Markdown recipes

Use Markdown when the source should remain diffable, reviewable, and easy to publish into other text or document workflows.

Create several formats from one data model

The multi-format status pack sends one service-status object array into five thin composition blocks:

PowerShell objects
  |-- Markdown status page
  |-- Word owner report
  |-- Excel analysis workbook
  |-- PowerPoint review deck
  `-- PDF delivery copy

This is useful when audiences need different artifacts but the numbers and status labels must remain consistent. Calculate the data once, then keep each document block focused on how that audience consumes it.

Run and adapt a recipe

For reports that combine headings, tables and charts, use document spacing and table padding to keep each section readable. The patch compliance recipe creates both an editable Word document and a PDF delivery copy.

.\Examples\Word\Recipe-Word-ProjectStatus.ps1

Replace the sample objects first. Then adjust visual choices such as styles, colors, layout, and labels. Search the PowerShell command reference for exact parameters and accepted values.

The complete example index also covers Visio, Reader, RTF, CSV, HTML review, DbaClientX, ChartForgeX visuals, and Confluence publishing.

Example source