Let’s say you’ve decided to make some custom functionality available to your users as a SharePoint 2013 app. You’ve decided that this will be published to the appropriate internal SharePoint App Catalog (as opposed to being available in the public SharePoint Store). In a large company, it’s probably not realistic to expect all users to install such internal apps, even if we want to make the functionality available to everyone.
The answer *might* be to use one of the options for deploying the app at “tenant scope”. This works for both on-premises deployments and Office 365/SharePoint Online. This article looks at these options, but just as a reminder of where we are in the overall series, here's the table of contents:
- SharePoint 2013 apps – architecture, capability and UX considerations
- Getting started – creating lists, content types, fields etc. within a SharePoint app (provisioning)
- Working with data in the app web, and why you should
- Access end-user data (in the host web) from a SharePoint 2013 app
- Rolling out SharePoint 2013 apps to the enterprise - tenant scope and PowerShell installs [this article]
- Azure is the new SharePoint ‘_layouts’ directory
- “Host web apps” – provisioning files (e.g. master pages) to the host web
- “Host web apps” – provisioning fields and content types
- Deploying SP2013 provider-hosted apps/Remote Event Receivers to Azure Websites (for Office 365 apps)
- Working with web parts within a SharePoint app
- Deployment to named site collections
- Deployment to all sites under a particular managed path
- Deployment to all sites created from a certain site template
I said *might*. When deploying apps in this way, there is a crucial detail to be aware of – something which could either be highly-desirable or a deal-breaker. Essentially, all installed instances of the app *share* a single app web. This means any lists or libraries you provision as part of your app, are shared amongst all the webs where the app is installed. As I say, this could be exactly how you want your app to operate, or completely against it’s design.
The process for using this model is as follows:
- Upload app to App Catalog.
- Install the app to the App Catalog site collection – yes, for this scenario we actually have to install the app there (for reasons which will become clear later).
- Go to the Site Contents page and find the app. On the callout menu here (and only here), you’ll have an action labelled ‘DEPLOYMENT’:
- Click the ‘DEPLOYMENT’ button to go to the admin page.
On this page, I see the 3 options for deployment – individual site collections:
..or deploying to all sites under a Managed Path, or all sites created from a certain template:
Once you’ve selected appropriate options and hit OK, after a few minutes time you’ll find your app has landed in the target locations:
Important aspects of tenant-scoped app installations
As I highlighted before, all app instances share a single app web. The way this works is that the instance which is installed to the App Catalog site is used for all instances – effectively the user is always redirected to this URL on the app domain, regardless of which site they entered the app from:
There are also important by-products of this:
- Users in sites where the app is installed cannot remove the app – regardless of their permissions there
- This makes sense because they would effectively be uninstalling the single instance used by everyone
- Individual “usages” of the app do not get reported by Get-SPAppInstance – only the instance in the App Catalog site gets returned (N.B. applicable to on-premises SP2013 only)
Any changes to the app (e.g. app upgrades, app removal) need to be managed at the instance which is installed to the App Catalog site.
But I want something else - to roll out my app in bulk, but it NOT to be “single instance”
Then in this case, PowerShell is your friend – this is a two step process to install a new app:
- Use Import-SPAppPackage to initially install the app to the site collection, then..
- Use Install-SPApp to install to individual webs
For a full list of cmdlets around SharePoint 2013 apps, see App Management Service cmdlets in SharePoint 2013 on TechNet. Corey Roth also has a post on some of these cmdlets.
If you’re on Office 365 (with it’s limited set of PowerShell cmdlets, as of April 2013), you’ll need to accomplish the same thing using one of the client APIs. I’m starting to form the view that .NET CSOM code “wrapped” with PowerShell is a good way to do this – since it can then be integrated with TFS automated builds etc.
Happy app installing!
12 comments:
I've understood that this "batch installation" also has limitations as to what kinds of artifacts the app is allowed to install (see http://msdn.microsoft.com/en-us/library/fp179896.aspx), e.g. app parts and custom actions can not be provisioned to host webs.
Also, we've had some issues with app permissions when using the Install-SPApp cmdlet. Namely, the app needs to be trusted manually at the host web in order to make it work. Have you experienced similar issues?
@Jarno,
Agree on both of those points. On the first, I'd like to think that a future update *may* change this - I can't really think of any technical reason why it has to be that way.
On the second however, obviously Install-SPApp is effectively skipping that step of the app installer agreeing to the app's Permission Requests. It still needs to happen at some point. It's an interesting question as to whether this can also be accomplished with PowerShell - I haven't yet looked.
Obviously all this doesn't apply to tenant-scope apps, because the person who installed it to the App Catalog site agreed to the Permission Requests at that time.
Cheers,
Chris.
Hi Chris,
I have installed my custom app, which is a On-Prom Provider-Hosted app, in my On-Prom app catalog, but I can't deploy my app in the desirable site collections and receive an error saying "The entered site collection is invalid."!!
Have you experienced this issue before? Do have any suggestions?
Cheers,
Parr
@Parham,
This happens when you're trying to specify a site collection which is NOT associated to the App Catalog you're working with. Remember that App Catalogs are associated at the web application level.
Effectively you're going "across the boundary", and will need to either change the App Catalog or site collection being specified.
HTH,
Chris.
Hi,
I ran into the same issue about the manual trust like Jarno. Is there a way to set an app trustable by powershell?
Hey Chris,
"If you’re on Office 365 (with it’s limited set of PowerShell cmdlets, as of April 2013), you’ll need to accomplish the same thing using one of the client APIs. I’m starting to form the view that .NET CSOM code “wrapped” with PowerShell is a good way to do this – since it can then be integrated with TFS automated builds etc."
How would you do this in office365?
@Anonymous,
Effectively your PowerShell is calling one of the client APIs rather than the server API. You'll need the client API bits on the box which runs the PowerShell.
Here's an example by Anders Rask which is used to import SP2013 search configuration (managed properties etc.) - http://andersrask.sharepointspace.com/Lists/Posts/Post.aspx?ID=42
HTH,
Chris.
I have not found any way to trust the app via built in SharePoint PowerShell cmdlets.. BUT, I wrote a 'workaround' to trust it that works good enough for me. Basically I am using the PowerShell Internet Explorer automation to do it.
Here is my sample code, you'll need to modify a few things etc to get it work, but hopefully is a good starting point. I am using this as part of my TFS Build process that builds the app, installs the app, and now trusts it automatically. I used https://officesharepointci.codeplex.com/ for this and then modified it to add this:
Write-Host "Trying to trust the app..."
$authorizeURL = "$($web.Url.TrimEnd('/'))/_layouts/15/appinv.aspx?AppInstanceId={$($appInstance.Id)}"
Write-Host "Loading url:" $authorizeURL
$oIE = New-Object -com internetexplorer.application
try
{
$oIE.visible=$true
$oIE.navigate2($authorizeURL)
sleep -Seconds 1
while ($oIE.busy) {
sleep -milliseconds 50
}
Write-Host "Loaded Page:" $oIE.Document.Title
sleep -seconds 5
$button = $oIE.Document.getElementById("ctl00_PlaceHolderMain_BtnAllow")
if ($button -eq $null)
{
Write-Host "Could not find button to press"
Write-Host $oIE.Document.documentElement.outerText
}
else
{
Write-Host "Found [Trust It] button, clicking..."
}
$button.click() #click the button, even if it errors (this will give TFS Build a Red error to show)
sleep -Seconds 1
while ($oIE.busy) {
sleep -milliseconds 50
}
Write-Host "Now we're on page:" $oIE.Document.Title " - " $oIE.LocationURL
#if the button press was successful, we should now be on the Site Settings page..
if ($oIE.Document.title -like "*trust*")
{
Write-Host "Error: " $oIE.Document.body.getElementsByClassName("ms-error").item().InnerText
throw ("Error Trusting App:" + $oIE.Document.body.getElementsByClassName("ms-error").item().InnerText)
}
else
{
Write-Host "App was trusted successfully!"
}
}
finally
{
$oIE.Quit()
}
@David,
NICE work! Good thinking to use IE automation, especially as part of a build process.
Thanks for sharing!
Chris.
@David,
The solution worked perfectly. Using the IE screen didn't even occur to me!
There's also a way to automate app part installations. Normally you can't export an app part, and I suspect they set the export mode to "Do not allow" because the .webpart file contains a GUID that refers to the host web (which is obviously always different).
What you can do is export the app part (just allow exporting it first from the web part's settings). If you open the .webpart file, you'll notice there's a property element with name 'ProductWebId' in the file. This contains the GUID to the host web that the original app part was exported from, and this needs to be replaced run-time when importing the .webpart file.
So, just read the .webpart file into memory, and before adding that file to the web, modify the ProductWebId element's value to reflect the ID of the new host web. Then you can add it programmatically like any other exported web part.
I'm pretty sure you can add the ClientWebPart completely programmatically too, but I haven't tried that yet.
But thanks again David, with the following steps, I can automate app and app part installations now:
1) Upload the app to app catalog
2) Install the app to a web (using your approach)
3) Install exported app parts to a page by changing the ProductWebId guid
Jarno
@Jarno,
Also cool. So are you doing this with CSOM or some other remote code?
Thanks,
Chris.
Thank you Chris and all the commentators.. This post has been posted a while a go and just wanted to see if there was any updates on how installing an app via powershell and trusting there is well. The last solution was an IE script. Anybody?
Also it looks like the batch installation for apps that have custom ribbon actions are still not supported :( so we're looking at doing a batch powershell script to do the installs.
Post a Comment