| title | description | ms.date | ms.subservice | ms.assetid | ms.localizationpriority |
|---|---|---|---|---|---|
Application Lifecycle Management (ALM) APIs | ALM APIs provide simple APIs to manage deployment of your SharePoint Framework solutions and add-ins across your tenant. | 06/28/2022 | migration-tool | fdf7ecb2-8851-425b-b058-3285fba77b68 | high |
ALM APIs provide simple APIs to manage deployment of your SharePoint Framework solutions and add-ins across your tenant. ALM APIs support the following capabilities:
- Add SharePoint Framework solution or SharePoint Add-in to tenant or site collection app catalog.
- Remove SharePoint Framework solution or SharePoint Add-in from tenant or site collection app catalog.
- Enable SharePoint Framework solution or SharePoint Add-in to be available for installation in tenant or site collection app catalog.
- Disable SharePoint Framework solution or SharePoint Add-in not to be available for installation in tenant or site collection app catalog.
- Install SharePoint Framework solution or SharePoint Add-in from tenant or site collection app catalog to a site.
- Upgrade SharePoint Framework solution or SharePoint Add-in to a site, which has a newer version available in the tenant or site collection app catalog.
- Uninstall SharePoint Framework solution or SharePoint Add-in from the site.
- List all and get details about SharePoint Framework solutions or SharePoint Add-ins in the tenant or site collection app catalog.
ALM APIs can be used to perform exactly the same operations that are available from a UI perspective. When these APIs are used, all typical actions are performed. Following are some of the characteristics of ALM APIs:
InstallandUnInstallevents are being fired for provider-hosted add-ins when corresponding operations occur.- ALM APIs support app-only-based operations for SharePoint Framework solutions only.
ALM APIs are supported for the tenant-scoped site collections and site collection app catalog. Use the corresponding app catalog's URL to target a specific app catalog. You must first enabled a site collection app catalog before targeting it with the actions documented on this page.
Important
Tenant-scoped permissions which require tenant administrative permissions are not supported with the ALM APIs.
ALM APIs are natively provided by using REST APIs, but there are additional client-side object model (CSOM) extensions, PowerShell cmdlets, and the cross-platform CLI for Microsoft 365 available through SharePoint PnP Community channels.
The ALM APIs are natively provided as endpoints on the SharePoint REST API.
The app catalog must be included in all HTTP requests when using the REST API as shown in the examples below. Replace the {app-catalog-scope} placeholder in the endpoint with the scope of the app catalog. The available scope options are tenantappcatalog and sitecollectionappcatalog.
For example:
| Scope | Endpoint |
|---|---|
| tenant | https://contoso.sharepoint.com/sites/AppCatalog/_api/web/tenantappcatalog/{command} |
| site collection | https://contoso.sharepoint.com/sites/Marketing/_api/web/sitecollectionappcatalog/{command} |
- when targeting the tenant app catalog located at
https://contoso.sharepoint.com/sites/AppCatalog, the endpoint would be **
Learn more here: SharePoint REST API
The PnP CSOM implements the ALM APIs by calling the SharePoint REST API.
Before using any of the ALM APIs in PnP CSOM, you need to obtain an authenticated client context using the Microsoft.SharePointOnline.CSOM. Then use the authenticated client context to get an instance of the PnP CSOM's AppManager object to call the ALM commands:
usingMicrosoft.SharePoint.Client;usingOfficeDevPnP.Core.ALM;// ...using(varcontext=newClientContext(webURL)){context.Credentials=newSharePointOnlineCredentials(username,securePassword);varappManager=newAppManager(context);// execute PnP CSOM ALM command}In all PnP Core methods, it's assumed the request targets the tenant app catalog in the tenant you connect to using the SharePoint CSOM ClientContext object. you can override the scope of all commands with an optional scope argument, for example
appManager.Install('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx',AppCatalogScope.Site);Learn more here: PnP PowerShell
PnP PowerShell implements the ALM APIs by calling the PnP CSOM.
Before using any of the cmdlets in the PnP PowerShell module, you must first connect to SharePoint Online using the Connect-PnPOnline cmdlet.
In all PnP PowerShell cmdlets, it's assumed the request targets the tenant app catalog in the tenant you connect to using the Connect-PnPOnline cmdlet. You can override the scope of the command using the -Scope parameter to target a site collection app catalog.
Learn more here: PnP PowerShell
[!INCLUDE pnp-powershell]
The CLI for Microsoft 365 is a cross-platform command-line interface that can be used on any platform, including Windows, macOS, and Linux. The CLI implements the ALM APIs by calling the SharePoint REST API.
Before using any of the commands in the CLI for Microsoft 365, you must first connect your Microsoft 365 tenant using the m365 login command.
Learn more here: CLI for Microsoft 365
[!INCLUDE pnp-o365cli]
First add an app package (*.sppkg or *.app) to an app catalog in order to make it available to SharePoint sites.
POST /_api/web/{scope}appcatalog/Add(overwrite=true, url='sharepoint-solution-package.sppkg')| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
| Content-Type | application/json |
| X-RequestDigest | {form digest} |
| binaryStringRequestBody | true |
Byte array of the file
// read filevarfilePath="c:\path\to\file\sharepoint-solution-package.sppkg";// get an instance of the PnP CSOM's AppManager as shown abovevarresult=appManager.Add(filePath);Add-PnPApp-Path ./sharepoint-solution-package.sppkgRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app add --filePath ./sharepoint-solution-package.sppkgRefer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
Deployment of the solution makes it available to install in sites.
POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Deploy| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
| Content-Type | application/json;odata=nometadata;charset=utf-8 |
| X-RequestDigest | {form digest} |
{ "skipFeatureDeployment": true }Note
This operation can only be completed after calling the Add endpoint and before you can install packages to specific sites.
Important
Deploying multiple packages in parallel is not supported. Make sure to serialize your deployment operations to avoid deployment errors.
appManager.Deploy('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')Publish-PnPApp-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app deploy --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
This is the inverse of the deploy step above. Once retracted, the solution can't be installed in sites.
POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Retract| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
| X-RequestDigest | {form digest} |
Note
This operation will block installing the solution in sites and disable existing installations.
// get an app packageappManager.Retract('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')Unpublish-PnPApp-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app retract --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
This is the inverse of the add step above. One removed from the app catalog, the solution can't be deployed.
POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/RemoveappManager.Remove('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')Remove-PnPApp-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app remove --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
Note
If the Retract operation is not performed before the Remove operation, the solution is automatically retracted.
This operation will return a list of all available SharePoint Framework solutions or add-ins in the app catalog.
GET /_api/web/{scope}appcatalog/AvailableApps| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
{ "value": [ { "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "ContainsTenantWideExtension": false, "CurrentVersionDeployed": true, "Deployed": true, "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "IsClientSideSolution": true, "IsEnabled": true, "IsPackageDefaultSkipFeatureDeployment": false, "IsValidAppPackage": true, "ShortDescription": "", "SkipDeploymentFeature": false, "Title": "sharepoint-solution-package" }, { "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "ContainsTenantWideExtension": false, "CurrentVersionDeployed": true, "Deployed": true, "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "IsClientSideSolution": true, "IsEnabled": true, "IsPackageDefaultSkipFeatureDeployment": false, "IsValidAppPackage": true, "ShortDescription": "", "SkipDeploymentFeature": false, "Title": "sharepoint-solution-package2" } ] }varallAppPackages=appManager.GetAvailable();Get-PnPAppRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app listRefer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
This action will return details about a specific SharePoint Framework solution or add-in available in the app catalog.
GET /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
{ "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "ContainsTenantWideExtension": false, "CurrentVersionDeployed": true, "Deployed": true, "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "IsClientSideSolution": true, "IsEnabled": true, "IsPackageDefaultSkipFeatureDeployment": false, "IsValidAppPackage": true, "ShortDescription": "", "SkipDeploymentFeature": false, "Title": "sharepoint-solution-package" }varappPackage=appManager.GetAvailable('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx');Get-PnPApp-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app get --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
Install a solution package with a specific identifier from the app catalog to the site based on URL context.
POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Install| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
| X-RequestDigest | {form digest} |
// get an app packageappManager.Install('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')Install-PnPApp-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app install --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>Refer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
Upgrade a solution package from the site to a newer version available in the app catalog.
POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Upgrade| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
| X-RequestDigest | {form digest} |
// get an app packagevarappPackage=appManager.GetAvailable('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx');if(appPackage.CanUpgrade){appManager.Upgrade(appPackage)}Update-PnPApp-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app upgrade --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>Refer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
This action is the inverse of the install command above.
Note
When you use the uninstall a solution package from the site with any of the methods below, it's permanently deleted; it'sn't placed in the recycle bin.
POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Uninstall| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
| X-RequestDigest | {form digest} |
appManager.Uninstall('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')Uninstall-PnPApp-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
m365 spo app uninstall --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>Refer to the CLI for Microsoft 365 documentation for complete details and examples on this command.
This action requires that you refer the list item ID of the solution in the app catalog site.
POST /_api/web/{scope}appcatalog/SyncSolutionToTeams(id=xxxxx)| Header | Value |
|---|---|
| Authorization | Bearer {token} |
| Accept | application/json;odata=nometadata |
| X-RequestDigest | {form digest} |
appManager.SyncToTeams('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')Sync-PnPAppToTeams-Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxRefer to the PnP PowerShell documentation for complete details and examples on this cmdlet.
Not Supported
