https://blogs.office.com/dev

Here is the RSS feed for the new Office Developer blog: https://blogs.office.com/feed/?filter-audience=dev

Please join us in this new location to keep reading all the latest news about developing Apps for Office and SharePoint.

Don’t worry, we won’t delete any of these MSDN blog posts – they’ll stay here so you can continue to refer to them for the information you need.

Here are all the places where you can join the Office Developer conversation:

^{Twitter @OfficeDev}

^{Facebook Office Developer}

^{Yammer - Office 365 Technical Network}

^{MSDN forums}

^{Stackoverflow [MS-Office] [Office365] [OneNote]}

^{Office Developer Center}

You can now access the Office 365 REST APIs from .NET and JavaScript, using a new set of client libraries. These libraries make it a lot easier to interact with the Office 365 APIs, from popular device and desktop platforms. The libraries are included in the latest update for Office 365 API Tools for Visual Studio Preview. Along with the libraries, this release also brings you some key updates to the tooling experience making it easier to interact with Office 365 services. 

Read all about it here! .NET and JavaScript Libraries for Office 365 APIs, Available in Preview

Download the tools here.

And for more developer-related announcements from TechEd, see Soma's post.
 

Enjoy!

In last month’s blog post, we announced the Office 365 API Tools – Preview add-in for Visual Studio 2013. By using Office 365 APIs, developers can access users’ data in the Office 365 cloud, e.g., reading calendar information, storing documents, or sending emails on behalf of users. The Office 365 APIs are an open platform that is available across a variety of languages and technologies. If you’re developing Model-View-Controller (MVC) web projects or Windows 8.1 applications, our Office 365 API Tools for Visual Studio will make it that much easier to add Office 365 APIs to your solution.

The previous post focused on getting started with the tooling and the Office 365 APIs – going through the registration piece and exploring the sample code. This post continues from where the previous post left off, going from using the generated sample code to authoring your own. If you haven’t already done so, I highly recommend reading the previous post before continuing with this one.

Note A couple of weeks ago (April 7, 2014), we released an updated (1.1) version of the Office 365 API Tools – Preview, which offers some reliability improvements to the tool, along with some slightly modified sample code (particularly in relation to SharePoint). Today’s blog post assumes you are using the latest version of the tools and the accompanying samples.

Recap of the Project Structure

In last month’s blog post, we took a look at the files that are added by the Office 365 API Tooling. If you have not already, I would encourage you to read the “Exploring the project structure” section of that post – including the diagrams that show which files are added to the MVC Web Application and the Windows 8.1 app. In a nutshell, after registering an app with the Azure Active Directory, the Office 365 API Tools make the following modifications to a project:

• Add NuGet packages for Active Directory Authentication Library and Json.NET.
• Add a set of common helper files (files whose names start with "Office365*," such as "Office365ServiceInfo") that are common across different services.
• Add a set of service-specific sample files (for example, ExchangeSampleController and its accompanying View folder for MVC, or ExchangeSamplePage.xaml and its accompanying code-behind for Windows 8.1).
• Modify Web.config or App.xaml to include the Client ID (and, in the case of web apps, the Password) for the app.

The NuGet additions and the Web.config/App.xaml modifications are fairly straightforward, so in terms of new files added to the project, we’re left with the helper files and the service-specific sample files. The helper files are designed to be fairly transparent to the developer, as they encapsulate functionality that you shouldn’t need to worry about. The one exception is error-handling, where you may want to customize the experience by customizing the UI or writing the errors to a log or database. We’ve left a TODO flag in the Office365Helper and Office365CommonController files to make it clear where such error-handling logic should be implemented. For the rest of the helper-class implementations, you can treat those files as library files and generally avoid peeking into them, except to satisfy your academic curiosity.

Instead of exploring the underlying plumbing of the helper files, this blog post will focus on showing you how to use the files to accomplish your business needs.

A note on the differences between MVC Web Apps and Windows 8.1 apps

No doubt, every developer has faced the frustration of learning to do something one way – and then needing to re-learn a completely different approach for a similar scenario.

When designing our helper classes, we worked hard to ensure that much of the individual differences between platforms and services are abstracted away. Using our helper classes, accessing Exchange from a Windows 8.1 app feels no different than accessing SharePoint from an MVC web app. For example, authentication on Windows 8.1 apps has different caching mechanisms than web applications, but our helper classes handle it transparently for the developer in either case. Likewise, accessing OneDrive for Business in SharePoint requires an extra discovery step, whereas accessing Exchange does not; but again, this is not be something that a developer needs to remember. By using our helper classes, the code that you author will be similar both in spirit and structure, no matter which project type and which service you choose to target.

So, what does the sample code look like when the individual differences are abstracted away by helper classes? Let us take a function that retrieves calendar events from Exchange and take a look, step by step.

Performing a GET request

Step 1: Obtain information for communicating with the service

To use the helper functionality, first you need to create an object to represent the service. The object type is one of the helper classes, Office365ServiceInfo. This class encapsulates information about a service’s API endpoint, resource ID, access token, error handling, and more (generally speaking, much of this information should be transparent for your code). All you need to do is obtain an instance of the service, and then pass it around to other helper functions.

To construct an Office365ServiceInfoinstance, the Office365ServiceInfo file offers a number of static methods that construct an instance of a particular service type:

By necessity, this preamble to get the Office365ServiceInfo object is somewhat different between the two project types – but it does stay identical between services (merely substituting GetExchangeServiceInfoAsync for GetOneDriveServiceInfoAsync, GetActiveDirectoryServiceInfoAsync, etc).

As a side note, the reason for the difference is that a web project must redirect to a login page and then back to itself in order to show a login UI, whereas a Windows 8.1 project is able to display the login screen as an overlay dialog. Thus, whereas the MVC code needs to redirect to the authorization URL if no access token is retrieved, the Windows 8.1 code does not. The difference also accounts for the need to “await” the dialog in Windows 8.1 (though certain services, like GetOneDriveServiceInfoAsync, still need to be async even in the case of an MVC Web App, as they first require a call to a Discovery service).

Step 2: Create a URL for retrieving the data

The next step is to construct a URL to call into the service. This code is completely the same across project types (though it is different for different service types).

How do you know which URL to use for the service, and which query parameters to pass in? In the MSDN Office 365 APIs Preview documentation, choose an appropriate section for your service type, such as the article on Using the Mail, Calendar and Contact REST APIs. For this example, the “Work with calendar items” section describes the format of the query to retrieve calendar data and even suggests a filter that you can apply, which is part of the standard ODATA syntax.

GET https://outlook.office365.com/ews/odata/Me/Calendar/ Events?$filter=Start le 2014-02-14T05:00:00Z and End ge 2014-02-10T05:00:00Z HTTP/1.1

