November 2013

Volume 28 Number 11

Visual Studio 2013 - Build Office 365 Cloud Business Apps with Visual Studio 2013

By Heinrich Wendel | November 2013

The requirements, expectations and importance of business applications have never been greater than they are today. Modern business applications need to access data available inside and outside the organization. They need to connect individuals across the organization and help them collaborate with each other in rich and interesting ways. The applications themselves need to be available on multiple types of devices and form factors, such as smartphones, tablets, laptops and desktops with various screen sizes.

You need a platform to provide a set of services to meet the core requirements of these applications. You also need a toolset that lets you productively build those applications while integrating with existing DevOps processes across the organization.

In this article, we’ll show how Visual Studio 2013 helps you build these modern business applications. We’ll create a recruiting app that manages job postings and candidates, providing experiences that seamlessly extend the Office 365 and Windows Azure platforms and use Office 365 services such as identity and social.

We’ll show how Visual Studio helps you be productive across the complete lifecycle of a Cloud Business App from building, running and testing, to publishing and using continuous integration.

Creating a New Project

Start by launching Visual Studio 2013. Click File | New Project. The Cloud Business App template is available under the Apps node of Office/SharePoint for both Visual Basic and Visual C# (see Figure 1). This categorization is based on the language used in the middle tier; the client is HTML and JavaScript.

Creating a New Cloud Business App Project in Visual Studio 2013
Figure 1 Creating a New Cloud Business App Project in Visual Studio 2013

A Cloud Business App comprises four projects:

  • The Server project, which is a basic ASP.NET project used to add tables and connect to data sources
  • The standard app-for-SharePoint project, which provides a connection to Office 365
  • The HTMLClient project, a JavaScript project in which you define the UI for your app (the screens)
  • The Cloud Business App project, which ties all of the projects together. You can see the Visual Studio project structure in Figure 2.

Cloud Business App Structure
Figure 2 Cloud Business App Structure

We’ll go through how to use each of these projects.

Defining the Data Model

Data lies at the heart of every business application. Cloud Business Apps offer a variety of ways to interact with that data. Let’s start by defining a new data model using the Table Designer. We’ll later deploy this data model to a Windows Azure SQL Database. We’ll use the Table Designer to define a Candidate entity. Figure 3 shows the details of the data model. Entities are made up of properties, which are either a simple data type such as string or integer, or a business type such as URL, Email Address or Person. Specific validation logic and unique visualizations are built into the Visual Studio tooling and runtime.

Figure 3 Candidate Entity Details

Property Name Data Type
Name String
Phone Phone Number
Email Email Address
ReferredBy Person
InterviewDate Date (not required)

A Cloud Business App is an app for SharePoint. It has access to data in the Office 365 tenant where it runs. Information workers use SharePoint on a daily basis to create, manage and share data in a collaborative environment. For our scenario, we’ll assume a SharePoint list is currently being used to track open job postings. Figure 4 shows this list, including data that was entered.

A Job Posting List in SharePoint
Figure 4 A Job Posting List in SharePoint

Let’s attach data to this list using the Add Data Source action in the context menu of the Data Sources folder. Select SharePoint in the first page of the wizard and enter the URL for the SharePoint site against which you plan to develop. (If you don’t have a SharePoint site for development, you can get one from dev.office.com—it’s free for a year with an MSDN subscription.) The next page shows all lists and document libraries available on the given SharePoint site. Import the Job Postings list by selecting it and finishing the dialog.

Relating data from two different data sources—SharePoint and SQL in this case—and writing business logic that works over both is one of the most powerful features you get when building Cloud Business Apps. Let’s add a relationship between Candidates and Job Postings using the Table Designer. We’ll set up a one-to-many relationship using the Add Relationship action in the Table Designer. We’ll specify that every Candidate can apply to just one Job Posting. Figure 5 shows the exact configuration of the relationship. Now that we’ve defined the data model, we’ll change our focus to providing a UI for the app.

The One-to-Many Relationship Between Candidates and Job Postings
Figure 5 The One-to-Many Relationship Between Candidates and Job Postings

Designing the UI

