Project

PSWriteOffice

PowerShell document automation across Word, Excel, PowerPoint, PDF, Reader, Confluence, Visio, and open text formats.

Stars 159

Forks 14

PowerShell Gallery downloads 158,661

Release v3.0.5

Language: C# Updated: 2026-09-03

API Reference

Cmdlet

Add-OfficePdfBackgroundShape

Aliases: PdfBackgroundShape

Namespace PSWriteOffice

Aliases

PdfBackgroundShape

Inputs

OfficeIMO.Pdf.PdfDocument

Outputs

OfficeIMO.Pdf.PdfDocument

Source

Sources/PSWriteOffice/Cmdlets/Pdf/AddOfficePdfBackgroundShapeCommand.cs:25 Edit on GitHub

Adds a decorative generated PDF page background shape or band.

Remarks

Background shapes are intended for subtle page structure such as header bands, side bands, highlight panels, or decorative accents. They are rendered behind generated content and should usually use restrained opacity values.

Examples

Authored help example

Add a header band and accent ellipse.

PS>


New-OfficePdf -Path .\Report.pdf {
                PdfBackgroundShape -Shape TopBand -Height 86 -FillColor '#DBEAFE' -FillOpacity 0.75
                PdfBackgroundShape -Shape Ellipse -X 420 -Y 650 -Width 96 -Height 72 -FillColor '#99F6E4' -FillOpacity 0.35
                PdfHeading 'Styled report'
              }

Creates a polished generated page background without hand-drawing PDF primitives.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.

Syntax

Add-OfficePdfBackgroundShape [-CornerRadius <Double>] [-FillColor <String>] [-FillOpacity <Double>] [-Height <Double>] [-InsetX <Double>] [-InsetY <Double>] [-OffsetX <Double>] [-OffsetY <Double>] [-PassThru] -Shape <Rectangle> [-StrokeColor <String>] [-StrokeOpacity <Double>] [-StrokeWidth <Double>] [-Width <Double>] [-X <Double>] [-Y <Double>] [<CommonParameters>]

Parameter set: Context

Parameters

CornerRadius Double optionalposition: namedpipeline: False: Rounded rectangle or band corner radius in PDF points.
FillColor String optionalposition: namedpipeline: False: Fill color. Named colors and hexadecimal values are accepted.
FillOpacity Double optionalposition: namedpipeline: False: Fill opacity from 0 to 1.
Height Double optionalposition: namedpipeline: False: Shape height in PDF points, or band height for top/bottom bands.
InsetX Double optionalposition: namedpipeline: False: Horizontal inset for top/bottom bands in PDF points.
InsetY Double optionalposition: namedpipeline: False: Vertical inset for left/right bands in PDF points.
OffsetX Double optionalposition: namedpipeline: False: Horizontal offset for left/right bands in PDF points.
OffsetY Double optionalposition: namedpipeline: False: Vertical offset for top/bottom bands in PDF points.
PassThru SwitchParameter optionalposition: namedpipeline: False: Emit the updated document.
Shape OfficePdfBackgroundShapeType requiredposition: 0pipeline: Falsevalues: 7: Shape type to add.; Possible values: Rectangle, RoundedRectangle, Ellipse, TopBand, BottomBand, LeftBand, RightBand
StrokeColor String optionalposition: namedpipeline: False: Stroke color. Named colors and hexadecimal values are accepted.
StrokeOpacity Double optionalposition: namedpipeline: False: Stroke opacity from 0 to 1.
StrokeWidth Double optionalposition: namedpipeline: False: Stroke width in PDF points.
Width Double optionalposition: namedpipeline: False: Shape width in PDF points, or band width for left/right bands.
X Double optionalposition: namedpipeline: False: Shape left coordinate in PDF points for explicit shapes.
Y Double optionalposition: namedpipeline: False: Shape bottom coordinate in PDF points for explicit shapes.

Outputs

OfficeIMO.Pdf.PdfDocument

Add-OfficePdfBackgroundShape [-CornerRadius <Double>] -Document <PdfDocument> [-FillColor <String>] [-FillOpacity <Double>] [-Height <Double>] [-InsetX <Double>] [-InsetY <Double>] [-OffsetX <Double>] [-OffsetY <Double>] [-PassThru] -Shape <Rectangle> [-StrokeColor <String>] [-StrokeOpacity <Double>] [-StrokeWidth <Double>] [-Width <Double>] [-X <Double>] [-Y <Double>] [<CommonParameters>]

Parameter set: Document

Parameters

CornerRadius Double optionalposition: namedpipeline: False: Rounded rectangle or band corner radius in PDF points.
Document PdfDocument requiredposition: namedpipeline: True (ByValue): Compatibility parameter. Page composition is supported only inside New-OfficePdf with OfficeIMO 3.2.
FillColor String optionalposition: namedpipeline: False: Fill color. Named colors and hexadecimal values are accepted.
FillOpacity Double optionalposition: namedpipeline: False: Fill opacity from 0 to 1.
Height Double optionalposition: namedpipeline: False: Shape height in PDF points, or band height for top/bottom bands.
InsetX Double optionalposition: namedpipeline: False: Horizontal inset for top/bottom bands in PDF points.
InsetY Double optionalposition: namedpipeline: False: Vertical inset for left/right bands in PDF points.
OffsetX Double optionalposition: namedpipeline: False: Horizontal offset for left/right bands in PDF points.
OffsetY Double optionalposition: namedpipeline: False: Vertical offset for top/bottom bands in PDF points.
PassThru SwitchParameter optionalposition: namedpipeline: False: Emit the updated document.
Shape OfficePdfBackgroundShapeType requiredposition: 0pipeline: Falsevalues: 7: Shape type to add.; Possible values: Rectangle, RoundedRectangle, Ellipse, TopBand, BottomBand, LeftBand, RightBand
StrokeColor String optionalposition: namedpipeline: False: Stroke color. Named colors and hexadecimal values are accepted.
StrokeOpacity Double optionalposition: namedpipeline: False: Stroke opacity from 0 to 1.
StrokeWidth Double optionalposition: namedpipeline: False: Stroke width in PDF points.
Width Double optionalposition: namedpipeline: False: Shape width in PDF points, or band width for left/right bands.
X Double optionalposition: namedpipeline: False: Shape left coordinate in PDF points for explicit shapes.
Y Double optionalposition: namedpipeline: False: Shape bottom coordinate in PDF points for explicit shapes.

Outputs

OfficeIMO.Pdf.PdfDocument