Get started with Office 365/SharePoint Online dev – part 2: Developing SharePoint Add-ins (apps)

This is the second post around getting started with Office 365/SharePoint Online development. In these couple of articles, I discuss a process where developers new to this space can get started by using trial environments and an Azure virtual machine. The idea is that you don’t need an MSDN subscription, existing Office 365 environment or even a development machine to get running – in the last post, we created all those things. Now it’s time to use them. Specifically, we’ll get some add-in code running in the Azure VM, which talks back to SharePoint Online - we’ll do this by obtaining a sample app and configuring our dev environment to run it. In my opinion, this is a good way to learn about modern SharePoint development which uses “provider-hosted” remote code – which, of course, can be used on-premises or in the cloud. Before we get started, a reminder on the contents of these two articles:

1. Get started – part 1: Create trial environments and a VM
2. Get started – part 2: Developing SharePoint Add-ins/apps (this post)

Deploying a provider-hosted SharePoint Add-in in your VM

Here’s an overview of what we’ll cover here:

• Create a Developer Site in Office 365
• Complete some information in your user profile in SharePoint Online (since our lab demo will use it)
• Prepare the development environment to host apps locally:
  • Create a local IIS website to run apps
  • Create a self-signed SSL certificate and bind it to the site
• Register the SharePoint Add-in using AppRegNew.aspx
• Download the “app script part” SharePoint Add-in sample from from Github (from the Microsoft OfficeDev Patterns and Practices library), and run it locally in the VM
• Review how the solution is working

Here are the step to go through..

Create a developer site collection in Office 365

Navigate to the SharePoint admin area of Office 365, and go to the “Site Collections” page. Click “New” to create a new site collection:

Use settings like the below:

Once the site has created, check it can be accessed in the browser:

Enter some details into your user profile in Office 365/SharePoint Online

In any SharePoint page in your Office 365 tenant, click the user photo in the top right corner, and then click the “About me” link to go to the profile page:

Click the “Edit profile” link:

Enter some details into fields such as “About me” and “Ask Me About”. Also use the “Change your photo” link to change your photo:

Once done, click “Save all and close”.

Create a new site in IIS for app hosting

Open IIS Manager, and create a new website. Use the following settings:

Config item	Value
Name	spsites
Path	C:\inetpub\wwwroot\spsites (N.B. the “spsites” folder will need to be created)
Host name	spsites

The Add Website dialog should look like this:

Click “OK” to finish creating the IIS site.

Add the site to your hosts file:

Create a self-signed SSL certificate and apply it to the site

Open a PowerShell window as an administrator. Create a self-signed cert using the following command:

New-SelfSignedCertificate -DnsName spsites -CertStoreLocation cert:\LocalMachine\My

Now we need to install the certificate as a Trusted Root certificate in the store, and apply it to the “spsites” IIS website. The following steps are used:

1. Certificate is exported to a file.
2. Certificate is installed from the file on the filesystem to the “Trusted Root Certification Authorities” cert store.
3. Certificate is applied to the IIS website.

Go to “Server Certificates” in IIS, and find the certificate you just created. Follow the sequence in the steps below to export the certificate to a file:

The certificate should now be exported as spsite.cer.

Now find the file on the filesystem, and right-click > “Install Certificate”:

Follow the process in the images below to install the certificate to the Trusted Root cert store:

The final step around IIS and SSL certificates is to apply it to the site. Find the website in IIS, right-click on it and select “Edit bindings..”:

Add a new site binding on port 443 – select the “spsites” certificate:

Click “OK”, and the certificate should now be applied to the site. You should be able to browse it on https://spsites (although note you will get a default IIS page, since there is no site running there at this point).

Obtain the “app script part” sample from the Microsoft OfficeDev Patterns and Practices library

Navigate to https://github.com/OfficeDev/PnP - click the “Download zip” link:

Save the zip file to C:\Code on your virtual machine (create the folder since it won’t exist already), and then unzip:

Now run Visual Studio 2015 as an administrator. Note that it can take some time to open in an Azure virtual machine.

In Visual Studio, use “File > Open > Project/Solution…” to open the “App Script” sample from the zip in Visual Studio – this can be found at:

C:\Code\PnP-master\PnP-master\Samples\Core.AppScriptPart\Core.AppScriptPart.sln

Once the project has opened, enter the URL for your Office 365 developer site in the Site URL property of the main project in Visual Studio:

A dialog box should appear – enter the credentials for your Office 365 identity:

Visual Studio should now be signed-in to your developer site in Office 365.

Configure the web project to match your hosting environment

Go to the properties page for the “Core.AppScriptPartWeb” project, and go into the “Web” area. Change the settings to match the IIS site we created, and click the “Create Virtual Directory” button to allow the files to be hosted in their dev location:

Save the Visual Studio project.

Also edit the userprofileinformation.webpart file in the project – find the line which sets the URL of the JavaScript file being linked by the web part in the sample, and set it to https://spsites/Core.AppScriptPartWeb/scripts/userprofileinformation.js:

Create the registration for your Add-in in SharePoint Online

In a browser window to your developer site, navigate to the following URL:

[site]/_layouts/15/AppRegNew.aspx

..so in my case, this is:

https://chrisob1.sharepoint.com/sites/Dev/_layouts/15/AppRegNew.aspx

Click the “Generate” button to generate new values for both the Client ID and Client Secret fields, then complete the other information as below:

On the next screen, be sure to copy the Client ID and Secret somewhere safe – you’ll need these later:

Now return to Visual Studio and perform the following steps:

Open the web.config file in the web project, and update the ClientId and ClientSecret app settings values:

Open the AppManifest.xml file in the app project, and update the ClientId attribute:

Your add-in should now be configured to run in development – in the next step we will run the app to test it.

Run the add-in

Press F5 in Visual Studio to run the project. Enter the credentials for your Office 365 identity if prompted:

You should be prompted to trust the app:

Click “Trust It”, and you should then be taken to the default page for the add-in. Note that this page is not a key piece of the add-in – it simply uploads the web part in an automated way to make it available.

To do this, click the “Run scenario” button:

Now click the “Back to Site” link:

Edit the page, and add the web part deployed by the add-in to the page. Go to add a web part, and you’ll find it in the “Add-in Script Part” category:

Once the web part has been added to the page, it should show details from your user profile (including a photo if you have one – I don’t in this case!):

If you got this far, well done! Now let’s consider what we just got working.

Key takeaways

• We implemented a web part which is truly cloud-friendly – it has NO server-side code, because it is not a legacy web part.
• In fact, it’s just an out-of-the-box Script Editor web part – which points to a particular JavaScript file, which has the actual functionality implemented
• The JavaScript file has some CSOM code to fetch the user profile details
• The JavaScript file is actually hosted remotely from SharePoint. In the case of our development scenario, it was running in IIS – but we could publish it to Azure or similar for production use (remember we’d need a new app registration with the appropriate URL etc.)

The key bits of code are essentially some simple JSOM code to fetch user profile details and output to HTML:

So that’s an introduction to the world of remote code and cloud-friendly development in SharePoint. Hope someone found it useful!