In today’s world it’s no longer enough to create UIs that just work. Users expect apps that work across a breadth of devices, from smartphones and tablets to traditional desktops. They also expect apps to be usable with touch as well as keyboards for heavy data input. Apps should look consistent throughout the company and have specific branding. Cloud Business Apps provide you with templates, layouts and controls to easily accomplish these nontrivial tasks.

We’ll create a set of three screens and define the navigation flow between them. The first screen will show a tiled list to let you browse all candidates in the database. From here, you can navigate to a second screen to add a new candidate, or drill into the details of an existing candidate on a third screen.

Add the first screen by selecting the Add Screen action in the context menu of the Screens folder in the HTMLClient project. The screen template dialog offers three templates you can use as good starting points. For the first screen, we’ll use the “Browse Data Screen” template. Make sure the Candidate entity is selected in the Screen Data dropdown and complete the dialog.

The Screen Designer displayed in Figure 6 is composed of two parts. The data bound to the screen is shown in the side panel on the left, and a hierarchical view of your screen is in the main area.

The Screen Designer Showing the Browse Candidates Screen
Figure 6 The Screen Designer Showing the Browse Candidates Screen

Select the List in the screen designer and set up the Item Tap Action from its properties sheet. Instead of writing your own method using JavaScript code, you can select from a set of commonly used predefined methods. Choose Candidates.viewSelected, and follow the wizard to create the details screen. Back on the first screen, select the Command Bar and add a new button. This time use the Candidates.addAndEditNew method and create an Add Edit Details Screen.

Now that the basic screens and navigation between them are defined, let’s tailor their appearance. You can render a list of entities in three ways: using the standard list, a tabular view or a tile list. The list is a good fit for more complex layouts, whereas the tabular view is optimized for data-intensive tasks.

For now, we’ll choose the tile list, which makes better use of screen real estate and scales best across different screen sizes. Remove all child items from the tile list node except Name, Phone and Email. Finally, select a better visualization for the command from the set of icons included by changing the Icons property in the properties sheet.

The App in Action

It’s time to take a look at the running app. Press F5 in Visual Studio to run it in the browser. The first time the app is deployed to your SharePoint developer site, a dialog asks you to approve a set of permissions. Subsequent F5s will skip this step unless you change the SharePoint project within your solution.

The app is loaded using the Single-Page Application (SPA) architecture with the UI completely rendered by client-side code. Communication with the server is performed using asynchronous calls, resulting in a fast and fluid experience. One example where you can see this is the list of candidates on the home screen, which uses incremental scrolling. When reaching the end of the lists, the next set of items is dynamically loaded in the background without blocking the user.

All layouts adapt well to different form factors using responsive design techniques. Resizing the browser window gives you a quick way to see how the app looks on a phone or tablet, as shown in Figure 7. Everything has been optimized for touch but works equally well on a desktop using the keyboard and mouse.

All Three Screens of the Running Cloud Business App on a Mobile Device
Figure 7 All Three Screens of the Running Cloud Business App on a Mobile Device

Now let’s add a new candidate. The dialog displayed gives you the expected set of input fields and a picker that lets the user choose the Job Position from the attached SharePoint List. Select the ReferredBy value using an auto-complete textbox that shows suggestions based on your organization’s user directory—for example, something like Active Directory.

You can see additional Office 365 integration on the details screen, which shows presence information for each person. A Lync contact card shows detailed information and allows for rich interaction such as initiating an IM conversation, sending an e-mail or scheduling a meeting.

The fields that track when and by whom an entity was created and last modified are added automatically. These help fulfill common auditing requirements without writing any code. If they aren’t required for your scenario, you can switch back to the screen designer without stopping the app, remove the fields and save the screen. Refresh your browser—there’s no need to restart the app in Visual Studio—and the changes are reflected in the app immediately.

Adding Business Logic

The productive development experience we’ve described so far lets you focus your energy on the unique value of the app: the business logic. Let’s say that only employees from the human resources department should be allowed to schedule interviews for candidates. This kind of organizational information is usually stored in Active Directory.

In Office 365, Active Directory is surfaced to developers via the User Profile Service. A strongly typed API has the most commonly used properties, such as a user’s department. You can add custom properties specific to your organization to the User Profile service using the SharePoint Admin center. You can also retrieve these in code using standard SharePoint APIs to talk to the User Profile service directly.

