Until the end of November 2017 it was very tricky to manage the application lifecycle for SharePoint solutions, since some of the possibilities available weren't supported by Microsoft. If you've worked with SharePoint web services to reach your goals, you know how vulnerable a system becomes to changes caused by Microsoft. But now… it is past!!!
In this blog post I'll present and explain you the new ALM APIs.
At the end of the day it is just about executing REST calls
- you don't need to take care of inconvenient things like passing the REQUESTDIGEST while executing the calls.
- you don't need to remember the REST APIs or build complex strings/code.
APIs' scope
The new APIs were designed to act in different scopes:
Site level operations: These APIs will execute requests against the site collection which you requested client context for.
App catalog operations: These APIs will execute requests against the app catalog. Independent from the generated client context.
APIs' overview
Site level operations:
Description | API |
---|---|
Get available apps | _api/web/tenantappcatalog/availableApps |
Get available app by id | _api/web/tenantappcatalog/availableApps/GetById("") |
Install available app | _api/web/tenantappcatalog/availableApps/GetById("")/Install |
Update available app | _api/web/tenantappcatalog/availableApps/GetById("")/Upgrade |
Uninstall available app | _api/web/tenantappcatalog/availableApps/GetById("")/Uninstall |
App catalog operations:
Description | API |
---|---|
Add app to app catalog | _api/web/tenantappcatalog/Add |
Deploy available app | _api/web/tenantappcatalog/availableApps/GetById("")/Deploy |
Retract available app | _api/web/tenantappcatalog/availableApps/GetById("")/Retract |
Remove available app | _api/web/tenantappcatalog/availableApps/GetById("")/Remove |
APIs for site level operations in test
Instead of directly working with REST calls, I'll demonstrate the new APIs using PnP PowerShell.
Get available apps:
Returns all apps which are available for your site collection.
Get-PnPApp | Format-Table
Get available app by id:
If the app is available, it returns the searched app.
Get-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811 | Format-Table
Install available app:
Installs an app to the current site collection. If the app requires admin permission to install, the API will automatically handle the approval process.
Install-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811
Install-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811
If a new app version is available, it updates the app on the current site collection.
Running the API below will update the app from the version 1.0.0.0 to the version 1.0.0.1.
Update-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811
After running the API, you can see in the site contents of your site collection that the app is getting updated.
Running the API below will update the app from the version 1.0.0.0 to the version 1.0.0.1.
Update-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811
After running the API, you can see in the site contents of your site collection that the app is getting updated.
Uninstall available app:
Uninstalls an app from the current site collection. It completely removes the app from the site collection, without moving it before to the recycle bin folder. So wonderful!!!
Uninstall-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811
Instead of directly working with REST calls, I'll demonstrate the new APIs using PnP PowerShell.
Uploads an app file to app catalog. Using the REST API you can work with binary data and pass the parameter override. At time of this written, the PnP method Add-PnPApp works with a file path and automatically set the override parameter to false. If the file already exists in the app catalog and the override parameter is set to false, you'll get an exception.
Add-PnPApp -Path C:\search-web-part\search-web-part.sppkg | Format-Table
Deploys and trusts an available app. It is possible to set the parameter SkipFeatureDeployment. Although the PnP method is called Publish, it does the right job J
Publish-PnPApp -Identity 38740267-e8a5-4179-9725-fc5155d19447
After running this API, the app is available in the "add an app" page for installation.
Uninstall-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811
APIs for app catalog operations in test
Instead of directly working with REST calls, I'll demonstrate the new APIs using PnP PowerShell.
Add app to app catalog:
Uploads an app file to app catalog. Using the REST API you can work with binary data and pass the parameter override. At time of this written, the PnP method Add-PnPApp works with a file path and automatically set the override parameter to false. If the file already exists in the app catalog and the override parameter is set to false, you'll get an exception.
Add-PnPApp -Path C:\search-web-part\search-web-part.sppkg | Format-Table
This API returns the app unique ID which is not the product ID. The unique app ID is
stored in the hidden field UniqueId
of the list Apps for SharePoint. The picture below shows the new uploaded app.
Notice that the file is still no deployed.
Deploy available app:
Deploys and trusts an available app. It is possible to set the parameter SkipFeatureDeployment. Although the PnP method is called Publish, it does the right job J
Publish-PnPApp -Identity 38740267-e8a5-4179-9725-fc5155d19447
After running this API, the app is available in the "add an app" page for installation.
Retract available app:
Retracts
the available app without removing it from the app catalog. Although the PnP
method is called Unpublish, it does the right job J
Unpublish-PnPApp -Identity 33aad64c-fe65-4f39-b873-5349632957fe
After running this API, the specified app is no longer available for installation.
Remove available app:
Removes an available app from the app catalog. Notice that installed apps will not be uninstalled, but as far as I know, client side web parts will no longer work.
Remove-PnPApp -Identity 33aad64c-fe65-4f39-b873-5349632957fe
Summary
We
finally have stable and supported APIs for managing the application lifecycle
of SharePoint solutions. Processes have become faster and are easier to
automate. Many thanks to everyone involved in developing these APIs.