Class PresentationEditor

Namespace

DocToolkit

Assembly

DocToolkit.dll

Opens and edits PowerPoint (.pptx) presentations.

public static class PresentationEditor

Inheritance

object

PresentationEditor

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

Create(IEnumerable<PptxSlide>)

Creates a deck from slides, one slide each.

This exists for content that comes from data rather than from an existing file: there is no template to edit, so ReplaceText(byte[], IReadOnlyDictionary<string, string>) cannot help, and the same slides produce the same CONTENT on every machine — nothing here consults the current culture. Not the same BYTES: the OpenXml SDK mints fresh relationship ids per package, so two calls with identical slides in the same process differ. Do not build a cache key, a content hash or a golden-file test on the bytes.

An empty sequence is valid and produces a valid deck with no slides.

public static byte[] Create(IEnumerable<PptxSlide> slides)

Parameters

slides IEnumerable<PptxSlide>

The slides, in deck order.

Returns

byte[]

Examples

byte[] pptx = PresentationEditor.Create(new[]
{
    PptxSlide.Titled("Quarterly Report", "Revenue up 12%"),
    PptxSlide.Titled("Outlook", "Hiring 3 engineers"),
});

Exceptions

ArgumentNullException

slides is null.

ArgumentException

An element of slides is null.

DocumentConversionException

The deck could not be built.

CreateAsync(IEnumerable<PptxSlide>, Stream, CancellationToken)

Builds a deck from slides and writes it to destination. See Create(IEnumerable<PptxSlide>) for the slide semantics.

destination is written, from its current position, and is not disposed, closed or sought — it belongs to the caller, and may be write-only and forward-only, such as an HTTP response body.

public static Task CreateAsync(IEnumerable<PptxSlide> slides, Stream destination, CancellationToken ct = default)

Parameters

slides IEnumerable<PptxSlide>

The slides, in deck order.

destination Stream

The stream the deck is written to.

ct CancellationToken

Cancels the build and the write to destination.

Returns

Task

Exceptions

ArgumentNullException

slides or destination is null.

ArgumentException

An element of slides is null, or destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The deck could not be built or written.

CreateToFileAsync(IEnumerable<PptxSlide>, string, CancellationToken)

Builds a deck from slides and writes it to outputPath. See Create(IEnumerable<PptxSlide>) for the slide semantics.

Named CreateToFileAsync rather than a third CreateAsync overload, matching CreateToFileAsync(string, IEnumerable<IEnumerable<object?>>, string, CancellationToken): the distinct name keeps which kind of destination a call writes to visible at the call site, rather than resting on the argument type alone.

The deck is built completely before the output is opened. That ordering is what stops a failed build truncating a file that was already there, and it is pinned by FilePathOverloadTests rather than left as a comment — it survives only as long as nobody rewrites this into a streaming write.

public static Task CreateToFileAsync(IEnumerable<PptxSlide> slides, string outputPath, CancellationToken ct = default)

Parameters

slides IEnumerable<PptxSlide>

The slides, in deck order.

outputPath string

Where to write the deck. Overwritten if it exists.

ct CancellationToken

Cancels the write to outputPath.

Returns

Task

Exceptions

ArgumentNullException

slides or outputPath is null.

ArgumentException

outputPath is blank, or an element of slides is null.

DirectoryNotFoundException

outputPath's directory does not exist.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The deck could not be built.

ExtractText(byte[])

All text found on every slide, one entry per text-bearing body, in the order the deck is presented rather than the order the slide parts happen to be related.

A "text-bearing body" is any element holding <a:p> paragraphs: an ordinary shape's <p:txBody>, a shape nested in a group, and a table cell's <a:txBody> alike. Paragraphs within one body are joined with newlines. This is deliberately the same walk ReplaceText(byte[], IReadOnlyDictionary<string, string>) performs, so anything this reports is something that can be replaced and vice versa. Speaker notes and slide masters/layouts are not included.

public static IReadOnlyList<string> ExtractText(byte[] pptx)

Parameters

pptx byte[]

Returns

IReadOnlyList<string>

Exceptions

ArgumentNullException

pptx is null.

ArgumentException

pptx is empty.

DocumentConversionException

The package could not be opened or read.

ExtractTextAsync(Stream, CancellationToken)

Reads a .pptx from source and returns all text found on every slide, one entry per text-bearing body, in deck order — see ExtractText(byte[]) for exactly what counts as a text-bearing body. source is read to its end and is neither disposed, closed nor sought.

public static Task<IReadOnlyList<string>> ExtractTextAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream

ct CancellationToken

Returns

Task<IReadOnlyList<string>>

Exceptions

ArgumentNullException

source is null.

ArgumentException

source is not readable or held no bytes.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The package could not be opened or read.

ExtractTextAsync(string, CancellationToken)

Reads a .pptx from path and returns all text found on every slide, one entry per text-bearing body, in deck order — see ExtractText(byte[]) for exactly what counts as a text-bearing body.

public static Task<IReadOnlyList<string>> ExtractTextAsync(string path, CancellationToken ct = default)

Parameters

path string

The .pptx to read.