Business logic is written on the middle tier, which is represented by the server project in this solution. The Table Designer Write Code dropdown provides you with an extensive set of entry points into the data pipeline of your app. Here we’re handling the validate event and using the Application object to query the current logged-on user’s department:

if (entity.InterviewDate !=
  null && Application.Current.User.Department != "HR") {
  results.AddPropertyError("Only HR can schedule interviews",
  entity.Details.Properties.InterviewDate);
}

Start your app again, or just refresh your browser if you didn’t stop the app already. Now, trying to set the interview date for a candidate will result in an error because you aren’t a member of the human resources department. This logic runs on the middle tier, which means the validation rule will run regardless of how clients connect to the service.

Integrating Enterprise Social

Social networks are used for communication and collaboration. Users expect modern business apps to integrate with these social networks. Cloud Business Apps enable social integration with just a few clicks using the SharePoint Newsfeed feature. In this first version, you must configure SharePoint to use SharePoint Newsfeeds rather than Yammer.

Design-Time Options Open the Candidate entity in the Table Designer and view the Properties window. The Social section has options for generating a post to the Newsfeed on creation and on update of the entity. Enable both of these. You can control which properties trigger a social update using the “Choose post triggers...” link. Select only the InterviewDate post trigger, as shown in Figure 8. The Summary property lets you select what data about the entity will be shown in the post.

Social Properties and Post Triggers Dialog
Figure 8 Social Properties and Post Triggers Dialog

Runtime Newsfeed Run the app to see the social integration that has been configured. Notice the Newsfeed and Follow links in the top-right corner. The Newsfeed link opens a new window to a page that shows the app’s activity. Think of this as the app’s internal social feed. The Newsfeed page has an entry for each newly created Candidate and each Candidate for whom the interview date changed. Clicking on the post takes you directly to the Candidate details screen. In addition, users can start a new conversation or Like or Reply to any of the posts. Add a new Candidate or change the interview date of an existing Candidate to see examples of this activity being generated on the Newsfeed page, as shown in Figure 9.

The Cloud Business App Newsfeed Page
Figure 9 The Cloud Business App Newsfeed Page

Having the Newsfeed option is helpful if you want to look at the activity from within the app, but there’s an easier way to follow the app’s activity on a regular basis. Clicking the Follow link on the home screen will cause the same social posts and conversations to be posted to the user’s personal Newsfeed. This lets the user follow what’s going on in this app or any other Cloud Business App, Person or Document in a centralized location.

Publish

Now that you’ve built and tested your app locally, it’s a good time to deploy the app to other employees in your organization. Select Publish from the context menu of the Cloud Business App project in Solution Explorer. The publish dialog walks you through the choices you have when publishing a Cloud Business App: SharePoint hosting method, hosting of app services, data connections and SharePoint authentication.

Let’s take an optimal path for publishing the Cloud Business App to Office 365 using a secure Windows Azure Web Site to host the app services and Windows Azure SQL Database to host the database.

You can publish the app to the Office Store or your company’s app catalog. If the goal were to create an app available for the public, then the Office Store makes sense. If the app is intended only for internal use in your organization, then using your app catalog is the way to go. The app catalog lets you push the app out to many sites automatically. This simplifies acquisition of the app for the end users and management. Only a single instance of the app actually exists, even though users can access it from many different sites.

SharePoint Hosting Method Select the Provider-hosted option, which gives you more control over how you’ll deploy different parts of the app. It also provides greater visibility into how the app is performing, makes it easy to scale the different layers of the app and provides full control over the lifetime of the app’s data.

Hosting of Application Services Now you need to decide between hosting the application services in Windows Azure or on an IIS server. Windows Azure is the easiest and fastest way to create a hosting environment. You don’t have to set up a machine or even configure IIS, as Windows Azure takes care of this for you.

Next, select the specific Windows Azure subscription to use. If you’re signed in to your Windows Azure account, select the subscription you’d like to use. Otherwise, you’ll need to sign in to see the available subscriptions.

