Alexander Vanwynsberghe

"There is nothing impossible to him who will try"

Debugging SharePoint 2013 remote events using the Windows Azure Service Bus

In this post, I will talk about how you can debug remote events within a SharePoint 2013 App. Especially with the Autohosted App Model (I made a post about that a while ago). Let me first start with a small and really easy to understand app that I will use to highlight the topic of this post.

The App

It’s quite an easy app where you can:

  • Add a contact
  • Get a contact

The App has some logic in the Web project (to manage the button “Add Contact” and “Get Contacts“), and a “List” in the SharePoint project. You will find the sources at the bottom of this post. When running this App, you will see something like:

03

As you can see, the “FullName” contains the text “Not set!“. That’s correct, I only provided my first and last name. But I want my full name to be “managed” by a remote service. And that’s where this post is all about. Finally! What I want is a remote event receiver that will be triggered when a new contact has been added. Add one to the SharePoint project. Right-Click and select “Add – New – Remote Event Receiver”. Call it “Contact List“. You need to select the type of event on which the event receiver needs to do something. Select “An item was added“.

02

You will now see a new folder in the Web Project called “Services“‘ and a new service called “ContactList.svc“. When you open it, you should see 2 methods. The one we need is called “ProcessOneWayEvent“. You can add the following code:

What it actually will do is get the ClientContext and get my first and last name that I submitted. It will than perform a string merge and add it to the “FullName” of the ListItem. Nothing fancy. So, why don’t we just hit F5 and check it out? You will soon find out that it will not work, the service is not being called. You can try to add a breakpoint, and you will see that it will be ignored. But why?

Problem

The problem is quite easy to understand. What will happen when you press F5 is a “Publish” of your App to SharePoint online, and once you “Trust” the App will eventually loop back to your “Local IIS”  (as you can see in the URL of the screenshot at the beginning of this post). It looks like:

problem1

So our Web project is running locally, meaning that our web service is also running locally. So in our case, when we hit the button “Add Contact“, it will try to call our Remote Event Receiver. So from a  SPAppWeb (which is SharePoint Online) context, it will not be able to contact “Localhost“. It looks like:

problem2

Solution: Windows Azure Service Bus

In the final “RTM” version of Office Developer Tools for Visual Studio 2012 there is cool feature called “Enable Remote Event Debugging“, making use of the Windows Azure Service Bus. Now first of all, what’s that Azure Service bus? Let me take the description from MSDN:

The Windows Azure Service Bus provides a hosted, secure, and widely available infrastructure for widespread communication, large-scale event distribution, naming, and service publishing. The Service Bus provides connectivity options for Windows Communication Foundation (WCF) and other service endpoints – including REST endpoints — that would otherwise be difficult or impossible to reach. Endpoints can be located behind network address translation (NAT) boundaries, or bound to frequently-changing, dynamically-assigned IP addresses, or both.

In other words, the Windows Azure Service Bus allows you to expose our local WCF service to the “outside world”. And that’s exactly what we need! All you have to do is get yourself a Service Bus instance and enable this feature in the SharePoint App project properties. You can get a Windows Azure Service Bus  instance using the Windows Azure Management Portal. On the left side, click on “Service Bus” and click on the “Add” sign on the bottom of the page. Add a name, and finish the wizard.

06When your service has been created, all you have to do is click on the “Access Key” button and copy the connection string. Next, right-click on your SharePoint App project in Visual Studio and select “SharePoint“. There you can “Enable Remote Event Debugging“:

08

Now you can add a breakpoint in your service code and press F5. There you go:

09And if you look at the App itself, you will see that the “FullName” has a value:

10

Mission accomplished! You can download the sources here. Have fun! Oh, and just a small note, did you know that you can actually see which services are available/active on you Windows Azure Service Bus? Just browse to the URL of your service bus, and you should see:

04

Deploying SharePoint 2013 Apps with TFS 2012

In this third part about SharePoint 2013 Apps with TFS 2012, I will talk about how you can deploy your package to your SharePoint 2013 (or SharePoint Online) instance. (Note that I’m using the “AutoHosted” App model) First you have to complete the steps described in my previous posts:

Assuming that this was no problem, you should have a build definition based on the “OfficeToolsAppTemplate” build process template (which you can download here). This should result in a build definition who will give you the following output:

completedbuildThat’s great. Now we want to deploy this App to our SharePoint instance. Good news, the build process template has everything available to achieve this. Once  you have downloaded this build process template, you also have a folder called “DeployScripts“. Add this folder (and the content of it) to Source Control like. That’s it for now.

deploy01

SharePoint requirements

Before we can deploy this App package, you need to have a “developer site“. Normally will already have this, because if you deploy your App directly from Visual Studio, you will also need this. You will have a site collection like:

deploy02

A thing I can advise you is using a “custom” deployment account. There reason for that is that this account is required to be “defined” in a PowerShell script (including that password). As  you can see in the previous screenshot, I have a user called “deploy” who is also an administrator of this development Site Collection.

On-prem Build Server requirements

On the Build Server, we will also need to verify some things. First of all, if you want to deploy to “SharePoint Online,” you need to have the SharePoint Online Management Shell installed. This will allow the deployment scripts to connect to your SharePoint online instance. You can easily test it using the “Connect-SPOService” command:

deploy03

Next thing that  you need to check is the account your TFS Build Service is using. If you installed the TFS Build Server using the “next-next-wizard”, your TFS Build Service account will be using “NT AUTHORITY\LocalService“. If you keep this by default, and you try to deploy your App, you will see the following error (been there!)

deploy04