ct CancellationToken

Cancels the read.

Returns

Task<IReadOnlyList<string>>

One entry per text-bearing body, in deck order.

Exceptions

ArgumentNullException

path is null.

ArgumentException

path is blank, or the file it names is empty.

FileNotFoundException

path does not exist.

DirectoryNotFoundException

path's directory does not exist.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The package could not be opened or read.

ReplaceText(byte[], IReadOnlyDictionary<string, string>)

Replaces every key with its value across all slide text, returning updated bytes.

PowerPoint routinely splits a single visible word across several <a:t> runs (spell-check state, formatting changes), so a naive per-run replace misses any placeholder that straddles a run boundary. Substitution therefore happens against the concatenated text of each paragraph, but the result is spliced back into only the runs the match actually overlaps: runs outside a match keep their text and their formatting untouched. When a placeholder does straddle runs, the replacement value is written into the run holding its first character and so inherits that run's formatting.

Keys are matched in a single left-to-right pass and the longest key wins at any given offset, so a substituted value is never rescanned for further placeholders. Slides are visited in deck order; speaker notes and slide masters/layouts are not touched.

public static byte[] ReplaceText(byte[] pptx, IReadOnlyDictionary<string, string> replacements)

Parameters

pptx byte[]

replacements IReadOnlyDictionary<string, string>

Returns

byte[]

Exceptions

ArgumentNullException

Either argument is null.

ArgumentException

pptx is empty.

DocumentConversionException

The package could not be opened or edited.

ReplaceTextAsync(Stream, IReadOnlyDictionary<string, string>, Stream, CancellationToken)

Reads a .pptx from source, replaces every key with its value across all slide text, and writes the result to destination — see ReplaceText(byte[], IReadOnlyDictionary<string, string>) for exactly what counts as a match and how formatting survives it.

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

public static Task ReplaceTextAsync(Stream source, IReadOnlyDictionary<string, string> replacements, Stream destination, CancellationToken ct = default)

Parameters

source Stream

The stream the .pptx package is read from.

replacements IReadOnlyDictionary<string, string>

Each key is replaced by its value, longest key wins per match.

destination Stream

The stream the edited .pptx package is written to.

ct CancellationToken

Cancels the read, the edit and the write.

Returns

Task

Exceptions

ArgumentNullException

Any argument is null.

ArgumentException

source is not readable or held no bytes, or destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The package could not be opened or edited.

ReplaceTextAsync(string, string, IReadOnlyDictionary<string, string>, CancellationToken)

Reads a .pptx from inputPath, replaces every key with its value across all slide text, and writes the result to outputPath — see ReplaceText(byte[], IReadOnlyDictionary<string, string>) for exactly what counts as a match and how formatting survives it. The two paths may be the same file: the updated bytes are computed in full before outputPath is opened, so a document that fails to process — cannot be read, or cannot be edited — leaves outputPath untouched. That guarantee does not extend to a failure during the write itself: a full disk, a cancellation, or the process dying mid-write can still leave a partial file, so in-place editing of an irreplaceable document is not crash-safe.

public static Task ReplaceTextAsync(string inputPath, string outputPath, IReadOnlyDictionary<string, string> replacements, CancellationToken ct = default)

Parameters

inputPath string

The .pptx to read.

outputPath string

Where to write the result. Overwritten if it exists.

replacements IReadOnlyDictionary<string, string>

Each key is replaced by its value, longest key wins per match.

ct CancellationToken

Cancels the read and the write.

Returns

Task

Exceptions

ArgumentNullException

A path or replacements is null.

ArgumentException

A path is blank, or the file at inputPath is empty.

FileNotFoundException

inputPath does not exist.

DirectoryNotFoundException

inputPath's or outputPath's directory does not exist.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The package could not be opened or edited.

SlideCount(byte[])

Number of slides in the deck, as counted from the deck's slide list.

public static int SlideCount(byte[] pptx)

Parameters

pptx byte[]

Returns

int

Exceptions

ArgumentNullException

pptx is null.

ArgumentException

pptx is empty.

DocumentConversionException

The package could not be opened or read.

SlideCountAsync(Stream, CancellationToken)

Reads a .pptx from source and returns its slide count, counted from the deck's slide list. source is read to its end and is neither disposed, closed nor sought.

public static Task<int> SlideCountAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream

ct CancellationToken

Returns

Task<int>

Exceptions

ArgumentNullException

source is null.

ArgumentException

source is not readable or held no bytes.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The package could not be opened or read.

SlideCountAsync(string, CancellationToken)

Reads a .pptx from path and returns its slide count, as counted from the deck's slide list — see SlideCount(byte[]) for details.

public static Task<int> SlideCountAsync(string path, CancellationToken ct = default)

Parameters

path string

The .pptx to read.

ct CancellationToken

Cancels the read.

Returns

Task<int>

The number of slides in the deck.

Exceptions

ArgumentNullException

path is null.

ArgumentException

path is blank, or the file it names is empty.

FileNotFoundException

path does not exist.

DirectoryNotFoundException

path's directory does not exist.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The package could not be opened or read.