Accept: application/json

Armed with the example above, we can create our own query. In the case of the sample code that the tool produces, this query will retrieve the top 10 upcoming calendar events (and minimize data sent over the wire by doing only a select on a few fields):

Note that to reduce error, the code above substitutes serviceInfo.ApiEndpoint into the beginning of the query, so that you don’t have to type out the same API endpoint (“https://outlook.office365.com/ews/odata”) every time. In addition to saving on typing, this pattern also makes calling different services consistent, whether the API endpoint is static (as it is for Exchange and Active Directory Graph) or dynamically discovered (as in the case of OneDrive for Business).

Step 3: Prepare the HTTP request

Now that the URL for obtaining the data is prepared, the next step is to create HttpClient and HttpRequestMessage objects. While the sample code creates a new HttpClient object every time, you may instead choose to keep it around for easy reuse. The code is the same across project types and fairly similar across service types as well. Differences worth noting are things like substituting odata=verbose versus odata=minimalmetadata for the Accept headers, depending on the service type. For such things, the MSDN documentation gives guidance on which Accept or ContentType headers the REST calls expect.

For the case of doing a simple Get on Exchange, the following will suffice:

You may wonder, why do we create a lambda (e.g., a function that returns an HttpRequestMessage) rather than just creating the appropriate HttpRequestMessage object? The reason is that a request could fail because of an expired access token, in which case a new access token would need to be created and a new request dispatched to the service. Because an HttpRequestMessage object cannot be used more than once, the procedure for creating the request is captured as a lambda.

The whole business of retrying a request sounds tricky, but fortunately our helper code handles it for you. All you need to do is use the helper, and then you can just read the data. The only difference between the MVC code and the Windows 8.1 code is the name of the helper: Office365Helper vs. Office365CommonController.

Step 4: Read the response and de-serialize the data

With the response received, it’s time to read the response object; and, in case of failure, to use the common error-handling function to parse out the human-readable error from the response and display it to the user. As mentioned before, the error-handling implementation has a basic default behavior, but you can customize it to suit your needs. The code is the same across service types, and only mildly different between platforms (redirecting to a special error view in the case of MVC, versus displaying an error dialog in the case of Windows 8.1)

Finally, if the response was successful, you typically want to perform some action based on the response. For GET operations such as retrieving mail, calendar, or files, this may involve de-serializing the data. For POST operations, you may still want to de-serialize the data, or you might be content to know that the operation succeeded.

If you do need to de-serialize the data, using a library such as Json.NET (which is added automatically to the project when you add an Office 365 service) makes it possible to work with the returned data as if it is a .NET object. First, however, you need to define the shape of the data that you expect to receive over the wire. The same MSDN documentation as before will show the shape of the returned data. Thus, continuing with the previous example, the section on Work with calendar items defines not only the query format, but also the entirety of the object that you will get back.

Trimming for brevity, the MSDN documentation shows something like this:

{

  "@odata.context": "https://outlook.office365.com/EWS/OData/$metadata#Me/
Calendar/Events", "value": [

    {

      "@odata.id": "https://outlook.office365.com/EWS/OData/Users
('sadie@contoso.com')/Events('AAMkAGI3...')",

      ...

      "Subject": "Lunch",

      ...

      "Start": "2014-02-13T20:30:00Z",

      "End": "2014-02-13T21:00:00Z",

      ...

    },

    {

      "@odata.id": "https://outlook.office365.com/EWS/OData/Users
('sadie@contoso.com')/Events('AAMkAGI3...')",

      ...

      "Subject": "Test new REST API",

      ...

      "Start": "2014-02-13T16:00:00Z",

      "End": "2014-02-13T17:00:00Z",

    }

  ]

}

Tip While MSDN can be great for initial familiarization with the data step, sometimes you want to experiment with the data against live data in real-time. A common technique is to dispatch the request and then watch the response using a debugging proxy such as Fiddler. In fact, if you run the sample code, you can use Fiddler to intercept the request (Access Token and all) – and then use the Composer tab in Fiddler to re-issue the request with minor modifications.

In any case, once you know the JSON shape, you can create a plain C# class with properties that match the names of the JSON fields. In the case of the sample files, this class is defined towards the top of the files. Alternatively, you could also extract it into a separate file, for example, to reuse across your project.

With the data structure defined, all that remains is to de-serialize it. The exact call can differ slightly between service types, depending on how nested the JSON structure is. For Exchange, it looks like this:

Also depending on the service, you may need to do additional post-processing on the results. For example, Exchange does not yet support ordering events on the server, so the sample sorts them locally:

With that, you have successfully accessed data from the Office 365 cloud. From here, the samples display the data in a basic MVC view or a Windows 8.1 page – but for authoring your own code, the sky’s the limit.

Performing a POST request

The sample code produced by the Office 365 API Tools shows only GET requests. Now that you’ve seen how a GET request works, how do you go about authoring a POST request? The answer: Follow the exact same pattern!

To demonstrate that the patterns are in fact the same, I will round off this article with an example of issuing a POST request, such as adding a new contact to Exchange.

As before, we start with looking at the MSDN documentation to see the prototypical way to create a contact. In the Create a contact section, we see:

To create a contact, send a POST request to the Contacts property of the contacts folder with a JSON representation of the new contact in the payload. The following example creates a new contact in the default Contacts folder.

POST https://outlook.office365.com/ews/odata/Me/Contacts HTTP/1.1

Accept: application/json

Content-Type: application/json;odata.metadata=full

Expect: 100-continue

{

  "@odata.type": "#Microsoft.Exchange.Services.OData.Model.Contact",

  "GivenName": "Mara",

  "Surname": "Whitley",

  "EmailAddress1": "mara@fabrikam.com"

}

First, ensure you have appropriate permissions by going back to the Services Manager dialog. For this example, select Exchange, then Configure, and then Have full access to the users’ contacts.

With this done – and having added an entry point (such as a method off of a button click, with appropriate error handling) for invoking the action – you would follow the same steps as before. In broad strokes:

1. Obtain information for communicating with the services.
2. Create a URL corresponding to the ODATA request – and, in the case of a POST request, prepare a data structure for transmitting the data.
3. Prepare the HTTP request.
4. Send the request.
5. Read the response and handle errors.

The biggest difference is in step #3, when preparing the HttpRequestMessage object:

• The request must be a POST rather than a GET.
• The Accept header may need to be adjusted, depending on what the documentation prescribes.
• A Content header must be added.
• The request content must be set to the serialized JSON.

Here is the code in its entirety, for a Windows 8.1 app:

privateclassContact