You need to change this account to a known user account so the deployment script can import the SharePoint module. In my case, I’m using a standard Windows Server 2012 Azure VM, and I simply use the ‘Administrator” account.

deploy05

Configuring the deployment

Almost there. If you look into the folder “DeployScripts”, you will find a PowerShell file called “Parameters.ps1“. In this file, you need to supply your credentials (like my “Deploy” user) and the site URL where you want your application to be deployed. If you’re deploying to SharePoint online, you do not need enter the “$SpDeployUserDomain“, just enter the portal.microsoftonline.com login (user@account.onmicrosoft.com). Save the changes, and check-in to Source Control.

Now we have to change the Build Definition so that it will execute a PowerShell Deployment script. Edit your Build Definition, and select the “Process” section. On the bottom section, there is a field where you can provide the deployment script. In our case, this is something like “$../DeployScripts/SharePointApp/SharePointAppDeploy.ps1

deploy06

There you are. Save this Build Definition, and queue a new build. After a wile, you should see a nice green build, meaning that your App is deployed!

deploy07If you go to your developer site, you will see your App listed. Just click on it, and you will see this nice error:

deploy08

Bummer! But no worries, that’s normal. Maybe you know, but if you deploy directly from within Visual Studio, you will be redirected to a page asking you “Do you trust this app?“. In the case of a Build Server deployment, there is no such a question, resulting in the error from above (note: by default, you will not see a detailed error, but I added “<customErrors mode=”Off” /> to my Web.Config”). To solve this error, you need to click on the “…” of your listed App, and select “Manage Permissions“.

deploy09

If you now trust your App, you can enjoy playing with it! So if you change the Build Definition to “Continuous Integration”, you will have a “Continuous Deployment” system up and running! Have fun

Adding a custom domain to Office365 using WAAD

I’m playing with my Office 365 Plan E3 Technical Preview subscription for a quite a while now, and I think it’s just great! In this post, I want to guide you through the process of adding a custom domain to your subscription. The way I will show it is by using the Windows Azure Active Directory portal, which I will explain right away.

WAAD

Did you know that when subscribe to an Office 365 Plan, Microsoft automatically creates a new Windows Azure Active Directory (WAAD) that is associated with your Office 365 account? Well, at first, I didn’t! This is really great! For the people that do not know WAAD, let me quote:

Windows Azure Active Directory (Windows Azure AD) is a modern, REST-based service that provides identity management and access control capabilities for your cloud applications. Windows Azure Active Directory provides a cloud-based identity provider that easily integrates with your on-premises AD deployments and full support of third party identity providers.

When you login at https://activedirectory.windowsazure.com using your Office 365 administration credentials, you see that it’s linked to your subscription like:

01

Activate your custom domain

Alright, that being said, let’s move on and add a custom domain to our subscription. By default, your subscription domain will be something like yourname.onmicrosoft.com. That’s great, but using your personal domain is a much more professional way of working of course.  Let’s do that now.

First, click on the ‘domains’ link on the left side. You will see that the  *.onmicrosoft.com is already listed there by default. Click on the ‘Add a domain’ button.

02

In general, the process consists out of 2 mayor steps. First you need to ‘activate’ your domain, meaning that you need to prove that you actually own it. Secondly, you need to ‘manage your DNS settings’ to manage the correct usage of the Office 365 settings. The first wizard you see is the ‘activation’ part. Enter your domain and click ‘next

03

Now you need to verify that you are the owner of the domain. Out of the box, there are some pre-defined domain registrars listed. My domain is registered somewhere in the Netherlands, so no one of the listed option, so I selected ‘General Instructions

04

On the next screen, I used the TXT record option. On the DNS management page of my domain registrar, I added the TXT record like:

05

If you click ‘next’, the service will check the TXT record and you will be able you continue the process. In my case, it only took a few seconds for the TXT record to be applied. In other cases, it can take bit longer. The next step is to select the domain services. In other words, which services will be used with your domain? I selected ‘Exchange’ and ‘Lync’.

Don’t select SharePoint, because the DNS record that you create to enable SharePoint Online for this domain by default restricts all other DNS records from working. What you can do is create a CNAME record with the WWW prefix, and point it to yourname.sharepoint.com. Or even better, yourname-public.sharepoint.com, so it will link to the public website. You can then create another CNAME record with the PORTAL prefix, and point it to the SharePoint sites root.

06

That’s it, your domain is ready to be used, meaning that it’s added to your WAAD account (and thus can be used with your Office 365 subscription).

07

Configure your custom domain

Now that our domain is active, we can start using it. Click on the ‘Finish’ button (or if you already closed the previous wizard, just click on your Domain and click ‘DNS Settings’.) You will see a nice overview of the DNS entries you need to make on the DNS settings page of your domain registrar. For example:

09

On the wizard screen, you don’t have the option to ‘validate’ if you entered the correct DNS entries, but there’s an option to validate. Just go back to the screen where you see your domain name listed, click on the domain and select the ‘Troubleshoot domain’ button. It will ask you when you changed the DNS entries. For this quick check, just select ‘more than 72 hours ago’ so it will check it right away. In my case, this was a green result for Exchange (I didn’t configure Lync):

12

That’s it. Now we can use our custom domain with our Office 365 subscription. Let’s take Exchange for example. To be able to send an email to ‘abc@mycustomdomain.com’, you will need to add the email (alias) to the list of email addresses of the person ‘abc@something.onmicrosoft.com’. Go to the Exchange admin center – Recipients and edit the mailbox you want. On this new popup, select the ‘email address’ section, and add an SMTP alias like:

11

That should do the trick, you can now send an email to ‘abc@mycustomdomain.com’, and it should arrive in the mailbox of the user you just configured.

Have fun!