Getting started with SharePoint Cloud Business Apps using Visual Studio 2013

Posted Tuesday, November 26, 2013 11:35 AM by CoreyRoth

Cloud Business Apps are a new project type that you will find in Visual Studio 2013 for SharePoint development.  What exactly are they?  They are the next evolution of LightSwitch using the app model.  If you’re not familiar with LightSwitch, it’s a light-weight developer tool inside Visual Studio that lets you create applications rapidly.  It allows you to create data stores and connect to external data using a designer.  I first saw them in the release candidate build of Visual Studio 2013 but couldn’t get very far with them since there was not much documentation at the time.  MSDN Magazine published an article on them recently and this gave me the information to dig more into them.  If you haven’t read that article yet go take a look.  I wanted to expand on it though with a step-by-step example and lots of screenshots.

To get started, look for the new Cloud Business App project type under Office/SharePoint in the New Project dialog.  In my example, we’re going to make a simple app that allows us to manage customers and their feedback.


Give the project a name and then you’ll go to the next step where you specify the site that you are going to develop your app on.  Like working with other types of SharePoint apps, keep in mind that you need to have an existing site collection using the developer site template.  Like working with other apps, you don’t need to have SharePoint installed locally.  You can work directly with your developer site hosted in SharePoint Online.  If you don’t have a developer site, you can click on the link to either get a trial or use your MSDN subscription.


When you click Finish, it will create a number of projects in Visual Studio in this order:

  • Cloud Business App project – has configuration for the entire app itself
  • HTMLClient project – contains the screens for your project
  • Server project – contains your data model
  • SharePoint App Project – entry point to your app


Ultimately, what you are building here is a provider-hosted app.  This just takes a lot of the pain out of the process. 

When you create your solution, you start out with a blank design surface where you can start working with your data.  We start by adding our data model and relationships.  Then we can start defining screens and the navigation between them.


We’re going to start by defining a customers table with some basic contact information.  Clicking the Create new table button opens the table designer.  You will need to rename the table to something meaningful and then you can add your properties.


You’ll see familiar SQL data types in the list plus some additional custom ones such as Email Address and Phone Number.  Selecting one of these types will provide some automatic validation in your forms.


In my example, I’ll add my remaining fields.


The power of the Cloud Business App is that you can relate data regardless of where it comes from.  Ultimately, the Customers will be stored in SQL, but I am going to track the feedback in a SharePoint list.  The list is simple and just contains Title, Description, and CustomerName fields.  Here is what the list looks like in SharePoint.


To add external data, click the Attach to External Data button on the Customers table design surface.


On the next step, we provide the URL to the SharePoint site that contains the list.  You can also specify specific credentials otherwise it will just use the user’s credentials.  Keep that in mind with your permissions on the list.


Now, select the lists that you want to include.  In my case, I am including the Customer Feedback list.


When you finish you will see a table designer for the SharePoint list.  This one is different though in that you cannot edit any of the fields.  It will also automatically create a relationship to the UserInformationList table so that you can get names of users as opposed to just their Ids.


Now what we need to do is add our relationship between the Customers SQL table and the CustomerFeedback SharePoint list.  Click the Relationship button to make this happen.  In this screen select the tables you are mapping and then specify the multiplicity.  In this case, I can have multiple feedback items per customer.  The last thing you need to specify is the common fields to use for the join.  In my case, I simply used the name of the customer.  Normally, you wouldn’t join this way but I was having issues using a number field in SharePoint and the auto-increment value in SQL.  The data types come across as int in SQL and double in SharePoint so it won’t let you map it.


Now that we have our data model defined, we can start adding screens to manipulate the data as well as navigation elements.  Go back to the Customers data model and then click the HTMLClient button.  This allows us to click the Add Screen button at the top.


This takes us to a wizard where we can choose what type of screen to add.  Let’s start with the Browse Data Screen which lets us view a list of all of the items in the table.


In the Screen Data dropdown, select the Customers table.  Click OK and we will be taken to a new designer that lets us customize how this screen works.


