OfficeRuntime.Storage interface

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

Returns

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.

Examples

// Retrieve a value from the shared runtime storage by its key.
async function getItem() {
    const key = document.getElementById('readKey').value.trim();

    const value = await OfficeRuntime.storage.getItem(key);

    if (value === null) {
        console.log(`Item not found - Key "${key}" not found in storage.`);
    } else {
        console.log(`Item retrieved successfully - Key: "${key}"\nValue: "${value}"`);
    }
}

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

Returns

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.

Examples

// Retrieve a set of default values from the shared runtime storage.
async function getDefaultSettings() {
  const keysToRetrieve = [
      'username',
      'email',
      'theme',
      'lastLogin',
      'preferences'
  ];

  const items = await OfficeRuntime.storage.getItems(keysToRetrieve);
  for (const [key, value] of Object.entries(items)) {
      console.log(`"${key}": "${value}"`);
  }
}

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

getKeys(): Promise<string[]>;

Returns

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.

Examples

// Retrieve all keys currently stored in the shared runtime storage.
async function getAllKeys() {
  const keys = await OfficeRuntime.storage.getKeys();

  if (keys.length === 0) {
    console.log('No items in storage.');
    showStatus('Storage is empty', 'info');
  } else {
    console.log(`Found ${keys.length} key(s):\n\n${keys.toString()}`);
  }
}

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

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

Parameters

Returns

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.

Examples

// Delete an item from the shared runtime storage by its key.
async function removeItem() {
    const key = document.getElementById('deleteKey').value.trim();
        
    // Check if key exists first.
    const value = await OfficeRuntime.storage.getItem(key);

    if (value === null) {
        console.log(`Key "${key}" not found`);
    } else {
      await OfficeRuntime.storage.removeItem(key);
      console.log(`Item "${key}" removed successfully`);
    }
}

Removes multiple items from storage. Returns a Promise.

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

Parameters

Returns

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.

Examples

// Delete all the items from the shared runtime storage.
async function clearAllStorage() {
  const keys = await OfficeRuntime.storage.getKeys();
  await OfficeRuntime.storage.removeItems(keys);
  console.log(`All ${keys.length} items cleared from storage`);
}

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

Returns

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.

Examples

// Save a key-value pair in the shared runtime storage.
async function storeValue() {
  const key = document.getElementById('createKey').value.trim();
  const value = document.getElementById('createValue').value.trim();

  await OfficeRuntime.storage.setItem(key, value);
}

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

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

Parameters

Returns

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.

Examples

// Save multiple key-value pairs in the shared runtime storage.
async function setDefaultSettings() {
  const demoData = {
      'username': 'JohnDoe',
      'email': 'john.doe@example.com',
      'theme': 'dark',
      'lastLogin': new Date().toISOString(),
      'preferences': JSON.stringify({ notifications: true, language: 'en' })
  };

  await OfficeRuntime.storage.setItems(demoData);
}