{

    [JsonProperty("@odata.type")]

    publicstring EntityType { get; set; }

    publicstring GivenName { get; set; }

    publicstring Surname { get; set; }

    publicstring EmailAddress1 { get; set; }

}

privateasyncTask AddContact() {

    // Obtain information for communicating with the service:

    Office365ServiceInfo serviceInfo = await

       Office365ServiceInfo.GetExchangeServiceInfoAsync();

    if (!serviceInfo.HasValidAccessToken)

    {

        return;

    }

    // Create the data structure and the URL corresponding to the ODATA request

    Contact contact = newContact()

    {

        EntityType = "#Microsoft.Exchange.Services.OData.Model.Contact",

        GivenName = "Mara",

        Surname = "Whitley",

        EmailAddress1 = "mara@gabrikam.com"

    };

    string requestUrl = String.Format(CultureInfo.InvariantCulture,

        "{0}/Me/Contacts",

        serviceInfo.ApiEndpoint);

    // Prepare the HTTP request:

    using (HttpClient client = newHttpClient())

    {

        Func<HttpRequestMessage> requestCreator = () =>

        {

            HttpRequestMessage request = newHttpRequestMessage(

                HttpMethod.Post, requestUrl);

            request.Headers.Add("Accept", "application/json;odata.metadata=full");

            request.Content = newStringContent(

                JsonConvert.SerializeObject(contact));

            request.Content.Headers.ContentType =

                newMediaTypeHeaderValue("application/json");

            return request;

        };

        // Send the request using a helper method, which will add an authorization header to the request,

        // and automatically retry with a new token if the existing one has expired.

        using (HttpResponseMessage response = awaitOffice365Helper.SendRequestAsync(

            serviceInfo, client, requestCreator))

        {

            // Read the response and deserialize the data:

            string responseString = await response.Content.ReadAsStringAsync();

            if (!response.IsSuccessStatusCode)

            {

                awaitOffice365Helper.ShowErrorMessageAsync(serviceInfo, responseString);

                return;

            }

            awaitnewMessageDialog("Contact added successfully!", "Success!").ShowAsync();

        }

    }

}

