Download the Code: CloudBusinessTasks.zip

When you deploy your SharePoint Provider-Hosted Cloud Business App, you can use an authentication key from the Microsoft Seller Dashboard to allow multiple SharePoint websites to consume the same website application. You can segment the data so that each SharePoint website only sees its own data using row level filtering.

Note: To complete this tutorial you must have Visual Studio 2013 with the Visual Studio 2013 Update 2 (or higher) installed.

The Life Of A Cloud Business Application

A SharePoint Cloud Business app (CBA) is deployed in a multiple parts.  First, there is the traditional web hosting provider (such as Azure websites) for the CBA to run on.  Next, the SharePoint specific parts and metadata (for example, the lists the app uses or any special SharePoint types it defines) are installed on the SharePoint site that the CBA is installed on (the application is installed using an .app file). 

The following are the steps performed when a user runs the CBA application in SharePoint:

• The user opens their web browser and navigates to the SharePoint site
• The user launches the CBA app by clicking a link on the SharePoint site
• SharePoint redirects browser to the 3rd party web server where the LightSwitch SharePoint enabled Cloud Business App (CBA) is located.  This redirect sends along special SharePoint OAuth authentication.
• The CBA app detects the SharePoint identity and talks back to SharePoint to make sure the user is who they claim to be
• The CBA can now impersonate the user whenever they communicate with SharePoint

Create The Sample Application

Open Visual Studio and select File, then New Project, and create a Cloud Business App.

Point it to your SharePoint developer site (or click the link to take you to the website that shows you where we can sign up for a SharePoint developer site).

After the Solution is created, right-click on the Data Sources folder in the Server project and select Add Table.

Create a table with the following structure:

Next, set the table to update the SharePoint Newsfeed…

Click on the table header so that you set scope to the entire table. In the table Properties, enable the Created and Updated post settings under Social.

Set the Summary Property to TaskName.

Enable Multi-Tenant Capability

We will enable multi-tenant capability in the application by programmatically recording the website that the user is coming from, in the HostURL property in the Task table, and setting a filter that will only show a user data from the website they are coming from.

While the table is still selected, select Write Code then Tasks_Inserting.

Use the following code for the method:

partial void Tasks_Inserting(Task entity)
{
    // Set the HostURL
    entity.HostURL = this.Application.SharePoint.HostUrl.Host;
}

Return to the table designer, select the table, and select Write Code then Tasks_Updating.

Use the following code for the method:

 partial void Tasks_Updating(Task entity)
{
    // Set the HostURL
    entity.HostURL = this.Application.SharePoint.HostUrl.Host;
}

Return to the table designer, select the table, and select Write Code then Tasks_Filter.

Use the following code for the method:

 partial void Tasks_Filter(ref Expression<Func<Task, bool>> filter)
{
    // Only allow users to see records from their own site
    filter = e => e.HostURL == this.Application.SharePoint.HostUrl.Host;
}

Note: For more information on how the filtering works, see the LightSwitch article on row level filtering.

The HostURL field is set as a required field. We need to provide a default value for it (even though the value will be overwritten in server-side code).

Select the HTMLClient tab  and then Write Code, and then created, to create client-side JavaScript code for the Task entity.

Use the following code for the created method:

myapp.Task.created = function (entity) {
    // Set a default value.
    // This will be overwritten
    // in the Inserting/Updating
    // methods.
    entity.HostURL = " ";
};

Create The Screens

Right-click on the Screen folder in the Client project and select Add Screen.

Select the Common Screen Set template.

The screens will be created.

Format The Screen

We don’t need the HostURL displayed on the edit screen.

Open the AddEditTask screen, by double-clicking on it in the Solution Explorer.

Right-click on the Host URL control to select it, and delete it.

Add A Delete Button

We can customize the application to add a Delete button.

Open the View Task screen, and click on the Command Bar to expand it.

Click the Add button and add a Delete button.

A Delete method will show in the View Model on the left-hand side of the screen.

Right-click on the Delete method and select Edit Execute Code.

Use the following code for the method:

myapp.ViewTask.Delete_execute = function (screen) {
    // Delete the Task
    screen.Task.deleteEntity();
    // Save changes
    myapp.commitChanges().then(null, function fail(e) {
        // There was an error - show it in a box
        msls.showMessageBox(e.message, {
            title: "Error",
            buttons: msls.MessageBoxButtons.ok
        }).then(function (result) {
            if (result === msls.MessageBoxResult.ok) {
                // Discard Changes
                screen.details.dataWorkspace.ApplicationData
                    .details.discardChanges();
            }
        });
    });
};

Test The Project

We will now Debug the application.

Note: While we will be directed to and logged into the SharePoint website, it will pass us back to our local development machine, and we will be running the application directly from our development machine.

Select Debug, then Start Debugging to Debug the project.

You will be prompted to log into your SharePoint development site.

