New to Telerik Document Processing? Start a free 30-day trial

EmbeddedFilesCollection

Class

Attachment store for embedded files; add, rename, and remove files, with single ZUGFeRD/Factur‑X invoice support when present.

Definition

Namespace:Telerik.Windows.Documents.Fixed.Model.Collections

Assembly:Telerik.Windows.Documents.Fixed.dll

Syntax:

public sealed class EmbeddedFilesCollection : NamedCollectionBase<EmbeddedFile>, IEnumerable<EmbeddedFile>, IEnumerable

Inheritance: objectNamedCollectionBase<EmbeddedFile>EmbeddedFilesCollection

Implements: IEnumerableIEnumerable<EmbeddedFile>

Methods

Add(string, byte[])

EmbeddedFile

Creates and adds a new embedded file with the specified name and binary data to the collection.

public EmbeddedFile Add(string name, byte[] data)

Parameters:namestring

The name to assign to the embedded file.

databyte[]

The binary data content of the embedded file.

Returns:

EmbeddedFile

The newly created embedded file instance.

Exceptions:

ArgumentException

Thrown when the name is null or empty.

ArgumentNullException

Thrown when the data is null.

DuplicatedEmbeddedFileNameException

Thrown when an embedded file with the same name already exists in the collection.

AddZugferdInvoice(byte[], ZugferdConformanceLevel)

EmbeddedFile

Creates and adds a ZUGFeRD-compliant embedded invoice file to the collection with basic conformance level.

public EmbeddedFile AddZugferdInvoice(byte[] data, ZugferdConformanceLevel level = ZugferdConformanceLevel.Basic)

Parameters:databyte[]

The raw XML bytes of the invoice to embed. This should contain a valid ZUGFeRD/Factur-X compliant XML document.

levelZugferdConformanceLevel

The ZUGFeRD/Factur-X conformance level to apply when exporting the PDF. Defaults to Basic. Supported values are Minimum, Basic, Comfort, Extended and XRechnung.

Returns:

EmbeddedFile

The newly created embedded file representing the invoice.

Exceptions:

ArgumentNullException

Thrown when data is null.

NotSupportedException

Thrown when an invoice attachment is already present. Only one ZUGFeRD/Factur-X invoice per document is allowed.

Remarks:

If an invoice already exists (detected by common invoice filenames such as "ZUGFeRD-invoice.xml", "zugferd-invoice.xml", "factur-x.xml", or "xrechnung.xml"), the method throws.
The specified level is stored in the collection and used during PDF export.
For XRechnung, the embedded invoice file name is fixed to "xrechnung.xml".
To replace an existing invoice, call RemoveZugferdInvoice() before adding a new one.

Clear()

Removes all embedded files from the collection.

public void Clear()

ContainsName(string)

bool

Determines whether an embedded file with the specified name exists in the collection.

public bool ContainsName(string name)

Parameters:namestring

The name to search for in the collection.

Returns:

bool

True if an embedded file with the specified name exists; otherwise, false.

Exceptions:

ArgumentNullException

Thrown when the name parameter is null.

GetEnumerator()

IEnumerator<EmbeddedFile>

Returns an enumerator that iterates through the collection.

public override IEnumerator<EmbeddedFile> GetEnumerator()

Returns:

IEnumerator<EmbeddedFile>

An enumerator for the collection.

Overrides: NamedCollectionBase<EmbeddedFile>.GetEnumerator()

IncrementFileNameOverride(ref int, string[], string, string)

string

Generates an incremented version of the provided name if it already exists in the collection.

protected override string IncrementFileNameOverride(ref int counter, string[] splitName, string fileName, string newName)

Parameters:counterint

The current counter value used for generating unique suffixes.

splitNamestring[]

The name components split by dot separators.

fileNamestring

The base file name without extension or numeric suffix.

newNamestring

The candidate new name to check for uniqueness.

Returns:

string

A unique name that doesn't conflict with existing names in the collection.

Overrides: NamedCollectionBase<EmbeddedFile>.IncrementFileNameOverride(ref int, string[], string, string)

Remove(string)

bool

Removes the embedded file with the specified name from the collection and cleans up its parent associations.

public bool Remove(string name)

Parameters:namestring

The name of the embedded file to remove.

Returns:

bool

True if the embedded file was successfully found and removed; otherwise, false.

Exceptions:

ArgumentException

Thrown when the name parameter is null.

RemoveZugferdInvoice()

bool

Removes all ZUGFeRD invoice files from the collection.

public bool RemoveZugferdInvoice()

Returns:

bool

True if any ZUGFeRD invoice files were successfully found and removed; otherwise, false.

Rename(string, string)

Changes the name of an existing embedded file in the collection.

public void Rename(string oldName, string newName)

Parameters:oldNamestring

The current name of the embedded file to rename.

newNamestring

The new name to assign to the embedded file.

VerifyCollectionLimit()

Verifies that the collection has not exceeded its maximum capacity limit.

protected override void VerifyCollectionLimit()

Exceptions:

InvalidOperationException

Thrown when the collection size exceeds the maximum allowed limit.

Overrides: NamedCollectionBase<EmbeddedFile>.VerifyCollectionLimit()

Properties

ContainsZugferdInvoice

bool

Indicates whether the collection contains a ZUGFeRD (or Factur‑X) invoice file.

public bool ContainsZugferdInvoice { get; }

Property Value:

True if the collection contains a ZUGFeRD invoice file; otherwise, false.

Count

int

Number of embedded files in the collection.

public int Count { get; }

Names

IEnumerable<string>

Collection of names of the embedded files.

public IEnumerable<string> Names { get; }

this[string]

EmbeddedFile

Get the embedded file associated with the specified name.

public EmbeddedFile this[string name] { get; }

Parameters:namestring

The name of the embedded file to retrieve.

Property Value:

The embedded file with the specified name.

Exceptions:

KeyNotFoundException

Thrown when no embedded file with the specified name exists in the collection.