For an MVC project, the code would be largely the same. For real-world applications, though, the one important difference between Windows 8.1 and MVC code is the initial authentication piece. Whereas a Windows 8.1 app will display a dialog box that prompts the user to enter credentials – and which the code can just “await” – an MVC web project must do a redirect to an authentication provider (e.g., redirect to https://login.windows.net/) before getting redirected back to the MVC controller. As such, if the action is state-full (e.g., you’re adding a contact based on information submitted by the user), you will need to ensure that this information is persisted when the login page returns. You can do this in a variety of ways – for example, storing a cookie, encoding the information as a query parameter on the URL passed to serviceInfo.GetAuthorizationUrl, or ensuring that even a blank form requires the user to log in first.

I hope this blog post has helped you to get started with authoring your own Office 365 APIs code. To learn more, I invite you to read the MSDN documentation on Office 365 APIs, and – if you’ve haven’t already – to watch The Office 365 API Tools for Visual Studio video on Channel 9 that touches upon many of the points in this post.

Video: Office 365 API Tools for Visual Studio

- Michael Zlatkovsky, Program Manager on the Office Developer Tools team at Microsoft

Compose apps are available for all our customers on Office 365 and for on-premises customers that have installed the Service Pack 1 for Office 2013 and Exchange 2013.

Check Andrew’s post in the Exchange dev blog and build great apps for Outlook!

Come see us at this year’s //build conference as we take you on a journey through the latest updates and improvements to the Office and SharePoint APIs and Services. We have made huge investments in the developer capabilities for apps for Office and SharePoint, as well as the new Office 365 APIs, which are services that enable external access to Office 365 data.

Don’t miss these Office developer track sessions at //build:

Start your journey with an overview of all the things that are new in Office and SharePoint development with the Build Connected Productivity Apps (2-567) session, then explore the details of the new APIs in the sister sessions Office Power Hour (3-568), SharePoint Power Hour (3-569) and Apps for Outlook Power Hour (3-574). Next, we’ll go through more examples of how SharePoint apps can be created using some of the most widely used 3^rd-party JavaScript libraries in the SharePoint 2013 Apps with AngularJS (2-570) session.

After that, make it easy for users to work together! Take a little detour into the realm of social, and explore how we can extend the social enterprise experience with Building Enterprise Social Apps with Yammer (3-571), and how we can enable data capture and retention through customized experiences by using the new OneNote Services APIs in Captivate Consumers with the OneNote API (3-572).

Finally, we’ll have our friends from the Visual Studio team deep dive into the Cloud Business Apps templates in Visual Studio that enable rapid and agile development of apps for SharePoint with easy connectivity to a variety of external data sources in Developing Office 365 Cloud Business Apps (3-573).

We’re excited to share the new development APIs available for the Office platform. Stop by the Office booth and get your “Working on it…” t-shirt and invaluable reference posters. We’ll also have expert staff on hand to discuss any of the topics in our sessions or answer any of your questions.

Can't wait for the sessions to start learning more? Check out the content on https://dev.office.com.

Follow us on Twitter: @MSDN_Office

See you in San Francisco!

Office Developer Platform Team

Let’s walk through an example. Imagine we are store owners who sell a variety of products, and would like to use SharePoint to store documents related to those products, such as manuals, warranties, sales presentations, and notes. In this example, we will create a Cloud Business App (CBA) that relates our products to documents stored on Office 365 or SharePoint 2013. We will also create screens to allow access to those related documents.

Choose the SharePoint document library

On the SharePoint site, choose a document library to store documents relating to our products. The document library needs to be on the same site and host web as our CBA app when we deploy, so the app has access to the library. We need to create a column to track which product the document belongs to, in this case use the string field Product. While the document library list can have associated content types, the shared column needs to be a list column so it is available for every document.

Figure 1. Choose a Document Library List with a field to store the associated product.

Create tables in Visual Studio

1. Create a new Cloud Business App project (VB or C#). Select our debugging SharePoint site. This site should mirror the document library we have set up on the production site.

   Note: If we had created the Cloud Business App with a previous version of Visual Studio, upgrade the app and update the SharePoint data sources. If the entities were SharePoint Document Libraries they will be ready for use after the update. To upgrade the app, choose the project in Solution Explorer and select "Upgrade Project..."

2. Create a table named Product.

   a. Add a new field ProductName as type string.

   
   Figure 2. Create the products table.

3. Set the Include in Unique Index property for this field so we do not have two products with the same name. Alternatively, we can choose to auto-populate a string field with any unique key, like a GUID, by writing code in the Product_Inserting event. We need a unique field so it can be associated with a column on the document library.

   
   Figure 3. Set the ProductName field property to Include in Unique Index.

Add data source for the document library

1. Add a new data source by choosing the Data Sources node in the Solution Explorer and then choosing SharePoint.
   
   Figure 4. Attach to a SharePoint data source.
2. The SharePoint site is already filled in with the site we used when creating the project. The document library must reside on the same debugging site as our app. When we deploy the app, we need to verify the ProductDocument library exists on the production site. The Publish Wizard will walk us through this. For more information, see the Publish Cloud Business Apps topic in the MSDN library.
   
   Figure 5. Choose to connect to the host web SharePoint site.
3. Depending on our SharePoint site's security, we will be prompted for our credentials when we choose Next. Select Document Libraries to show the document library lists, and select our library. We can now search for the library using the search box and get more information about the library—including the fields and related tables.
   
   Figure 6. Select the document library entity.
4. Choose Finish to add the data source to our project.

Set Relationship between the Product Documents entity and Product

1. In the ProductDocuments entity designer, select Add: Relationship.
2. Set up the relationship as shown in the image below. Each product can have many documents, and the fields we set up earlier are the shared fields.
   
   Figure 7. Set up the relationship to the document library.

Add screens

1. Choose the Client project screen node in the Solution Explorer and choose Add Screen…. In the dialog box, choose the Common Screen Set. The Common Screen set creates the Browse, View, and Add/Edit screens all at once and configures them for the associated data. For screen data, choose the Products table and choose Product ProductDocuments. Choose OK to create the screens.
   
   Figure 8. Create the product common screens.
2. Once the screens are created, observe the view details screen where we included the related documents. There is a tab called Product Documents that has a tile list to containing the documents. The row of the tile list is using the new Document Summary control. There is also an Add command bar button to add or upload new documents. We do not need to make any changes to the screen to get the document functionality.
   
   Figure 9. The Product Documents row uses a Document Summary control.

Running the app

Choose Start Debugging (F5) to start the app. We may need to enter our credentials and we will need to trust the app. When the app loads, it will open to the Product page where we can add a product.

Figure 10. Create a new product.

Once the product is added, select the product to view details and open the Product Documents tab. Choose the Add button to create a new document or upload an existing document. The item named Document is the default template added for new document libraries. We can customize which templates are associated with the library in SharePoint and they will appear in the popup list for easy creation. For now, create a Word document.

Figure 11. Create a new document for the product.

This will open the document in Office Online. Using Office Online, we can rename the document by selecting the name on the menu bar and add our content to the document body.

Figure 12. Use Office Online to rename and edit the new document.

When the edits are complete, just choose the back button to return to the product view page. Office Online auto-saves your document—so we don't need to explicitly save.

Figure 13. Documents for the selected product appear in the tile list.

Selecting the document in the tile list will open the document to allow viewing or editing. It will open the desktop Office client if we have it installed or Office Online if the desktop version is not installed.

Publishing

CBA apps have flexible deployment options. When we run the Publish Wizard, the SharePoint library address will automatically be updated to point at the host web of the publish site. Create the library with the same columns on this site so the app can find it.

Once the app is published, we can access the app on desktop, tablet, or phone and the layout will adjust for the best experience. Here's what it looks like on my phone. Pretty cool!

Figure 14. The document tile list adjusts format for device form factors.

Enable support for legacy browsers

To allow uploading documents on legacy browsers such as Internet Explorer 9, add a NuGet package to the server project. Choose the server project and choose Manage NuGet Packages from the context menu. In the NuGet manager, select Online, search for "web pages," choose Microsoft ASP.NET Web Pages package, and select Install. This package will also install two dependent packages; Accept the license agreement to install the packages.

Figure 15. Install Microsoft ASP.NET Web Pages NuGet Package for legacy browser support.

The Troubleshooting document libraries topic provides more information about enabling legacy browser support.

Summary

The document library support added in the Office Developer Tools for Visual Studio—March 2014 Update provides a way to seamlessly integrate SharePoint document libraries into your applications, without needing to write any code. CBA apps excel at showing a table entity and all of its related documents. Uploading documents, creating new documents from templates or blank Word, Excel, or PowerPoint documents, and editing documents in Office Online or Office desktop are supported.

The How Do I: Incorporate Document Libraries in a Cloud Business App? topic provides a video demonstration about integrating document libraries.

-Ed Smith, Software Development Engineer in Test, Cloud Business Applications Team

The Modern Trend app helps you tell a story based on your Excel data. With a few steps, your data is shown on an interactive trend chart. You can pin the specific data points on the chart, and add descriptions on the canvas. 

Figure 1. Modern Trend app for Excel

Currently, the app can:

• Bind and show your data on a trend chart. 
• Basic interactions on the chart
• Show or hide a line with a legend.
• Pin or unpin a data point.
• Add a description directly on the canvas

If you are interested in developing your own apps for Office and SharePoint, we have great news: we will publish the Modern Trend app source code soon. Stay tuned for more great apps for Office and SharePoint released on the Office Store.

Office 365 APIs enable developers to integrate Office resources (such as calendars, contacts, mail, files, and profile information) directly into their custom applications. For example, with Office 365 APIs, a native WinRT application could add calendar appointments directly into a user's Exchange calendar or send mail on behalf of the user. Similarly, a web application with export functionality could now offer a "Save to OneDrive" option, saving a user's files directly to their SharePoint "My Documents" folder.
 
We are excited about the new scenarios that Office 365 APIs will enable, and are committed to making it easy for every developer to try out these new platform capabilities. With today’s release of our "Office 365 API Tools - Preview" for Visual Studio 2013, adding and using Office 365 APIs is literally a few clicks away. Our tool will:

1. Register and configure your app to consume Office 365 Services.
2. Add helper classes for authentication, caching, and error-handling.
3. Add the necessary libraries (Active Directory Authentication Library and Json.NET) from NuGet, to ensure that the helper classes and sample code work right away.
4. Add sample code that uses Office 365 APIs and demonstrates common patterns and best-practices.

Best of all, our tool:

• Is available for both MVC Web Applications and Windows 8.1 apps. In fact, with the help of our helper classes, the code you'll write for MVC apps can be almost identical to what you'd write in a Windows 8.1 app, and vice-versa.
• Is available for both C# and VB.NET projects.
• Is explicitly designed for adding Office 365 APIs to existing applications, and for adding and configure new services at any time: not just on initial project creation. This means you can try out the new Office 365 APIs on real-world scenarios without needing to start a new project. Better yet, you can start small and then iteratively expand on the Office 365 services that you use.

The walkthrough below will guide you through adding Office 365 APIs to a web application. You can also view a Channel 9 interview/demo, which demonstrates adding Office 365 to an existing Windows 8.1 app.

Video: Adding Exchange and SharePoint to an existing Windows 8.1 app

Getting Started

You can get started by downloading our tool from the Visual Studio Gallery. Close Visual Studio 2013, then choose the .VSIX file and begin setup. A few moments later, the extension will be installed. Now, just open Visual Studio, and follow along in the walkthrough below.
 
Adding Office 365 Services to your project
Once you download and install our tool, open (or create) a project that you want to add Office 365 APIs to. The project must be either an MVC web application or a Windows 8.1 app, targeting .NET Framework 4.5 or 4.5.1. We support both C# and VB.NET projects.
 
In the Solution Explorer, choose the project and then choose Add > Connected Service (Figure 1).

Figure 1. Add Connected Service
 
A Services Manager dialog box will appear (Figure 2). Depending on your project, you may see a number of tabs on the left pane. Choose Office 365 > Sign in.

Figure 2. Services Manager
 
On the sign-in dialog box, enter the username and password for your Office 365 tenant (Figure 3). We recommend that you use your Office 365 Developer Site. Often, this user name will follow the pattern
<your-name>@<tenant-name>.onmicrosoft.com.
If you do not have a developer site, you can get a free Developer Site as part of your MSDN Benefits, or sign up for a free trial. Be aware that the user must be an admin user—but for tenants created as part of an Office 365 Developer Site, this is likely to be the case already.
 

Figure 3. Sign-in dialog box
 
After you're signed in, you will see a list of three services: Active Directory Graph, Exchange, and SharePoint. Initially, the Permissions column to the right of each service will be empty—after all, you have not registered your app to consume any services yet. Choose one of the services (for example, Exchange) from the list and choose OK (Figure 4).

Figure 4. Adding an Office 365 Service
 
Choosing OK will:

• Register the app with Windows Azure Active Directory, which serves as the authentication authority for Office 365 APIs.
• Add the common Office 365 helper classes and the accompanying NuGet libraries.
• Add sample code for the selected service (in the example above, for Exchange).

Because no permissions are configured, the tool will also prompt a dialog box to configure permissions (Figure 5). Note that you can return to this same dialog even after the application has been registered, re-opening the Services Manager dialog box and using the Configure… link to the right of the services grid to modify permissions.

Figure 5. Permissions dialog box. Note that the Make this app available to option is only available for Web applications, not for Windows 8.1 apps.
 
The permissions dialog box is different for each of the services. It is also subtly different for web applications versus native Windows 8.1 apps: The Make this app available to … my tenant only option is only available for Web apps. Native client apps (such as Windows 8.1 apps) don't need this distinction, and can be used on any tenant where the user has granted consent to the app.
 
Choose one or more permissions to proceed with adding the service. For purposes of running the sample code, choose a Read (or higher) permission for each of the services. Be aware that you can choose multiple permissions at the same time: for example, if I want to both read users' mail and send mail on behalf of users, I will need to select both permissions (Figure 6). For other permissions, something like Have full access to the users' calendars already encapsulates the Read users' calendars permission—but when in doubt, choose both permissions.


Figure 6. Selecting multiple permissions within the same category, such as read users' mail, and send mail as a user.
 
After you select the permissions and choose "OK", give our tool a few moments to register your app and add the necessary files and NuGet packages. Now it's time to explore the new files that were added or modified.

Exploring the project structure

Once the Service Manager is done adding files, let's look at the Solution Explorer to see which files got added or modified.
While the project structure between MVC Web Applications and Window 8.1 apps is quite different (see Figures 7 and 8), the pattern of which files get added or modified stays the same. Our tool:

• Adds NuGet packages for Active Directory Authentication Library and Json.NET.
• Adds a set of common helper files (that is, files whose names start with "Office365*", such as "Office365ServiceInfo") that are common across different services. These files get added regardless of whether you chose Exchange, SharePoint, or Active Directory, since they are used for all three cases. We expect that you will keep these files in your project, as they will be valuable for your own apps.
• Adds a set of service-specific sample files (for example, ExchangeSampleController and its accompanying view folder for an MVC web application, or ExchangeSamplePage.xaml and its accompanying code-behind for a Windows 8.1 app). These files are intended to show how each individual service is used, and to provide a compelling experience when you first try to run the service. Once you have ran the sample and copied any relevant functionality into your own code, you can delete these files.
• Modifies Web.config or App.xaml to include the Client ID (and, in the case of web apps the Password) for the app. These values are obtained from the Windows Azure Active Directory, which serves as the authentication authority for Office 365 APIs. Those credentials act as a "link" between the entry in Active Directory and your project within Visual Studio. The Client ID is used both at runtime (for authentication), and by our tool itself (that way, when you return to the Service Manager, we know whether we've already registered your app, and can add or modify services and permissions)

Figure 7. Files added to an MVC Web Application

Figure 8. Files added to a Windows 8.1 App
 
Note: For Windows 8.1 apps, the sample code relies on a set of Windows 8.1 common classes (NavigationHelper, ObservableDictionary, and so on) that are included automatically for non-blank Windows 8.1 apps. The files are found inside of a Common folder at the root of the project. If your project does not contain these files, simply choose Add > New Item > Basic Page (or any other non-Blank page), and add the page to your app. Choose Yes when prompted to add the missing files—this will ensure that the Common folder is added. After that, you can either delete the new page, or keep it for your own use.

Running the sample code

For the Web Application project, choose Debug (or press F5) to run the app. Depending on your web project settings and what file you have open in Visual Studio (our tool automatically opens the controller and the view for the newly-added Office 365 service), your browser may open to the right view by itself. If not, and if it goes to something like "https://localhost:10247/", just append "/<Service-Name>Sample/" to the URL: for example, "https://localhost:10247/ExchangeSample/".
 
Exchange offers several different samples, so going to the Exchange view will give you three buttons to choose from (Figure 9). For this example, I will choose Contacts. In the case of SharePoint and Active Directory, you would be taken directly to the sample.

Figure 9. Running the Exchange sample in a Web application
 
When the app is first run (and on any subsequent closing and re-opening of the browser), the app will have no access tokens or refresh tokens that are necessary for communicating with Office 365 APIs. As such, you will be directed to a login screen (Figure 10). You can enter the same credentials as you used for registering the app—or you can log in as a different user (or even as a different user on a different tenant, if you had enabled the Make this app available to… all tenants in the permissions dialog box (Figure 5)). For tenants other than the ones used to register the app, you will also see a consent dialog box after the login screen.
 

Figure 10. An automatic redirect to log in at https://login.microsoftonline.com
 
After authentication is complete, the browser will redirect you back to your app. You may briefly see something like "https://localhost:10247/Office365Common" in the address bar, along with some long query parameters. The common controller will handle authentication, will cache the access token and refresh token, and then redirect you back to the page where you came from (for example, "https://localhost:10247/ExchangeSample/Contacts"). Now that that page has an access token, it will be able to process the request. For example, you might see something like this (Figure 11).
 

Figure 11. Running the Exchange Contacts sample in a Web application
 
Within a given session, access tokens and refresh tokens are cached—so you will not need to log in again, even when switching among service, until you close and re-open the browser (or until the session expires due to inactivity). To cache the access tokens and refresh tokens beyond the confines of a session, you can persist them more permanently in a database—see the comments in the Office365CommonController class.
 
Windows 8.1 apps:
For Windows 8.1 apps, there is no address bar where you can navigate straight to a particular page. Instead, you will need to add code for an action to take you to the new sample page. For example, you might add a button to your main page.
 
    <Button Content="Exchange Sample" Click="ExchangeSampleButton_Click" />
Then, in the code-behind, simply do:
 
    private void ExchangeSampleButton_Click(object sender, RoutedEventArgs e)
    {
        this.Frame.Navigate(typeof(ExchangeSamplePage));
    }
 
Having done this, choose Debug (or press F5) to run the app. Be aware that you can run either in full-screen mode on the local machine, or in a Simulator (Figure 12).
 
 
Figure 12. Simulator vs. Local Machine dropdown for Windows 8.1 apps
 
When you run the app, choose the button to navigate to the sample page. Again, you will either have a choice of samples for Exchange (I will choose Contacts for the example below), or a single sample for Active Directory and SharePoint. In either case, if you are not already signed in with the app, you will be prompted with a login and consent dialog box (Figures 13 and 14).

Figure 13. Windows 8.1 login dialog box
 

Figure 14. Windows 8.1 consent dialog box
 
Once your app is authenticated and consented, you will see the example functionality (Figure 15).

Figure 15. Running the Exchange Contacts sample in a Windows 8.1 app

What's Next?

This post showed how to obtain the Office 365 API Tools, register an app for Office 365 APIs, and run the sample code. However, this was just the initial setup: the interesting part is once you start authoring your own code to use Office 365 APIs within your Web applications or Windows 8.1 apps.

Stay tuned for a follow-up post where we will explore the sample code that the tool generates, and use that as a building block for writing custom code (for example, to send mail on behalf of a user). For now, take a look at ExchangeSampleController/ExchangeSamplePage (and the analogous Active Directory and SharePoint files) to start looking at the code—and of course, the Office 365 APIs documentation. If you have any questions or feedback, the team is monitoring StackOverflow. Tag your questions [Office365APIs].

~ This post was brought to you by Michael Zlatkovsky, a Program Manager on the Office Developer Tools team at Microsoft.

For the Office Developer Tools – March 2014 Update, we’ve added several new features to Cloud Business Apps (CBAs) that enhance the experience for connecting to enterprise data sources. With a CBA, you can now create a line of business app that:

• Connects to SAP as a first-class data source.
• Allows you to easily integrate custom data with SAP data.

Overview

SAP provides a tool called SAP NetWeaver Gateway that enables the ability to expose SAP application data as an OData service. This OData service can then be used by a CBA to create custom line of business apps. SAP has several sample gateway services you can use for testing and app building. For our example, we will use the SAP Enterprise Procurement Model (EPM) service. Read the SAP documentation to learn how to access to the EPM service and other sample services from SAP. Be aware that these sample services are read-only; however, NetWeaver Gateway does support read-write services.

Our SAP CBA app will be based on a fictional company that sells computers and accessories. This company has several locations worldwide, including a distribution branch that we will be building a line of business app for, named Contoso Shipping Management. Specifically, our app will help the branch manager of Contoso Shipping Management with their daily tasks. The branch manager routinely views product information in the system and adds supplemental production information that is specific to their branch (such as the item location and whether items are out of stock).

Define the data model

Begin by creating a CBA app; in Visual Studio. Choose the Cloud Business App project template under the Office/SharePoint>Apps node.

Attach to SAP Data Source

When you have created the app, attach it to the SAP service.

1. In the Server Explorer, under the Server project, choose the Data Sources>Add Data Source.
2. In the Attach Data Source Wizard, notice the option to select SAP as a data source; after selecting it, choose Next.
   
   Figure 1. Select SAP in the Attach Data Source Wizard
3. On the Enter Connection Information page, enter the URL to SAP EPM service along with the credentials that you received after signing up for access to their test feeds; choose Next.
   Although, it is possible to select None for the authentication type, typically SAP feeds are configured to require authentication (CBA apps currently support connecting to SAP using basic authentication). For more information, see the Authentication section listed at the end of this post.
   
   Figure 2. Enter connection information in the Attach Data Source Wizard
4. On the Choose your Entities page, select the BusinessPartner and Product entities and rename the data source to SAP_EPM_Service; choose Finish.
   
   Figure 3. Select the BusinessPartner and Product entities in the Attach Data Source Wizard

As a result, you will now see the SAP_EPM_Service added as a data source to your Server project including the BusinessPartner and Product entities that you selected.

Figure 4. Entity Designer showing the Product entity

You can use the ctrl + up arrow\down arrow keys to change the order of the properties. It is useful to define the desired order on the entity, so that later when screens are created, the fields on the screen will automatically be added in the same order. For example, you may change the order of the properties so that ProductId, Name, ProductURL, and Description appear first.

One feature of an SAP data source within a CBA is the recognition of certain SAP-specific annotations that can adorn entity properties within the service. Specifically, the annotations that will be recognized by a CBA are those that have the sap:semantics value set to “email”, “tel”, or “url”. The BusinessPartner entity that was selected in the Attach Data Source Wizard happens to have properties that demonstrate all three of these annotations. You can view the semantic annotations by viewing the $metadata from the SAP feed.

https://sapes1.sapdevcenter.com/sap/opu/odata/sap/ZGWSAMPLE_SRV/$metadata

Viewing the BusinessPartner entity in the Entity Designer, observe that the EmailAddress, PhoneNumber, and WebAddress fields have their respective types set to the Email Address, Phone Number, and Web Address business types.

Figure 5. Properties on the BusinessPartner entity have been set to the appropriate business type

Extend the Product Entity Properties

For our line of business app, we need to track some additional product information that is specific to our branch, Contoso Shipping Management. With a CBA, we can easily extend any entity properties by relating data from the internal database of the app with data from an external data source. Furthermore, CBAs support relating data between external data sources, such as SharePoint\Office 365 and SAP.

Add a Relationship

In our example, we would like to track two additional pieces of product information: the item location and whether a product is out of stock. First, we need to add an entity to the internal database of our app that will be used to store this additional information. Second, we will relate this entity to the Product entity (that exists in the SAP data source) using a one-to-one or zero-to-one relationship.

1. To add an entity in the internal database, choose the Data Sources node in the Solution Explorer and select Add Table.
2. Rename the table to ProductDetail and add the following properties: OutOfStock and BackroomLocation. Clear the Required check box for these properties.
   
   Figure 6. The ProductDetail entity
3. Add a relationship between Product and ProductDetail. To do this, open Product in the entity designer and choose the Add: Relationship button.
   
   Figure 7. Adding a relationship
4. In the Add New Relationship dialog box, add a relationship so that each Product can have one ProductDetail (and a ProductDetail must have a Product). Choose OK to close the dialog box.
   
   Figure 8. Configuring the relationship

Create the client screens

Now that the data model is defined, add some screens to the app. While working with the screens, remember that the sample SAP service that we are using is read-only. As a result, the only data that we can edit is the ProductDetail entity because it is stored in the internal database of the app. If instead we were using a read-write SAP service, we would be able to edit all of the information on these screens and automatically save the data back to SAP.

Create the Common Screen Set

1. Choose Screens node in the Solution Explorer and select Add Screen.
2. In the Add New Screen dialog box, select the Common Screen Set template and set the Screen Data to SAP_EPM_Service.ProductCollection. Finally, choose OK to close the dialog box.
   
   Figure 9. Adding a new Common Screen Set
   As a result, you will now see a ProductCollection folder created in the SolutionExplorer that contains three screens: AddEditProduct, BrowseProductCollection, and ViewProduct.
3. Since we defined a one-to-one or zero-to-one relationship between Product and ProductDetail, we need to add code that automatically creates a new ProductDetail entity when the AddEditProduct screen is opened. Choose the AddEditProduct screen from the Solution Explorer, choose the Write Code drop-down in the Screen Designer toolbar and choose created.
   
   Figure 10. Writing "created" code on the AddEditProduct screen
   To create a ProductDetail instance for this Product instance, use the following code.
   

   myapp.AddEditProduct.created = function (screen) {
     if (!screen.Product.ProductDetail) {
       var productDetail = 
         myapp.activeDataWorkspace.ApplicationData.ProductDetails.addNew();
       productDetail.Product = screen.Product;
     }
   };
   

   
   Now when the AddEditProduct screen is opened, a related ProductDetail is created, if one does not already exist.
4. To make the fields that were added from the ProductDetail entity more prevalent on the screen, move the Out of Stock and Backroom Location controls to the top of the right Rows Layout group on this screen. Do the same on the ViewProduct screen as well. Notice that you can also change other appearance properties on controls, such as the font. There are many other properties that you can set on the screen designer to customize the screens.
5. Also on the ViewProduct screen, drag out the Supplier field under our ProductDetail controls to show data from the BusinessPartner entity. This will create a group called Supplier (with properties from the related BusinessPartner entity). For this example, remove all the fields from this group except Email Address, Phone Number, and Web Address. Notice that these controls appear respectively as an Email Viewer, Phone Viewer, and Web Address Viewer (due to the annotations feature described earlier).
   
   Figure 11. Control layout
6. Finally, we want to display the Product images on the ViewProduct screen. First change the Product Pic Url control to be an Image control. To do this, choose the ViewProduct screen in the Solution Explorer, then find the Product Pic Url control on the screen and change it from a Text control to an Image control.
   
   Figure 12. Changing Product Pic Url to an Image control
   Because this SAP service stores the image URLs in a relative format, we need to write more code to set the full URL to the image. With the Product Pic Url control still selected, choose the Edit PostRender Code link in the Properties window.
   
   Figure 13. Properties of the Product Pic Url control
   Add the following code to the PostRender method.
   

   myapp.ViewProduct.ProductPicUrl_postRender =
     function (element, contentItem) {
       contentItem.dataBind("value", function (value) {
         if (value) {
           var totalUri = "https://sapes1.sapdevcenter.com" +
                           contentItem.value;
           setTimeout(function () {
             $("img", element).attr("src", totalUri);
           }, 0);
         }
     });
   };

Run the app

Now, run the app (press F5).

If prompted, enter your SharePoint credentials. When the app starts, also choose Trust It (if prompted).

Notice the following:

• The app home screen allows you to browse Product data from the attached SAP data source.
• When you choose a Product, the detailed Product information is displayed—this includes fields from both the attached SAP data source and the fields defined on the intrinsic ProductDetails entity.
  
  Figure 14. The ViewProduct screen
• On the ViewProduct screen, you can choose the Edit button to open the AddEditProduct screen. Since the particular SAP service that the app is accessing is a read-only service, the fields defined on the SAP Product entity cannot be updated, but those defined on ProductDetail can be. If your app is accessing a read-only service, it is a good idea to remove the Add button on the ViewProduct screen and make the controls on the AddEditProduct screen “view” controls instead of “edit” controls.
  
  Figure 15. The AddEditProduct screen

Additional notes

Authentication

SAP can be configured with a variety of authentication providers. For this release, we support HTTP Basic authentication. Basic authentication is enabled on most NetWeaver Gateway installations, and is easy to configure in both test and production. If you find that CBAs aren’t working with your SAP environment, let us know how we can support you better in the future.

For our debut of SAP support, we wanted to enable a complete read and write scenario with SAP data. Therefore, in addition to basic authentication support, we’ve also implemented the session and CSRF token handling that SAP requires to be able to modify SAP data via the NetWeaver Gateway. This means that your CBAs will be able to write changes back to SAP if your SAP feeds support it. Don’t worry—when you attach to SAP data, we negotiate the SAP sessions and tokens automatically. There is nothing for you to configure.

Non-addressable entities

If your data fails to load and you see a diagnostics error similar to the following, it’s because you’re attempting to navigate directly to an SAP entity that is non-addressable.

Error: The SalesOrderLineItemCollection is not addressable. Please use the Navigation Property via the SalesOrder Collection or Entity.

For example, in the EPM service, the SalesOrderLineItemCollection entity set is marked as non-addressable which is evident in the service root document (for example, https://sapes1.sapdevcenter.com/sap/opu/odata/sap/ZGWSAMPLE_SRV).

The code is not complete and these widgets are “experimental”. In clearer terms, that means:

• The target audience for this release is developers and our primary goal is to collect feedback.
• The code is tested in Office 365. The People Picker works against SharePoint on-premises, but List View does not.
• The code has bugs and functionality limitations. Do not use this code for production scenarios.
• The developer interface will change—future versions may require you to change significant amounts of code.
• The license under which these controls are released grants you specific rights and has certain limitations. Read it carefully.
• We do plan to release these controls for production use soon. Your feedback is critical to identifying areas we should invest.

That said, technically, the controls are actually quite useful—and in the case of the People Picker—almost fully functional. By using them and providing feedback, you can help shape the direction and accelerate the delivery of these—and other widgets in the future.

A note about open source. We have not ruled out providing these controls as open source in the future, but now they still have a proprietary license. This release only includes the binaries. If you have feedback about open source-let us know!

Let’s dive into the widget details.

Widgets overview

First, a quick overview of the philosophy around widgets. The two core principles that we want to deliver on are:

• Bring Office to the Web and provide a delightful user experience. When possible, we want developers to be able to build the same experiences than those provided by our own products without having to spend excessive resources doing so.
• Provide a great developer experience. You should not have to reverse engineer our code to figure out how to use these widgets. The developer interface should be simple, familiar, and flexible to help you develop your scenarios.

Getting the code

The library code that you need for these widgets is part of a NuGet package. Install it and it will give you access to all the files you need to use the experimental widgets. If you have Visual Studio, it is as easy as choosing your project, choosing Manage NuGet Packages and searching for “Office Widgets”. Remember to sort by published date.

https://www.nuget.org/packages/Microsoft.Office.WebWidgets.Experimental/

Figure 1. Office Web Widgets - Experimental NuGet package in Visual Studio

People Picker

This is perhaps the most requested UI widget and hence it was an obvious choice for us to work on. We have seen several apps recreating this control on their own, several questions on our forums, and also requests on our UserVoice site to deliver a People Picker.

While there is already a Client People Picker that you can use in SharePoint hosted apps, you cannot use it in other hosting models. So, we created a pure HTML/JavaScript widget that you can use in apps for SharePoint in all hosting alternatives (SharePoint hosted, provider-hosted, or auto-hosted). The widget doesn’t have a dependency on where you host your pages, but it does require the use of the SharePoint cross-domain library and the SharePoint REST endpoint. It is specifically tailored to pick people from SharePoint.

You include the required files at the top of your HTML page, initialize the runtime, and instantiate the widget using a placeholder div with some special attributes. The following code shows the instantiation.

…  
    <script type="text/javascript">
        // Retrieve context tokens 
        var hostWebUrl = "PUT HOSTWEB URL HERE"
        var appWebUrl = "PUT APPWEB URL HERE";

            // Initialize Controls Runtime
            Office.Controls.Runtime.initialize({
                sharePointHostUrl: hostWebUrl,
                appWebUrl: appWebUrl,
            });
    </script>
  <!-- REFERENCES SECTION END -->
</head>
<body style="height: 100%;" onload="Office.Controls.Runtime.renderAll();">
  <!--MARKUP START-->
    Assigned to:<div id="PeoplePickerSimple" 
                     data-office-control="Office.Controls.PeoplePicker">
                </div>
  <!--MARKUP END-->
</body>

…

Figure 2. People Picker widget

The widget supports various properties and events. For full sample code and documentation, see How to: Use the experimental People Picker widget in apps for SharePoint.

List View

The List View widget attempts to provide the same functionality that the List View on SharePoint pages provides. Be aware that the functionality of the experimental widget is limited. It displays tabular data with some basic sorting and relies on SharePoint pages to view and edit individual items. Instantiation of the widget is similar to the People Picker, you can do it declaratively or imperatively. Since the People Picker example used the declarative syntax, I’ll use the programmatic syntax to instantiate the List View and render a list that is deployed as part of the app.

…
    <script type="text/javascript">
  
        
        function createListView() {
        // Retrieve context tokens 
        var hostWebUrl = "PUT HOSTWEB URL HERE"
        var appWebUrl = "PUT APPWEB URL HERE";

            // Initialize Controls Runtime
            Office.Controls.Runtime.initialize({
                sharePointHostUrl: hostWebUrl,
                appWebUrl: appWebUrl,
            });


            var listUrlValue = appWebUrl + 
                             "/_api/web/lists/getbytitle('CustomersInApp')";
            
            theList= new Office.Controls.ListView(
            document.getElementById("listhere"), {
                listUrl: listUrlValue 
            }
          );

        }



    </script>
…

Figure 3. List View widget

To see the full code sample and documentation for List View, see How to: Use the experimental Desktop List View widget in apps for SharePoint.

Runtime initialization and connectivity with SharePoint

Both widgets have a dependency on the SharePoint cross-domain library that in turn means that you must have an app web for things to work, even if you are not deploying any assets on SharePoint. To satisfy this requirement, use a dummy asset, for example, an empty web page hosted on SharePoint that is deployed as part of your SharePoint app package. To learn how the cross-domain library works, see How to: Access SharePoint 2013 data from apps using the cross-domain library.

To initialize the controls library as shown in the code sample, pass the app web and host web URLs to the runtime. If you get these parameters as part of your query string (for example, because you are passing them using context tokens), then you can initialize the runtime with an empty object and the code will attempt to get the parameters from the query string directly.

// Initialize with an empty object and the code 
// will attempt to get the tokens from the
// querystring directly.
Office.Controls.Runtime.initialize({});

Using these widgets in apps for Office

In this first iteration, widgets are designed with apps for SharePoint in mind, but they can also be used in apps for Office if you are using SharePoint as a backend. This scenario requires you to have both, an app for SharePoint deployed and an app for Office that in turn connects to the app for SharePoint.

Feedback

Fantastic, you reached the most important part of this post—how you can give us feedback. We will be monitoring comments on this blog post, but you can also send us feedback on UserVoice using the Office Web Widgets category. Some key areas where we want your feedback:

• Interface and syntax
  • What do you think about the interface (for example, widget instantiation, manipulation)? Does it make sense? Is it easy? Is it difficult?
  • Do the properties and event names make sense? Are they too long? Are they too short? Are they clear or confusing?
  • Do you like the name “Office Web Widgets” or would you prefer something else?
• Functionality
  • Does it meet your app needs?
  • Are properties/events missing?
  • Did you find any critical bugs?
  • Do you consider any of the missing functionality an adoption blocker? What would be you would like us enable/fix before you could use the controls in your production apps?
• Form factors
  • What form factors and input methods do you see your customers using these widgets on the most? Currently, they are optimized for keyboard and mouse.
• Other frameworks
  • Would you like controls for a particular framework (for example, AngularJS)?
  • Do widgets conflict with your existing code or frameworks you already use?
• More controls
  • o What other widgets would you like to see?

We look forward to hearing from you: download the code, look at the docs and give us feedback.

Happy coding!