OfficeRuntime.Storage interface

Package:

office-runtime

Asynchronous, global, and persistent key-value storage.

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This interface is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This interface isn't supported in Outlook on Mac or on the web.

Storage limit is 10 MB per domain, which may be shared by multiple add-ins.

Methods

getItem(key)	Retrieves an item from storage based on its key. Returns a Promise. In the event the Promise does not resolve, returns null.
getItems(keys)	Retrieves multiple items from storage based on their key. Returns a Promise. In the event the Promise does not resolve, returns null.
getKeys()	Retrieves an array of all keys from storage. Returns a Promise.
removeItem(key)	Removes an item from storage based on its key. Returns a Promise.
removeItems(keys)	Removes multiple items from storage. Returns a Promise.
setItem(key, value)	Sets a key-value pair into storage or updates an existing key-value pair. Returns a Promise.
setItems(keyValues)	Sets multiple items into storage or updates multiple items within storage. Returns a Promise.

Method Details

getItem(key)

Retrieves an item from storage based on its key. Returns a Promise. In the event the Promise does not resolve, returns null.

getItem(key: string): Promise<string | null>;

Parameters

key

string

Key of item to be retrieved. Must be a string.

Returns

Promise<string | null>

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This method is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This method isn't supported in Outlook on Mac or on the web.

getItems(keys)

Retrieves multiple items from storage based on their key. Returns a Promise. In the event the Promise does not resolve, returns null.

getItems(keys: string[]): Promise<{ [key: string]: string | null }>;

Parameters

keys

string[]

Keys of items to be removed. Must be an array of strings.

Returns

Promise<{ [key: string]: string | null }>

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This method is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This method isn't supported in Outlook on Mac or on the web.

getKeys()

Retrieves an array of all keys from storage. Returns a Promise.

getKeys(): Promise<string[]>;

Returns

Promise<string[]>

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This method is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This method isn't supported in Outlook on Mac or on the web.

removeItem(key)

Removes an item from storage based on its key. Returns a Promise.

removeItem(key: string): Promise<void>;

Parameters

key

string

Key of item to be removed. Must be a string.

Returns

Promise<void>

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This method is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This method isn't supported in Outlook on Mac or on the web.

removeItems(keys)

Removes multiple items from storage. Returns a Promise.

removeItems(keys: string[]): Promise<void>;

Parameters

keys

string[]

Keys of items to be removed. Must be an array of strings.

Returns

Promise<void>

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This method is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This method isn't supported in Outlook on Mac or on the web.

setItem(key, value)

Sets a key-value pair into storage or updates an existing key-value pair. Returns a Promise.

setItem(key: string, value: string): Promise<void>;

Parameters

key

string

Key of item to be set. Must be a string.

value

string

Must be a string.

Returns

Promise<void>

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This method is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This method isn't supported in Outlook on Mac or on the web.

setItems(keyValues)

Sets multiple items into storage or updates multiple items within storage. Returns a Promise.

setItems(keyValues: { [key: string]: string }): Promise<void>;

Parameters

keyValues

{ [key: string]: string }

Key-value pairs to be set. Must be strings.

Returns

Promise<void>

Remarks

[ API set: SharedRuntime 1.1, Mailbox 1.10 ]

This method is available in the SharedRuntime 1.1 requirement set for Excel, PowerPoint, and Word add-ins. It's also available starting in Mailbox requirement set 1.10 for Outlook.

Important: In Outlook, support is only available with the event-based activation feature implemented in Outlook on Windows. This method isn't supported in Outlook on Mac or on the web.