PSWriteOffice DSL Cookbook
Edit on GitHubCopy 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
- Project status report combines a header and footer, narrative, lists, conditional table rows, a chart, and approval controls.
- Change approval checklist creates a reusable form with a table of contents, content controls, and a watermark.
- Executive report is the larger reference for metadata, bookmarks, footnotes, endnotes, tables, charts, and rich text.
- Word object composition builds the same kind of content through a live document and paragraph targets.
- Inspect, update, merge, and mail merge cover existing-document workflows.
Use Word when the reader needs a flowing, editable report with sections, review features, fields, or forms.
Excel recipes
- Project tracker adds a structured table, status validation, conditional formatting, a chart, print settings, and an index sheet.
- Budget dashboard separates summary formulas and charts from a styled detail table.
- Operational dashboard demonstrates KPI cells, tables, charts, pivots, sparklines, links, threaded comments, print layout, and workbook validation.
- Quick export and Excel object composition show the shorter alternatives to a complete workbook DSL.
- Read, update, merge, compare, and import cover existing-workbook workflows.
Use Excel when the data grid, formula model, filtering, chart interaction, or workbook navigation is part of the deliverable.
PowerPoint recipes
- Quarterly business review creates a title slide, a data chart, a priority table, bullets, and speaker notes.
- Training workshop builds learning objectives, an agenda table, a call-to-action slide, and presenter notes.
- Service brief combines semantic designer plans with direct slide composition, charts, sections, transitions, and inspection.
- PowerPoint object composition keeps a presentation object for loop-driven slide creation.
- Inspect, update, and reuse slides cover existing-presentation workflows.
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
- Service invoice composes invoice metadata, line items, totals, payment terms, headers, footers, and a link.
- Audit report adds findings, bookmarks, page breaks, remediation sections, and interactive form fields.
- Composed PDF report demonstrates themes, backgrounds, borders, rich text, rows, links, bookmarks, tables, and attachments.
- Form data exchange, attachments, and page reordering cover post-composition operations.
- Inspect, merge, split, position, redact, sanitize, and process forms cover completed-PDF workflows.
Use PDF for fixed-layout delivery. Keep an editable source artifact as well when the workflow needs later content changes.
Markdown recipes
- Operations runbook creates front matter, a table of contents, warnings, task lists, code, a validation table, and collapsible rollback steps.
- Release notes creates a release page with metadata, an upgrade callout, a change table, a checklist, code, and known limits.
- Advanced Markdown collects the broader typed Markdown surface in one script.
- Markdown object composition uses an explicit Markdown document target.
- Inspect, publish HTML, and round-trip through Word cover Markdown transformation workflows.
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.