Share via

extensionAlternateVersionsArray object

The extensions.alternates property is used to hide or prioritize specific in-market add-ins when you've published multiple add-ins with overlapping functionality.

Properties that reference this object type:

Syntax

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "prefer": {
    "comAddin": {
      comAddin object
    }
  },
  "hide": {
    "storeOfficeAddin": {
      storeOfficeAddin object
    },
    "customOfficeAddin": {
      customOfficeAddin object
    }
  },
  "alternateIcons": {
    "icon": {
      extensionCommonIcon object
    },
    "highResolutionIcon": {
      extensionCommonIcon object
    }
  },
  "xllCustomFunctions": {
    "fileName": "{string}"
  }
}

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "prefer": {
    "comAddin": {
      comAddin object
    }
  },
  "hide": {
    "storeOfficeAddin": {
      storeOfficeAddin object
    },
    "customOfficeAddin": {
      customOfficeAddin object
    }
  },
  "alternateIcons": {
    "icon": {
      extensionCommonIcon object
    },
    "highResolutionIcon": {
      extensionCommonIcon object
    }
  }
}

Properties

requirements

Specifies the scopes, formFactors, and Office JavaScript library requirement sets that must be supported on the Office client in order for the hide, prefer, or alternateIcons properties to take effect. For more information, see Specify Office Add-in requirements in the unified manifest for Microsoft 365.

Type
requirementsExtensionElement

Required
—

Constraints

Supported values

prefer

Specifies the backward compatibility with an equivalent COM add-in, XLL add-in, or both.

Type
prefer

Required
—

Constraints

Supported values

hide

Configures how to hide another add-in that you've published whenever the add-in is installed, so users don't see both in the Microsoft 365 UI. For example, use this property when you've previously published an add-in that uses the old XML app manifest and you're replacing it with a version that uses the new JSON app manifest.

Type
hide

Required
—

Constraints

Supported values

alternateIcons

Specifies the main icons that are used to represent the add-in on older versions of Office. This property is required if the Office add-in is to be installable in Office on Mac, perpetual Office licenses, and Microsoft 365 subscription versions of Office on Windows earlier than 2304 (Build 16320.00000).

Type
alternateIcons

Required
✅

Constraints

Supported values

alternateIcons

Specifies the main icons that are used to represent the add-in on older versions of Office. This property is required if the Office add-in is to be installable in Office on Mac, perpetual Office licenses, and Microsoft 365 subscription versions of Office on Windows earlier than 2304 (Build 16320.00000).

Type
alternateIcons

Required
—

Constraints

Supported values

xllCustomFunctions

Represents an XLL-based add-ins custom function.

Type
extensionXllCustomFunctions

Required
—

Constraints

Supported values

Examples

{
  "alternates": [
    {
      "requirements": {
        "scopes": [ "mail" ]
      },
      "prefer": {
        "comAddin": {
          "progId": "ContosoExtension"
        }
      },
      "hide": {
        "storeOfficeAddin": {
          "officeAddinId": "00000000-0000-0000-0000-000000000000",
          "assetId": "WA000000000"
        }
      },
      "alternateIcons": {
        "icon": {
          "size": 64,
          "url": "https://contoso.com/assets/icon64x64.jpg"
        },
        "highResolutionIcon": {
          "size": 64,
          "url": "https://contoso.com/assets/icon128x128.jpg"
        }
      }
    }
  ]
}