You may also have to log into the web page of your SharePoint developer website.

You will have to Trust the application.

The application will load.

We can add Tasks by clicking the Add button.

We can enter task details, and save them by clicking the Save button.

Clicking on a Task shows the details and allows us to Edit or Delete the Task.

We can see that the Host URL is programmatically set.

We can also navigate to the Newsfeed…

The Task will show in the Newsfeed with an option to follow any changes or navigate directly to it.

Publish The Application

You will need to determine the location that you plan to publish your website application to.

Creating a website on Azure is a good choice.

Wherever you decide to deploy your website to, you must publish to a site that has a domain name (not an IP address) that has a (SSL) secure certificate (https://).

The URL will be required to create a client id, and it is also required for the Visual Studio publishing wizard (used to actually deploy the application to production).

The application will need a database, so be sure to create a linked resource…

…and specify a SQL Database.

Obtain A Client ID

To obtain a client id that will allow your application to be published in multiple SharePoint sites, you need to go to: http://sellerdashboard.microsoft.com and create an account.

The following steps only create a client id, it does not publish your application to the Microsoft Office 365 or SharePoint Online store. A client id is required for that process, but to actually publish your application in the store there is a secondary process.

After your account is approved (this may take a few days), log in and select APPS, then client ids and then add a new oauth client id.

Fill out the form.

• Friendly Client ID Name – Any name you want
   
• App Domain - The domain name without the “https://” part 
   
• App Redirect URL – Using this form: https://DomainName.com/SharePointLaunch.aspx?{StandardTokens}

You will receive your Client ID and Client Secret that you will need in the publishing wizard (in the next step).

Using The Publishing Wizard

In Visual Studio, open the Configuration Manager.

Change to Release mode.

While still in Visual Studio, open the publishing wizard.

Select Provider-hosted for SharePoint Options.

Choose your hosting option and click Next.

If you are using a Azure Web Site you would select it at this point.

The Azure Web Site option will allow you to sign in and select the web site you configured.

For Security Setting you must set https to required.

Therefore you must host the site at a location that has a secure certificate so that https will work. You cannot use a IP address, you must use a domain name.

Enter the domain name for the application, including the “https://” part.

For SharePoint Client ID and Client secret, enter the values saved earlier.

On the Summary page, click Publish to deploy the application.

Note, you will not be able to log into the website unless you are calling it through the SharePoint website using a link that will be created in the next step.

The .app file will also be created (Visual Studio will open it up in a window), we can now upload it to our SharePoint site.

Deploy The Application

To properly test your application, you will want to obtain another SharePoint site for testing.

See: Creating A SharePoint Online Testing Site for directions on creating a test site and deploying the application using the .app file.

When we run the application, each site can only see their own data.

When we log directly into the database we see that it stores data from each SharePoint site it is deployed on.

Changing The Database Connection String At Runtime

You can change the database connection string at run-time to allow each tenant to have their own database.

This method isn’t available in the Write Code drop down on the designers.  Instead, to find it, go into the ApplicationDataService.lsml.cs file…

… and start typing “partial “ and intellisense will show you an auto-complete drop down.  You can then select the _InitializingConnection method. 

The DatabaseConnectionState object passed into this method has one property, the ConnectionString, that you can get/set as needed.  This allows you to switch your data connection at runtime based on any rule you desire.

This method is only available for "Database" connections (either the ApplicationData or another attached Database data source).

For OData service and SharePoint data sources, the partial methods are:

partial void DeveloperData_SendingRequest(ODataSendingState state)
partial void DeveloperData_ReceivedResponse(ODataReceivedState state)

These methods allow you to intercept/inspect the outgoing request to the backend OData service, and inspect the incoming response from the backend service.

Special Thanks

A special thanks to Matt Evans, Eric Erhardt, Josh Booker, and Dave Kidder and for assistance in creating this article.

Links – Microsoft (LightSwitch)

SharePoint Hosting & Authentication Options for LightSwitch (Brian Moore)

Publishing LightSwitch apps for SharePoint to the Catalog (Brian Moore)

Using the Person Business Type

Integrating Documents in Cloud Business Apps

All About Newsfeeds With Your Cloud Business App (Nicole Haugen)

Links – Microsoft (Seller Dashboard)

Create Your Account and Add Payout Information in the Microsoft Seller Dashboard

How to: Create client IDs and secrets in the Microsoft Seller Dashboard

Create Client IDs and Secrets in the Microsoft Seller Dashboard

Microsoft Seller Dashboard FAQ

Links – LightSwitch Help Website

Deploy A LightSwitch Application To Office 365 / SharePoint Online

Creating A SharePoint Online Testing Site

Exploring SharePoint 2013 Visual Studio Cloud Business Apps (LightSwitch)

Implementing Documents in a SharePoint 2013 Cloud Business App (LightSwitch)