You are here:   Blog
Register   |  Login

LightSwitch News

 

Jun 5

Written by: Michael Washington
6/5/2014 10:12 PM  RssIcon

image

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). 

image

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

image

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

image

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).

image

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:

image

Next, set the table to update the SharePoint Newsfeed

image

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.

image

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;
        }

 

image

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;
        }

 

image

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.

image

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

image

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

image

Select the Common Screen Set template.

image

The screens will be created.

Format The Screen

image

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

image

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.

image

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

image

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.

image

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

image

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

image

You will have to Trust the application.

image

The application will load.

image

We can add Tasks by clicking the Add button.

image

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

image

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.

image

We can also navigate to the Newsfeed

image

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

Publish The Application

image

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://).

image

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).

image

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

image

…and specify a SQL Database.

Obtain A Client ID

image

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.

image

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.

image

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}

image

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

image

In Visual Studio, open the Configuration Manager.

image

Change to Release mode.

image

While still in Visual Studio, open the publishing wizard.

image

Select Provider-hosted for SharePoint Options.

image

Choose your hosting option and click Next.

image

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

image

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

image

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.

image

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

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

image

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.

image

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

image

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.

image

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

image

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.

image

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

image

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

image

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)

Embedding Your LightSwitch Cloud Business App Inside SharePoint As a App Part

Download Code

The LightSwitch project is available at http://lightswitchhelpwebsite.com/Downloads.aspx

(you must have Visual Studio 2013 (or higher) installed and a SharePoint Developer site to run the code)

4 comment(s) so far...


Gravatar

Re: Creating A LightSwitch SharePoint 2013 Multi-Tenant Provider-Hosted Application

Michael,
Excellent article !

That's a great idea to use the HostUrl to discriminate between tenants.
Just one hint: in order to avoid that the HostUrl is shown by default on html screens, and to avoid you need to remove it, you can also uncheck "display by default" in the entity designer"s html client tab.

By paul van bladel on   6/6/2014 10:59 AM
Gravatar

Re: Creating A LightSwitch SharePoint 2013 Multi-Tenant Provider-Hosted Application

@paul van bladel - Good point, thanks!

By Michael Washington on   6/6/2014 10:59 AM
Gravatar

Re: Creating A LightSwitch SharePoint 2013 Multi-Tenant Provider-Hosted Application

Nice article, thanks for the mention. I linked to your article on my blog post:

http://joshuabooker.com/Blog/Post/14/LightSwitch-Dynamic-Connection-Strings-Now-Supported

Cannot wait to try out the dynamic conn strings. Will be interesting to see what new provisioning options for provider apps come out in the light of auto-hosted being canned.

Have a nice day!

By joshbooker on   6/7/2014 7:05 AM
Gravatar

Re: Creating A LightSwitch SharePoint 2013 Multi-Tenant Provider-Hosted Application

Kick-ass awesome post!
I created an addendum on my blog on how to make the code a bit more generic, so that you don't have to repeat yourself for every entity. - http://janvanderhaegen.com/2014/08/21/addendum-a-generic-way-to-create-a-lightswitch-sharepoint-2013-multi-tenant-provider-hosted-application/
Keep rocking LS!

Jan

By Jan Van der Haegen on   8/21/2014 2:53 PM

Your name:
Gravatar Preview
Your email:
(Optional) Email used only to show Gravatar.
Your website:
Title:
Comment:
Security Code
CAPTCHA image
Enter the code shown above in the box below
Add Comment   Cancel 

Microsoft Visual Studio is a registered trademark of Microsoft Corporation / LightSwitch is a registered trademark of Microsoft Corporation