This interface looks a bit intimidating but is actually quite powerful once you start playing around with it.  At this point, we can actually run our app.  It won’t do much, but let’s take a look.  Press F5 to begin debugging.  When you deploy, you may get prompted for authentication.  You might also need to trust the app as well.


When you launch the app, you’ll see the Browse Customers screen.


Unfortunately, there is not much we can do at this point.  We still need to create views to edit and view the data.  Let’s do that next.  Go back to the HTMLClient of the Customers data model and click the Add Screen button again.  This time select Add / Edit Details Screen.  Notice how the wizard includes the CustomerFeedback table due to the relationship.  Select the checkbox next to it and complete the wizard.


This takes us to the editor for the screen itself.  Take notice that there is a Rows Layout for both the Customers table and the Customer Feedback.  Here we can configure how the form fields are displayed by dragging and dropping them.  There are a number of pre-defined layouts as well.  We’ll go into that more here in a bit. 


Repeat the same process for the View Details screen as well.  This gives us the screens we need to view and edit our data, but unfortunately we still don’t have any way to get to them.  We need to add navigation.  Go back to BrowseCustomers.lsml.  The screen is laid out using tabs and then in each tab you can specify different types of layouts to display the data.  Look for the Command Bar and select it.  Then click Add Layout Item –> Button


This takes us to a screen where we can add a button to navigate to the other screens.  We’ll start by adding a method to the Add / Edit screen.  Choose an existing method and look for Customers –> addAndEditNew.  Depending on the steps you took, the naming might vary slightly but it should be obvious which one you want.


Repeat the same process for the View Screen.  Now when we launch the app, we should have some shiny new buttons.  Here is what the screen looks like after I have added my first customer.


Let’s take a look at what the Add Customer form looks like.


This gives us a decent form and we even get a little validation.  If you noticed all of the buttons on the site, you might have noticed they seemed a bit tablet friendly.  That’s because they are.  This entire thing is implemented with responsive web design.  That means, we can shrink the browser width and the form resizes accordingly.


Notice how the second row of form fields automatically collapses into one vertical column.

Now let’s take a look at the View Details screen.  Since I defined the Web Site column with the appropriate field type, it automatically makes it a hyperlink.  Notice there is a tab there for Customer Feedback.


Clicking on it allows shows us the data from our SharePoint list in a summary view.


There we have it.  We have related data from SQL and SharePoint without writing a single line of code.  What if we want to make edit an existing customer.  To do that, go to BrowseCustomers.lsml and look for the Add button under the Customers list.


Choose the editSelected option to create a new button.


This gives us a new Edit Customer button when selecting a customer out of the list.


Wouldn’t it be nice if this browse customers screen showed some more information now?  That’s pretty easy to do.  Go back to BrowseCustomers.lsml again.  Click on the arrow next to list and you will see some options.  Try Table or Tile List (again sticking with the touch friendly theme).  Choosing custom control will allow you to define your own layout using code.


Once you choose one of the other layouts, you’ll have some new options available.  In the case, below I chose Table and it then lists all columns in the table.  We can then add and remove columns as desired.


Now when we refresh our browse customers page, we have the data presented in a grid.


Hopefully, this gives you a nice overview of what you can do with Cloud Business Apps.  There is lots more that I can show you, but this post is already quite long so I’ll save those things for a follow-up.  As you can see, Cloud Business Apps really aren’t hard to get started with.  Unfortunately, deploying them in a production scenario does seem a bit more involved.  Refer to the end of the MSDN article for help on setting up your certificates and the Azure web sites.  The nice thing is that they are built to run with Office 365 but they should work on-premises as well.


# re: Getting started with SharePoint Cloud Business Apps using Visual Studio 2013

Monday, December 16, 2013 8:36 AM by Jimmy

Hello Corey,

I'm new to SP Development and followed your instructions carefully, but I think I've missed something, because I'm not able to add a customer, I get the following error:

"Personal information necessary to process the request could not be obtained"

Can you please tell me what do I have to change/add?


# re: Getting started with SharePoint Cloud Business Apps using Visual Studio 2013

Monday, December 16, 2013 9:45 AM by Jimmy

Forget my reply, I've fixed the error by deleting the browser cookies and redeploying the app. I works now. Thanks for your post.

Leave a Comment