The Service Type tab (see Figure 10) provides options for using a Windows Azure Web Site or Cloud Service. Choose the Web Site option. The Web Site option is a great choice for Cloud Business Apps because of how quickly you can push the app out, the low cost for hosting it and the ease with which the app can be scaled up if it becomes popular. Using the Windows Azure Web Site option still gives you access to other Windows Azure services such as SQL databases, caching, BLOB storage and service bus.

The Publish Dialog
Figure 10 The Publish Dialog

Next, select the specific Windows Azure Web Site you want to use. If none are listed, or if you want to create a new one, use the link to go to the Windows Azure Portal. Finally, choose the HTTPS option so communication is safely encrypted.

Data Connections Now it’s time to configure the database connection to use for the app. If you’ve already linked a SQL database to the Web Site, then the connection string will be filled in correctly. If not, you can create a new linked resource by following the appropriate steps in the article, “How to Configure Web Sites,” in the Windows Azure documentation at bit.ly/151m3GM. You could also simply use the connection string of an existing SQL database. On the Attached Data Sources tab, make sure the connection is pointing to the appropriate endpoint—often connection endpoints are different based on whether you’re publishing to production or a different environment.

SharePoint Authentication The last thing you need to configure is the type of SharePoint authentication to use. This is required to enable the application services hosted on the Web server—Windows Azure in this case—to communicate with SharePoint. In the SharePoint Authentication tab, you need to select the “Use a client secret” option because you’re using Office 365. To use this type of authentication, you’ll need to acquire a Client Id and Client Secret. These are basically a user ID and password for the app. They’re required in order to use Open Authorization (OAuth), which is an open standard for app authorization.

We’ll be publishing the app to the app catalog because we only want it to be used by people within the organization. Therefore, to get a Client Id and Client Secret, you need to do the following:

  • Sign in to the Office 365 SharePoint site to which you plan to deploy the app and navigate to https://Your­SharePointSiteName/_layouts/15/appregnew.aspx (Figure 11 shows the AppRegNew.aspx page).
  • Click the Generate button for both Client Id and Client Secret.
  • Enter the name of your app as the Title and the domain for the Windows Azure Web Site as the App Domain.
  • Leave the Redirect URI textbox empty and click the Create button.

The AppRegNew.aspx Page
Figure 11 The AppRegNew.aspx Page

Back on the publish dialog window in Visual Studio, copy the Client Id and Client Secret from AppReg-­New.aspx confirmation page. On the next tab, the URL of your Windows Azure Web Site should already be filled in.

Publish the Cloud Business App You should now see the Summary tab showing a recap of the options you just configured. Click the Publish button to publish the Cloud Business App to the various endpoints. After deployment is finished, a File Explorer window will open showing the .app file. This is the SharePoint app package you need to upload to your app catalog. To learn more about this, see the steps in the Microsoft Office support article at bit.ly/1bnIrRY.

At this point, the app is in the app catalog and you can install it on one or more sites.

Continuous Integration

Continuous integration can save you time by automatically publishing your app throughout the development process. In team environments where multiple developers are constantly making changes, continuous integration ensures your app will be compiled, packaged, and published in an automated and consistent manner.

Team Foundation Server To take advantage of continuous integration for Cloud Business Apps, you either need Visual Studio Team Foundation Server (TFS) 2013 installed on-premises or use TFS in the cloud, Team Foundation Service (see tfs.visualstudio.com). If you’re using TFS 2013 on-premises, make sure you download the TFS build process template and install it for your team project. Currently, the new process template only supports deploying the SharePoint part of a Cloud Business App to Office 365-hosted SharePoint sites. On-premises SharePoint sites aren’t yet supported.

Create a Build Definition A build definition describes the continuous integration process and consists of a build process template (a .xaml file describing a workflow) and configuration data unique to your environment. To create a new build definition in Visual Studio, make sure you’re connected to your TFS machine and your app is checked in to source code control. On the Builds panel in Team Explorer, select New Build Definition.

Following are the key aspects of a build definition and a more detailed description of the new parameters specific to Cloud Business Apps (you’ll see six tabs on the left after clicking to create a new build definition):

  • General: Select this to supply the name, description and queue processing rules.
  • Trigger: Select this to specify when you want a build definition to start. You might want to set this to manual until you’ve confirmed the build definition operates as intended.
  • Source Settings: Select this to specify what you’re building.
  • Build Defaults: Select this to specify the build controller that will process the build definition and where the output should be placed.
  • Process: Select this to choose the build process template to use and parameters to pass into the workflow.
  • Retention Policy: Select this to specify how long build outputs should be retained.

