Interface ICustomProperties

Interface that represents set of custom metadata properties

Namespace: IronXL.Metadata

Assembly: IronXL.dll

Syntax

public interface ICustomProperties

Application-defined fields that a spreadsheet carries beyond the standard author and title, such as a project code, a review status, or a department tag, live behind ICustomProperties. A developer uses this contract to attach arbitrary named values to a workbook and read them back, the same custom properties Excel exposes under File, Info, Properties, Advanced. Where IMetadata covers the fixed Office fields, ICustomProperties holds the open-ended key/value pairs a team defines for itself.

A developer obtains an ICustomProperties from the metadata: IMetadata.CustomProperties returns it for the open workbook, and there is no constructor to call. The collection is edited in place and saved with the file. AddProperty(string name, object value) stores a named value of any type, Contains(string name) checks whether a key is present, and Remove(string name) deletes one. Reading offers two forms: GetValue(string name) returns an object, while the generic GetValue<T>(string name) returns the value typed, and TryGetValue<T>(string name, out T value) reads it safely without throwing when the key is missing. Prefer the TryGetValue<T> pattern for keys that may not exist.

ICustomProperties properties = workbook.Metadata.CustomProperties;
properties.AddProperty("ProjectCode", "X-42");

The edit Excel metadata example writes document properties, and the edit workbook metadata how-to walks through reading and updating them.

Methods

AddProperty(String, Object)

Method for adding property with the specified name and value.

Available value types are: System.Int32, System.Double, System.String, System.Boolean.

Declaration

void AddProperty(string name, object value)

Parameters

Type	Name	Description
System.String	name	Name of the property.
System.Object	value	Value of the property.

Contains(String)

Method to check whether set of properties contains property with the specified name.

Declaration

bool Contains(string name)

Parameters

Type	Name	Description
System.String	name	Name of the property.

Returns

Type	Description
System.Boolean	true if property with the specified name exists, otherwise false.

GetValue(String)

Method for getting custom property value by its name. See AddProperty(String, Object) for list of possible types.

Declaration

object GetValue(string name)

Parameters

Type	Name	Description
System.String	name	The name of the property.

Returns

Type	Description
System.Object	The value of the property.

GetValue<T>(String)

Unsafe method for getting strongly-typed custom property value by its name. See AddProperty(String, Object) for list of possible types.

Declaration

T GetValue<T>(string name)

Parameters

Type	Name	Description
System.String	name	Name of the property.

Returns

Type	Description
T	Returns default(T) is such property wasn't found

Type Parameters

Name	Description
T

Remove(String)

Method for removing property by its name.

Declaration

bool Remove(string name)

Parameters

Type	Name	Description
System.String	name	The name of the property.

Returns

Type	Description
System.Boolean	true if property was removed, otherwise false.

TryGetValue<T>(String, out T)

Safe method for getting strongly-typed custom property value by its name. See AddProperty(String, Object) for list of possible types.

Declaration

bool TryGetValue<T>(string name, out T value)

Parameters

Type	Name	Description
System.String	name	The name of the property.
T	value	The value of the property..

Returns

Type	Description
System.Boolean	true if value was returned successfully, otherwise false.

Type Parameters

Name	Description
T	Type of the return value.