Three new parameters for a Cloud Business App build definition are located on the Process tab. First, select the build process template created for Cloud Business Apps. Click the “Show details” expander and choose either the TfvcContinuousDeploymentTemplate.12.xaml template or the GitContinuousDeploymentTemplate.12.xaml template. Expand the Deployment Settings section to configure the new parameters (shown in Figure 12), which are:

  • Path to Deployment Settings: This parameter contains the path to an XML file that contains publishing information about the Cloud Business App, including the database connection string for the intrinsic database and endpoints for any attached data sources.
  • SharePoint Deployment Environment Name: This parameter contains the SharePoint URL, username and password that will be used to connect to the SharePoint server where the app will be published.
  • Windows Azure Deployment Environment Name: This parameter contains the required information for connecting to the Windows Azure subscription.

Build Definition Dialog
Figure 12 Build Definition Dialog

Queue a Build Definition Now that you’ve supplied the necessary configuration data to take advantage of continuous integration, it’s time to kick off a build. Locate the build definition you just created in the Builds panel and select Queue New Build from the context menu. Leave everything as is in the dialog that’s displayed and queue the build. It will be picked up by the build controller when it’s free.

To see the builds in the Build Explorer, select View My Builds from the Actions dropdown on the Builds panel. You’ll see that the Build Explorer has two tabs: one for queued, in-progress and recently completed builds; and one for builds completed earlier. You can see a log for any build by selecting it in the explorer, including additional diagnostics information if the build has failed.

Get Started Today

We’ve shown you highly productive experiences for defining data and screens that let you quickly get an app up and running. The app has a professional-looking UI that blends with SharePoint and is integrated with a set of Office 365 services such as Lync presence and contact card, person picker and social. We’ve shown you how you can use the Microsoft .NET Framework to customize your app and—when you’re ready—how to publish your app and configure continuous integration as part of your development process.

Start building Cloud Business Apps today. All you need is Visual Studio 2013 and an Office 365 developer subscription to use as a sandboxed developer environment. MSDN subscribers are eligible for a one-time, 12-month, single-user Office 365 Developer subscription. Go to bit.ly/1fvYeAT to learn more.


Mike Morton *has worked at Microsoft for many years in both the Information Technology group and in the product groups as a developer, architect and other roles. He is currently a program manager on the Visual Studio team that creates the tools for developing apps for Microsoft Office and SharePoint as well as the new Cloud Business Apps. Recently Morton has spent time building the new “Napa” tools, which work completely in the browser. *

Jim Nakashima is a principal PM on the Visual Studio Cloud Platform Tools team focusing on building great end-to-end developer experiences for Microsoft Office and SharePoint. Prior to his current role, Nakashima spent a number of years working on Windows Azure, which fueled his interest in the cloud and developer services that he now applies to Visual Studio.

Heinrich Wendel is a program manager on the Visual Studio team that builds the Cloud Business Apps tooling at Microsoft. Before joining the product group, he worked as a consultant designing business solutions for customers leveraging the SharePoint platform. Wendel is passionate about the modern UX and tries to bring its benefits to developers and end users alike.

Thanks to the following Microsoft technical experts for reviewing this article: Joe Binder and Brian Moore

Joe Binder is a Principal Program Manager who works on Visual Studio’s tools for Azure, Office 365 and business application development.  He was one of the original members of the Visual Studio LightSwitch team and helped shape its development and direction since its inception.  Binder is passionate about building great user experiences in business applications and high productivity application development. Prior to joining Microsoft, he studied computer science at Rochester Institute of Technology.

Brian Moore is a Program Manager currently working on integrating Cloud Business Apps with Office 365 and Windows Azure into the Visual Studio product line.  He has worked on all versions of LightSwitch projects in Visual Studio and over the past 20 years he has spent time in every major division at Microsoft, including different countries and campuses around the U.S.  A VB developer at heart, his passion is bringing simplicity to modern day line-of-business applications.