How To : Manually add common consent to your Office 365 APIs Preview app

 

Learn how to manually add Microsoft Azure Active Directory common consent to your ASP.NET application so that it can access secured services.

Prerelease content
The features and APIs documented in this article are in preview and are subject to change. Do not use them in production.

In this article, you’ll learn how to build a web application hosted on an Azure website that uses the OneDrive for Business API to access secured folders and files.

You can easily set up access to the OneDrive for Business using the Office 365 API Preview Tools for Visual Studio 2013. If you’re not using the tools, you’ll need to manually set up your app in your development environment, register your app with Microsoft Azure Active Directory, write code to handle tokens, and write the code to work with the OneDrive for Business resources. All these steps are described in this article.

Note
This article covers OneDrive for Business apps, but the same steps apply to apps that access any other secured resource.

Get set up to add common consent

---

Before you manually add common consent to your app, make sure that you have the following:

• An Office 365 account. If you don’t have one, you can sign up for an Office 365 developer site.
• Visual Studio 2012 or Visual Studio 2013.

  Note
  The Office 365 API Preview Tools for Visual Studio 2013, which simplify development, are available for Visual Studio 2013 only.

• A test account to use in your application.

We also recommend that you familiarize yourself with the Authorization Code Grant Flow. This will help you understand the authentication process that takes place in the background between your application, Azure AD, and the Office 365 resource so that you can better troubleshoot as you develop.

Create an organizational user account in Azure AD

---

If you’ve already created an account within your Azure tenancy, you can use that account. Otherwise, you will have to create a new organizational user account to use in this sample.

To create an organizational user account

1. Go to https://manage.windowsazure.com/.
2. Choose the Active Directory icon on the left side in the Azure portal.
3. Choose Add a user.
4. Fill in the user name.
5. Move to the next screen.
6. Create a user profile. To do this:
   1. Enter a first and last name.
   2. Enter a display name.
   3. Set the Role to Global Administrator.
   4. After you set the role you will be asked for an alternate email address. You can enter the email address that you used to create the subscription, or a different one.
7. Move to the next screen.
8. Choose create.
9. A temporary password is generated. You will use this to sign in later. You will have to change it at that time.
10. Choose the check mark to finish creating the organizational user account.

Create the Visual Studio project

---

The next step is to create the actual app that contains the UI and code needed to work with the OneDrive for Business REST APIs to list the folders and files in the user’s OneDrive.

To create the Visual Studio project

1. Open Visual Studio 2013 and create a new ASP.NET Web Application project. Name the application Get_Stats. Choose OK.
2. Choose the MVC template and choose the Change Authentication button. Select the Organization Accounts option. This will display additional options for authentication.
3. Choose Cloud – Single Organization.
4. Specify the domain of your Azure AD tenancy.
5. Set the Access Level to Single Sign On, Read directory data.

   Under More Options, you will see the App ID URI is set automatically.

6. Choose OK to continue. This brings up a dialog box to authenticate.

   Note

   If you receive an invalid domain name error, you might need to implement a workaround by substituting a real domain name, such as *.onmicrosoft.com, from another Azure subscription that you have. When you complete the Visual Studio new project dialog box, Visual Studio creates a temporary app registration entry on the domain that you specify. You can delete that entry later. As part of the workaround, you need to adjust the web.config settings and manually register the web app in the correct Azure AD domain.

7. Enter the credentials of the user you created earlier.
8. Choose OK to finish creating the new project. Visual Studio will automatically register the new web app in the Azure AD tenant you specified.
9. Run the Visual Studio project, and sign on using the test account you created earlier. After the project is running, you can verify that single-sign on is working because the test account user name is displayed in the upper right corner of the web app.

Manually register your web app in Azure AD

---

1. Log on with your Azure account.
2. In the left navigation, choose Active Directory. Your directory will be listed.
3. Choose your directory.
4. In the top navigation, choose Applications.
5. On the Active Directory tab, choose Applications.
6. Add a new application in your Office 365 domain (created at Office 365 sign up) by choosing the “ADD” icon at the bottom of the portal screen. This will bring up a dialog box to tell Azure about your application.
7. Choose Add an application my organization is developing.
8. For the name of the application, enter Get Stats. For the Type, leave Web application and/or Web API. Then choose the arrow to move to step 2.
9. For the Sign-On URL, enter the localhost URL from your Get_Stats Visual Studio project. To find the URL:
   1. Open your project in Visual Studio.
   2. In Solution Explorer, choose the Get_Status project.
   3. From the Properties window, copy the SSL URL value.
   4. Enter an App ID URI. Because the ID must be unique, it’s a good idea to choose a name that is similar to the app name. For example, you can use your Sign-on URL with your app name, such as https://locahost:44044/Get_Stats.
   5. Choose the checkmark to finish adding the application. You will be notified that the application was added successfully.

Configure your app to communicate with Azure AD

---

1. Copy the APP ID URI to the clipboard.
2. In your Get_Stats Visual Studio project, open the web.config file.
3. Locate the ida:Realm key and paste the APP ID URI for the value.
4. Locate the ida:AudienceUri key and paste the same APP ID URI for the value.
5. Locate the audienceUris element and paste the same APP ID URI for the add element’s value.
6. Locate the wsFederation element, and paste the same APP ID URI for the realm.
7. In the Azure Portal, copy the federation metadata document URL to the clipboard.
8. In the web.config file, locate the ida:FederationMetadataLocation key, and paste the URL for the value.
9. In the Azure Portal, choose the View Endpoints icon at the bottom.
10. Copy the WS-Federation Sign-On Endpoint to the clipboard.
11. In the web.config file, locate the wsFederation element and paste the endpoint value for the issuer.
12. Save your changes and run the project. You will be prompted to sign on. Sign on by using the test account you created earlier. You should see your account user name displayed in the upper right corner of the web app.

Get an application key

---

Next, you need to generate a key that you can use to identify your application for access tokens.

To get an application key for your app

1. In the Azure Portal, select the Get_Stats application in the directory.
2. Choose the Configure command and then locate the keys section.
3. In the Select duration drop-down box, choose 1 year.
4. Choose Save.

   The key value is displayed.

   Note
   This is the only time that the key is displayed.

5. In Visual Studio, open the Get_Stats project, and open the web.config file.
6. Locate the ida:Password element, and paste the key value for the value. Now your project will always send the correct password when it is requested.
7. Save all files.

Configure API permissions

---

You need to specify which web APIs your web app needs access to, and what level of access it needs. This determines what scopes and permissions are requested on the consent form for your web app that is displayed for users and admins.

To configure API permissions

1. In the Azure Portal, select the Get Status application in the directory.
2. From the top navigation, choose Configure. This displays all the configuration properties.
3. At the bottom is a web apis section. Notice that your web app has already been granted access to Azure AD.
4. Choose Office365 SharePoint Online API.
5. Choose Delegated Permissions and select Read items in all site collections.

   Note
   The options activate when you move over them.

6. Choose Save to save these changes. Your web app will now request these permissions.

   You can also manage permissions by using a manifest. You can download your manifest file by choosing Manage Manifest.

Add the GraphHelper project to your solution

---

The easiest way to call graph APIs in Azure AD is to use the Graph API Helper Library. The following instructions show how to include the GraphHelper project into your Get_Stats solution.

To configure the Graph API Helper Library

1. Download the Azure AD Graph API Helper Library.
2. Copy the C# folder from the Graph API Helper Library to your project folder (i.e. \Projects\Get_Stats\C#.)
3. Open the Get_Stats solution in Visual Studio.
4. In the Solution Explorer, choose the Get-Stats solution and choose Add Existing Project.
5. Go to the C# folder you copied, and open the WindowsAzure.AD.Graph.2013_04_05 folder.
6. Select the Microsoft.WindowsAzure.ActiveDirectory.GraphHelper project and choose Open.
7. If you are prompted with a security warning about adding the project, choose OK to indicate that you trust the project.
8. Choose the Get_Stats project References folder and then choose Add Reference.
9. In the Reference Manager dialog box, select Extensions and then select the Microsoft.Data.OData version 5.6.0.0 assembly and the Microsoft.Data.Services.Client version 5.6.0.0 assembly.
10. In the same Reference Manager dialog box, expand the Solution menu on the left, and then select the checkbox for the Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.
11. Choose OK to add the references to your project.
12. Add the following using directives to the top of HomeController.cs.
    using Microsoft.WindowsAzure.ActiveDirectory;
    using Microsoft.WindowsAzure.ActiveDirectory.GraphHelper;
    using System.Data.Services.Client;
    
    

13. Save all files.

Add code to manage tokens and requests

---

Because your web app accesses multiple workloads, you need to write some code to obtain tokens. It’s best to place this code in some helper methods that can be called when needed.Note that the Office 365 API Preview tools will handle all this coding for you.

Your custom code handles the following scenarios:

• Obtaining an authentication code
• Using the authentication code to obtain an access token and a multiple resource refresh token
• Using the multiple resource refresh token to obtain a new access token for a new workload

To create code to manage tokens and requests

1. Open your Visual Studio project for Get_Stats.
2. Open the HomeController.cs file.
3. Create a new method named Stats by using the following code.
   public ActionResult Stats()
   {
       var authorizationEndpoint = "https://login.windows.net/"; // The oauth2 endpoint.
       var resource = "https://graph.windows.net"; // Request access to the AD graph resource.
       var redirectURI = ""; // The URL where the authorization code is sent on redirect.
   
       // Create a request for an authorization code.
       string authorizationUrl = string.Format("{1}common/oauth2/authorize?&response_type=code&client_id={2}&resource={3}&redirect_uri={4}",
              authorizationEndpoint,
              ClaimsPrincipal.Current.FindFirst(TenantIdClaimType).Value,
              AppPrincipalId,
              resource,
              redirectURI);
   
   

4. The Stats method constructs a request for an authorization code and sends the request to the Oauth2 endpoint. If successful, the redirect returns to the specified CatchCode URL. Next, create a method to handle the redirect to CatchCode.
   public ActionResult CatchCode(string code)
   {}
   
   

5. Acquire the access token by using the app credentials and the authorization code. Use your project’s correct port number in the following code.
   //  Replace the following port with the correct port number from your own project.
       var appRedirect = "https://localhost:44307/Home/CatchCode";
   
   //  Create an authentication context.
       AuthenticationContext ac = new AuthenticationContext(string.Format("https://login.windows.net/{0}",
       ClaimsPrincipal.Current.FindFirst(TenantIdClaimType).Value));
   
   //  Create a client credential based on the application ID and secret.
   ClientCredential clcred = new ClientCredential(AppPrincipalId, AppKey);
   
   //  Use the authorization code to acquire an access token.
       var arAD = ac.AcquireTokenByAuthorizationCode(code, new Uri(appRedirect), clcred);
   
   

6. Next use the access token to call the Graph API and get the list of users for the Office 365 tenant. Paste the list into the following code.
   //  Convert token to the ADToken so you can use it in the graphhelper project.
   
       AADJWTToken token = new AADJWTToken();
       token.AccessToken = arAD.AccessToken; 
   
   //  Initialize a graphService instance by using the token acquired in the previous step.
   
       Microsoft.WindowsAzure.ActiveDirectory.DirectoryDataService graphService = new DirectoryDataService("09f9ea02-9be8-4597-86b9-32935a17723e", token);
       graphService.BaseUri = new Uri("https://graph.windows.net/09f9ea02-9be8-4597-86b9-32935a17723e");
   
   //  Get the list of all users.
   
       var users = graphService.users;
       QueryOperationResponse<Microsoft.WindowsAzure.ActiveDirectory.User> response;
       response = users.Execute() as QueryOperationResponse<Microsoft.WindowsAzure.ActiveDirectory.User>;
       List<Microsoft.WindowsAzure.ActiveDirectory.User> userList = response.ToList();
       ViewBag.userList = userList; 
   
   

7. Now you need to call Microsoft OneDrive for Business, and this requires a new access token. Verify that the current token is a multiple resource refresh token, and then use it to obtain a new token. Paste the token into the following code.
   //  You need a new access token for new workload. Check to determine whether you have the MRRT.
   
       if (arAD.IsMultipleResourceRefreshToken)
       {
           // This is an MRRT so use it to request an access token for SharePoint.
           AuthenticationResult arSP = ac.AcquireTokenByRefreshToken(arAD.RefreshToken, AppPrincipalId, clcred, "https://imgeeky.spo.com/");
       }
   
   

8. Finally, call Microsoft OneDrive for Business to get a list of files in the Shared with Everyone folder. Paste the list into the following code and replace any placeholders with correct values.
   //  Now make a call to get a list of all files in a folder. 
   //  Replace placeholders in the following string with correct values for your domain and user name. 
       var skyGetAllFilesCommand = "https://YourO365Domain-my.spo.com/personal/YourUserName_YourO365domain_spo_com/_api/web/GetFolderByServerRelativeUrl('/personal/YourUserName_YourO365domain_spo_com/Documents/Shared%20with%20Everyone')/Files";
   
       HttpWebRequest request = (HttpWebRequest)WebRequest.Create(skyGetAllFilesCommand);
       request.Method = "GET";
   
       WebResponse wr = request.GetResponse();
   
       ViewBag.test = wr.ToString();
   
       return View(); 
   
   

9. Create a view for the CatchCode method. In Solution Explorer, expand the Views folder and choose Home, and then choose Add View.
10. Enter CatchCode as the name of the new view, and choose Add.
11. Paste the following HTML to render the users and Microsoft OneDrive for Business response from the CatchCode method.
    @{
        ViewBag.Title = "CatchCode";
    }
    <h2>Users</h2>
    <ul id="users">
    
        @foreach (var user in ViewBag.userList)
        {
            <li>@user.displayName</li>
        }
    </ul>
    <h2>OneDrive for Business Response</h2>
    <p>@ViewBag.skyResponse</p>
    
    

12. Build and run the solution. Verify that you get a list of users, and that you get an XML response from the OneDrive for Business method call. To change the XML response, add files to the OneDrive for Business Share with Everyone folder.

New Office 365 API VS.Net Add-In exposes Javascript Client model

You can now access the Office 365 APIs using libraries available for .NET and JavaScript. These libraries make it easier to interact with the REST APIs from the device or platform of your choice.

 

Office365

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.

Client libraries

Office 365 provides REST-based APIs that enable developers to access Office resources such as calendar, contacts, mail, files, and more.

The client libraries will let you:

• Perform authentication and discovery
• Use the Mail, Calendar and Contacts API
• Use the My Files and Sites API (currently .NET only, with JavaScript coming soon)
• Use the Users and Groups API

 

You can program directly against the REST APIs to interact with Office 365, but it requires you to write and maintain code around managing authentication tokens, constructing the right urls and queries for the API you wanted to access, and perform other tasks.

By using client libraries to access the Office 365 APIs, you can reduce the complexity of the code you need to write to access the APIs. We’re providing these libraries for .NET as well as JavaScript developers for use with the just-announced multi-device hybrid applications.

Here are some examples of how easy it is access the Office 365 APIs using these libraries.

.NET C# code to authenticate and get upcoming events from your Office 365 calendar:

// Shows UI to authenticate
Authenticator = newAuthenticator();
AuthenticationInfo result = await authenticator.AuthenticateAsync("https://outlook.office365.com");


The AuthenticateAsync method will prompt for a username and password and authenticate against the specified resource url, like outlook.office365.com in this case. Once you have the authentication information, you can create a client object that serves as the base for accessing all the APIs for Exchange:


// Create a client object
ExchangeClient client =
newExchangeClient(newUri("https://outlook.office365.com/ews/odata"),
result.GetAccessToken);


Because we’re using .NET here, we get to take advantage of the native language capabilities, like LINQ, so querying the Office 365 calendar is as simple as writing a LINQ query and executing it:

// Obtain calendar event data
var eventsResults = await (from i in client.Me.Events
where i.End >= DateTimeOffset.UtcNow
select i).Take(10).ExecuteAsync();


With just those four lines of code you can start making calls to the Office 365 APIs!

We wanted to make sure that you can reach multiple device and service platforms with a consistent API, so the client libraries are portable .NET libraries, which means they also work with Android and iOS devices through Xamarin. Because authentication needs to display a UI that is different on the various platforms, we also provide platform-specific authentication libraries, which can then be used with the portable ones to provide an end-to-end experience.

For developers creating multi-device hybrid applications that target multiple device platforms through JavaScript, we also have JavaScript versions of these libraries that provide a similar experience while adopting JavaScript’s patterns and practices, such as using the promises pattern instead of await.

 

Here is the same example to authenticate and get calendar events in JavaScript:

var authContext = new O365Auth.Context();
authContext.getIdToken('https://outlook.office365.com/')
.then((function (token) {
// authentication succeeded
var client = new Exchange.Client('https://outlook.office365.com/ews/odata',
token.getAccessTokenFn('https://outlook.office365.com'));
client.me.calendar.events.getEvents().fetch()
.then(function (events) {
// get currentPage of calendar events
var myevents = events.currentPage;
}, function (reason) {
// handle error
});
}).bind(this), function (reason) {
// authentication failed
});

The flow to authenticate and create a client object is similar across .NET and JavaScript, but you’re doing it in a way that should be natural to the language.

Along with the JavaScript files for these libraries, we are also including the TypeScript type definition (.d.ts)—in case you choose to develop your apps in TypeScript.

As you get started using these libraries, there are a few things to keep in mind. This is a very early preview release of the libraries that is meant to prove out the concept and get feedback on it. The libraries do not currently cover all the APIs provided by the services and some of the APIs in the library may not work. The APIs in the libraries themselves will definitely change in future updates.

Note that while we tend to call these “client” libraries, these also work with .NET server technologies like Asp.Net Web Forms and MVC, so you really get to target the breadth of the .NET platform.

 

Tooling updates

With today’s update of our Office 365 API Tools for Visual Studio 2013, the tool displays the available Office 365 services that you can add to your project. Once you’ve signed in with your Office 365 credentials, adding a service to your project is as easy as selecting the appropriate service and applying the required permissions.

Once you submit the changes, Visual Studio performs the following:

1. Registers an application (if there isn’t an application registered yet) in Microsoft Azure Active Directory to consume Office 365 services.
2. Adds the following to the project:
   1. Client libraries from Nuget for the configured services.
   2. Sample code files that use the Client Libraries.

Project types supported

With the broad reach of the client libraries, the Office 365 API tool is now available for a variety of project types (client, desktop, and web) in Visual Studio. Here’s are all the project types supported with the May update:

• .NET Windows Store Apps
• Windows Forms Application
• WPF Application
• ASP.NET MVC Web Application
• ASP.NET Web Forms Application
• Xamarin Android and iOS Applications
• Multi-device hybrid apps

Installing the latest update

To install the latest update, you can either:

• Check for updates within Visual Studio. To do so, follow these steps:
  1. In Visual Studio menu, click Tools->Extensions and Updates->Updates.
  2. You should see the update available for Office 365 API Tools.
  3. Click Update to update to the latest version.

–OR–

• Download the extension and install it manually.

Once you’ve updated, you can invoke the Office 365 API tool as usual, that is, by going to your project node in the Solution Explorer and selecting Add->Connected Service from the context menu.

Looking forward to seeing your Apps out there when I visit the stores!!

---

MSDN references

Check also new SharePoint Online Solution Pack for branding and provisioning. This package contains also some examples, which originates from the AMS reference implementations. Here’s the direct links for the Solution Pack

• Download the package
• MSDN Code Gallery (9 samples)

You can find introduction to this SharePoint Online Solution Pack for branding and provisioning from following blog post – Introduction to SharePoint Online Solution Pack for branding and provisioning released.

How To : Use the Content Query Web Part for SharePoint 2013 Search

Meeting client requirements with SharePoint often involves aggregating items somehow – often we want to display things like “all the overdue tasks across all finance sites”, or “navigation links to all of the subsites of this area” or “related items (e.g. tagged with the same term)” and so on. In SharePoint 2010 there have been two main ways of accomplishing this:

• Content Query web part
• Custom solution built on SPSiteDataQuery (site collection-scoped), SPQuery (list-scoped) or search API

To a lesser extent, using the search web parts as part of a custom solution may also have been an option. Regardless, it was common to need custom code to meet such requirements. Maybe we needed to add paging to the results, or we needed to use some value obtained dynamically through code (e.g. from the current site/current page/current user/something else) – several Codeplex solutions arose from this gap, and lots of lines of code were written.

SharePoint 2013 presents the Content Search web part as a new option – it’s capabilities mean that simply using the web part (with some front-end work to meet look and feel requirements) will meet many needs, without use of custom code. If you’re a developer, the following screenshot should give you a clue as to why code won’t be required too often (with one of my favorite options highlighted):

It’s incredibly powerful, and it’s a good idea to understand what it can do.

Understanding the deal with search-based solutions

As the name suggests, the Content Search web part is powered by SharePoint’s search function. As such, there are the following considerations:

• The CSWP can be configured to “see” items anywhere in SharePoint (potential advantage)
  • In contrast, the CQWP and related SPSiteDataQuery can only search within the current site collection – the site collection “boundary” is a factor
• Results shown are not guaranteed to be 100% up-to-date (potential disadvantage) 
  • Since a search crawl has to run before any content changes will be shown in search results (remember this can include titles, summaries, images and so on for pages/documents), if a user creates/edits an item it will not be shown immediately. This can be a critical point.
  • Furthermore, my understanding from a FAST engineer is that in SharePoint 2013 there is no longer any means of pushing a document directly into the search index – in previous FAST incarnations including FAST for SharePoint 2010, there were options such as docpush.exe for “proactively” add an item to the index, rather than waiting for the next search crawl.
  • That said, it should be possible to obtain much lower indexing latencies in SharePoint 2013 via the “Continuous Crawl’” capability. In most deployments, my guess would be that changes would be reflected within a few minutes at most if this is enabled (where previously you may have had an incremental crawl scheduled every 15, 30 or 60 minutes for a SharePoint sites content source.

Summary – if the functionality you are creating needs fully up-to-date results (e.g. a user has created/edited something and it needs to be immediately reflected in the site) then you will probably need to stick with the original approaches (i.e. a query-based rather than search-based solution).

Terminology – new concepts in SharePoint 2013 search

So if we’re going to build solutions built on SP2013 search, we need to have a basic understanding of some concepts – we’ll run into these time and time again:

Concept	My quick definition
Result Source	Like a search ‘scope’ in SP2007/SP2010, but on steroids. Rules are specified to say what the scope consists of – e.g. DOCUMENTS in my TEAM SITES area (constraining on content type and path in this example). Created centrally, or at the web level. Result Sources can be used in just about any search-related functionality, including the Content Search web part.
Query Rule	Like a ‘best bet’ on steroids. Ability to do specially formatted results at top of results list (e.g.Promoted Result) for highly-recommended content. In addition to Promoted Result, we can also do a Result Block (example could be a block of 5 image results within main list of text links). Another option is to Change the Ranked Results – i.e. put something at the top, promoteor demote something by 1-10 (previously known as a ‘boost’ in FAST) LOTS of flexibility in matching the user’s query, including regular expressions and matching terms in the Managed Metadata store.
Display Templates	A Display Template is a JavaScript template (similar to jQuery templates) which controls formatting – in the case of the CSWP, this effectively replaces the use of XSL for look and feel. There is a separate template to pick for the overall control and formatting of an individualitem. The .js files for the templates are stored in the ‘Content Web Parts’ subfolder of the Master Page Gallery. Side note – in the context of a search results page (rather than CSWP), a Display Template is associated with a Result Type (e.g. Word doc, wiki page, PowerPoint file etc.) and so we have granular control over how each is displayed (and when). Extremely cool.

So, lots of flexibility in the search infrastructure. Let’s see some of this in the context of the Content Search web part.

Configuring the Content Search web part

There are two main aspects to this:

• Displaying the right items (Search Criteria)
• Look and feel (Display Templates)

In terms of the search criteria, there is enormous flexibility in what the CSWP – and the underlying search capability – can do. For one thing, it’s possible to either directly configure the query entirely in the properties of this web part instance (e.g. show me all documents which meet criteria X), and/or start from a pre-existing Result Source to do some of the filtering. Combining the approaches will be fairly common – an example could be “search only on wiki pages” (an OOTB Result Source) but only show items tagged with X (this defined directly in the CSWP properties).

Interestingly, configuring a centralized Result Source and a Content Search web part on a page are very similar, even though it would seem some sort of “reusable scope” and a web part are very different things in SharePoint. The overlap comes because underneath both there is a search query which does the work of isolating the desired results – indeed, as we’ll see later the same “Query Builder” UI is used in both places (with a couple of minor differences). So, if you’ve learnt how to configure a CSWP you’ve essentially also learned how to create  a custom Result Source.

 

Configuring the web part

The first thing to understand is that the Content Search web part appears in different guises in the web part gallery. The ‘main’ web part is in the ‘Content Rollup’ category:

But there are also many pre-configured versions available, each of which finds a specific type of content. This is great for end-users who don’t necessarily think in terms of needing a ‘Content Search’ web part:

And just to prove the point, the web parts above correspond to the following .webpart definition files in the Web Part Gallery:

Once the web part has been added to the page, it can be configured by it’s tool pane. The main configuration item is the query to use, and this can be started by clicking the ‘Change query’ button:

This opens the “’Build Your Query” dialog – this has tabs labeled BASICS, REFINERS, SORTING, SETTINGS and TEST. This thing is known (unsurprisingly) as the Query Builder – what you might not realize, is that it’s used in several places in SharePoint 2013:

• Configuring a Content Search web part (obviously)
• Creating a Result Source (specifically in the Query Transform section)
• Configuring a Search Results web part

There are some differences – for example, when configuring a Search Results web part there is no SORTING tab because this will be handled in the Result Source or the query. I’m going to talk about things from the perspective of the Content Search web part, but will call out any differences for the other usages – so hopefully by learning the CSWP, you also get to learn 75% of the search infrastructure.

BASICS tab – Quick Mode

Although the first tab is labeled ‘BASICS’, I’d say it’s actually the most involved – this is where the query itself is configured, and there is a ‘Quick Mode’ and ‘Advanced Mode’. You’ll also notice that – and let me just say I’d personally be willing to give the Product Manager for this feature A BIG HUG for this – that there’s a “live” results preview pane, permanently visible on the right-hand side of the Query Builder. This shows the first 10 results which would display from running the currently configured search against the current index, without the need to save the web part after each change:

Note that if you create your own query, then this preview pane is only able to show results when you are on the TEST tab. And we’ll talk about that towards the end.

Let’s now walk through the various configuration steps in here.

Select a query

In Quick Mode, the dropdown contains the Result Sources (see my definition above if you’ve forgotten already :)) which come out-of-the-box with SharePoint 2013 – one of these may provide a good foundation for what you need:

As you select a Result Source from the dropdown, other options may become available lower down. So if I want to find items matching a specific content type, I get this:

In fact, this option to restrict by content type appears for many of the pre-defined Result Sources, not just “Items matching a content type” – which makes sense, because it’s a common thing to include as a filter. Similarly, “Items matching a tag” and several other queries give this interface for selecting a tag to filter on:

And, happy days, if I specify the tag by typing one I get auto-complete to help me pick the term – this is a fully-fledged Managed Metadata input field. Consequently there’s also full validation of the terms you type-in (though this takes a few seconds to show), so if an author accidentally enters something which isn’t a known term, he/she should spot the mistake immediately:

Consider also that those middle options of using the navigation term associated with the current page is exactly what’s needed to build many types of ‘related items’ functionality – again, no code needed now.

Restrict results by app

In the next section, I can restrict the scope of the results to a particular location (e.g. the current site). This enables me to get something like the Content Query web part behavior of only searching within the current site collection if needed – because although we now have the power, it won’t always make sense to go across the entire farm 🙂

Add additional filters

In the next section I can supplement the query with any valid query text, e.g. a property filter. In this example, I’m adding a filter to only present items which werecreated by the current user:

Sort results

When we scope our query to a pre-defined Result Source (as we are here in the CSWP ‘Quick Mode’), then sorting is usually pre-defined at that level. The CSWP does give us the opportunity to override sorting based on based on some popularity ranking models (around most viewed/most clicked) instead though – expect proper wording to appear in this dropdown in the RTM version, but you get the idea: 

So what happens if none of the options presented so far do what you want? An example could be wanting to use an existing Result Source (e.g. ‘wiki pages’) but sort on Last Modified in descending order. Obviously the dropdown above does not allow that. We could create a custom Result Source and implement the query/sorting there, but that only really makes sense if we expect it to be re-used in multiple places.

In these cases, we can click into Advanced Mode (still on the BASICS tab).

BASICS tab – Advanced Mode

In Advanced Mode you basically get to specify the full query text yourself. In my mind, this is like building a solution with the search API in SP2007/SP2010 – I saw many custom solutions (and built several myself) which used the FullTextSqlQuery or KeywordQuery classes to find the right items. SharePoint 2013 makes it much easier to have this full control whilst still piggybacking onto the out-of-the-box web parts – meaning less work and more productivity.

When switching to the Advanced Mode, a couple of things become available:

• A SORTING tab (details later)
• Controls to help you build the query (which you’d previously do essentially by hand in earlier versions), with ‘Keyword filter’ and ‘Property filter’ options. These can be combined as you like, and the resulting query text appears in the textbox at the bottom:

Avoid custom code by using tokens

There are many tokens which can be used when building a query in this way – often you might want to pass something into the query, such as a URL (querystring) parameter, the value in a particular field on the page, and so on. Being able to do this unlocks a huge range of possibilities for building solutions. This is where the first image in this article comes from – here’s a reminder:

In summary, when using the Advanced Mode of the query builder you should be able to target just about any content in your SharePoint environment.

SORTING tab (Advanced Mode only)

In SharePoint 2010 Enterprise Search, you could only sort by relevance/rank (the normal search engine approach) or date. FAST for SharePoint 2010 had more options (you could sort by a Managed Property). In SharePoint 2013, frankly the sort options alone are enough to blow your mind 🙂  If you don’t need anything specific around sorting then you can skip this bit, but if you do then here are your options:

First you can sort by way more things than just rank and date:

One thing to note there – I’m unclear as to what makes it into that ‘Sort by’ list and what does not. It’s not Managed Properties as far as I can tell, so although the list is long many options may not be hugely useful. Still, better than before.

Usefully, you can now do multi-level sorting (sort by this, then by that). The ‘Add sort level’ link in the image above adds another row, allowing me to do things like sorting by URL depth (so items higher up in the site hierarchy show at the top), and then by rank (that makes sense, because there’ll be lots of items at the same URL depth so I do need two levels of sorting):

Note that effectively what I’m doing here is building some sort of custom ranking model. This works great if I need something very specific on sorting, but also note SharePoint 2013 comes with several ranking models – the next section allows me to pick from these if I’ve left the ‘Sort by’ dropdown on ‘Rank’, unlike in the image above. This is because all these options are effectively different forms of rank – most are around People Search or popularity:

And for those occasions when the client is telling you that his/her strategic document really has to be on page 1 of the results (but not a Promoted Result/best bet), you have ‘Dynamic ordering’ – you can boost/demote results, including the option to promote to the top:

REFINERS tab

In the context of search, refiners are usually the links on the search engine’s results page (typically in the left nav) which allow the user to further filter the results. So if I do a search for “meeting minutes” and get lots of results, it would be nice to be able to filter by, say:

• Date range
• SharePoint site (since minutes might be stored in individual project sites)
• Author
• ..and so on

However, in the context of the Content Search web part, refiners actually allow you to do this filtering as part of the initial query. The REFINERS tab is effectively a convenience to you, the person configuring the web part – what happens is that a search is performed whilst in edit mode, and all relevant refiners (e.g. managed properties) are presented as available refiners. These can be selected and moved over to the right-hand list:

The effect of this is that a further filter is added to my query. In the example above, this may be easier than using a Property Filter on the BASICS tab – since there I have little support, I just select the property and type the value:

In the REFINERS tab, SharePoint is doing the search for me (as it’s configured so far), and only coming back with values which have been found in the returned results.

SETTINGS tab

The SETTINGS tab controls some high-level options for running the search:

Query rules

Since these can be defined at the parent site or search service, it could be the case that your CSWP gets affected by one of these. As the radio button shows, this can be overridden, but consider that some types of Query Rules may not have an effect anyway – as a reminder (from the table at the beginning), a Query Rule can either:

• Add a promoted result
• Add a result block
• Change the ranked results somehow (by modifying the query)

Out of these 3 actions, 1.5 of them could affect the results of a ‘default’ CSWP. This can be summarized:

Query Rule Action	Will affect CSWP results?
Add a promoted result	Not by default. When a search runs in SharePoint, multiple result sets are returned (e.g. ‘main results’, ‘best bet results’ and so on – in SP2013, the real names for these are ‘RelevantResults’, ‘SpecialTermResults’, ‘PersonalFavoriteResults’ and ‘RefinementResults’.). Although a CSWP can be configured to show any table, the default is ‘RelevantResults’ – and a promoted result gets added to ‘SpecialTermResults’.
Add a result block	Yes if result block is configured to show ‘ranked within core results’ (the default), rather than ‘shown above core results’.
Change ranked results	Yes.

For completeness, here’s the place in the CSWP where you select which search result set to use (e.g. if you want to switch from the default of ‘RelevantResults’:

Options in the Results Table dropdown (shown to the left):

URL rewriting

This one is fairly simple – if results are being returned from a catalog which is using “friendly” URLs, then the CSWP can override this to use the original URLs. It may not always make sense to use rewritten URLs in aggregations outside of the catalog pages, especially if you’ve implemented anything funky there.

Loading behavior

This is useful – specify whether the CSWP web part instance should load in the main page load (default) or in an AJAX manner after the main page has finished. Considering that a CSWP could either be the centerpiece of your landing page or merely some page footer navigation, it’s nice to be able to prioritize in this way.

Priority

Similarly, we can actually specify High, Medium or Low priority for each CSWP instance we use – great for the different usages we will have, although as per the description, note this only has any effect if the search service is overloaded.

TEST tab

The TEST tab is hugely useful – it provides you the ability:

• To see the underlying query text (in Keyword Query Language [KQL]) which has been generated (though it must be edited in other tabs)
• To see the preview when you are defining a query yourself (the preview pane will be empty on other tabs in this scenario)

Which is all great, but at first glance it’s easy to miss some extra functionality – if the ‘Show more’ link is clicked, other information becomes visible including details on any refiners and Query Rules which have been applied. So below I can see that a custom Query Rule I created has indeed been used, so there’s no guesswork on (for example) whether a certain item is actually being promoted or not:

Sidenote – listing items from ONE site/list/library with the Content Search web part

Worthy of a quick note – if all you need to do is roll-up content from one list/library, then you can do this with the CSWP – in the query, simply restrict the search using PATH:[URL to document library]. The Query Builder UI helps you do this by providing the ‘Restrict by app’ area:

N.B. note that one potential gotcha here can be that you need ‘HTTP’ if your sites are browsed on HTTPS but crawled on HTTP (as in my case).

If you do want to filter by site/list/library, consider of course that the good ol’ Content Query web part will work just fine here, and you’ll get instant changes as content is changed. What you won’t have, is the Content Search Web Part’s ability to automatically use tokens in the query (e.g. value of current navigation category, value from current user’s profile etc.)

Summary

The Content Search web part is a great tool in the SharePoint consultant’s box of tricks. Configuration may prove quite simple for some scenarios, but there is also huge amount of flexibility and so a certain degree of complexity comes with that. Many advanced scenarios which make use SP2013 search capabilities (such as Result Sources, Query Rules, promoted results and so on) will be possible – knowing the details will help you identify whether the CSWP can be the answer to a particular problem or not.

Writing data from apps to Office documents

A key feature of Office extensibility is that you can interact with your documents. For example, the Wikipedia app for Word and Excel, which we just released to the marketplace, enables you to insert content into Word documents or Excel spreadsheets. Although we do not recommend directly quoting Wikipedia in your papers (even Wikipedia says not to use Wikipedia in as an authoritative source), the app is a great way to assemble notes or quickly understand ideas from your reading.

Figure 1. Wikipedia app in Word

Although the Wikipedia app is a great example of adding content via apps, you can add even more content types on your own. In this article, we walk through the types of content you can use and provide some samples you can refer to as you get started.

What data can I write with my apps?

The data you can put into documents changes depending on the kind of document your app is inserted into. Apps for Word and Excel are particularly good candidates for inserting content.

Platform	Content
	Images	Text	Matrices1	Tables	HTML	OOXML2
Word 2013	✔	✔	✔	✔	✔	✔
Excel 2013		✔	✔	✔
Excel Web App		✔	✔	✔
PowerPoint 2013		✔

1- Matrices are tables without headers and are manipulated as 2D arrays rather than JavaScript objects
2- Word documents can be edited by directly adding/removing/changing their XML nodes

Understanding where the app model’s features are enabled is key to creating quality apps. The Wikipedia app is usable in Word and Excel 2013, but it handles insertion differently depending on what Office product the user is working from. Apps written for Outlook or Project are for other scenarios, so we disabled using the app there from the app manifest.

Interacting with documents through Office.js

The JavaScript library file Office.js provides the APIs used to insert content into your documents. There are three major objects within Office.js that are key to inserting content into your document: Office.context, Office.context.document, and Office.documentMode.

Office.context

Office.context represents the runtime environment of the app—this object gets you the locales of the application, information on the document/mailbox (through Office.context.document), and any saved custom Outlook settings that the app may have. It’s useful if you want to change your inserted content depending on your user’s location or language.

Office.context.document

This API contains everything you need to directly manipulate your documents. There’s a whole lot this object can do, but to keep it simple here, we just focus on its setSelectedDataAsync method.

Office.documentMode

Office.documentMode is called to see if you have the proper permissions to read and write to your document. It returns a DocumentMode enumeration value (either Office.DocumentMode.ReadWrite or Office.DocumentMode.ReadOnly) that lets you see whether the document can or cannot be written to.

If the document is read-only, you won’t be able to insert any content. Allowing your users to try to write to a read-only document will cause the insertion call to fail. It’s a good idea to watch for this and to notify your user if and when this occurs.

Inserting data with setSelectedDataAsync()

You can insert content into your documents by calling Office.context.document.setSelectedDataAsync. The parameters passed through to the method change depending on the content being placed, but mainly focus on the data being inserted, what the content should be rendered as (we’ll call this the coercion type), and the function that is called when the method returns. The apps for Office API docs have a good overview of the details—check them out to learn more.

Text

Oftentimes, you want to insert some kind of text into your user’s document. The user can then format and adapt the inserted text to fit his or her needs. In the Wikipedia app, we use this to insert snippets of articles, but for simplicity here, we insert a static line of text.

To insert text, pass a string object as the data in setSelectedDataAsync. No coercion type is necessary.

   

Tables and matrices

If you have tabular data, you can insert content through tables or matrices. Matrices are simple grids of information and can be inserted as two-dimensional arrays.

  

If you want to include headers, or want to use the data as a JavaScript object before it is inserted, you can create an Office.TableData object and insert the data that way.

 

HTML

If you want to format some content before putting it in your document, you can do so using HTML.

 Although your inserted text takes the document formatting, you must insert HTML to do app-specific styling.

OOXML

In the event that you cannot insert content through any of the above methods, and if you are in Word 2013, you can directly alter the structure of the document by inserting OOXML nodes. This gets complicated fast—refer to the Apps for Office CustomXmlNode APIs for more information.

Images

There is no image coercion type for setSelectedDataAsync. If the image you are trying to insert already exists, and you have a path to it, you can insert it as HTML. If you have programmatically created the image or do not have a URL to include in your HTML snippet, you can insert the binary image in an OOXML node. Inserting the image through HTML is much simpler, but if your document goes offline or the image URL changes, the image won’t appear in the document. Make your design decision based on your situation and what format your data is in.

I have a cross-platform app. How can I know what data I can use?

“But I’m writing a cross-platform app!” you say, and, “I don’t know if my users are in Word or Project! Can I add HTML? What should I do?”

Instead of checking the product that your app is operating in, check whether the feature you want to use is enabled. Here, we are checking if the product the app is living in can even insert data into the first place:

 

Once you determine that the product can actually insert content, you can check whether your coercion type is supported in your document. The following example checks if OOXML is supported by your app’s document.

Once those two checks have successfully completed, go ahead and insert your data.

If you want to make sure the content is successfully inserted, you can add a simple if statement within the return function:

 The status property of AsyncResult (result in the above code sample) returns an AsyncResultStatus enumeration, which indicates success or failure by its type.

What about Project and Outlook?

For now, apps living in Project and Outlook are consumption oriented. That is, they provide contextual information that complements your user’s work. While there are great apps you can write for these platforms, focus on consuming document data instead of inserting your own.

Where can I find some working examples?

If you’d like some working examples of app insertion, we have several examples to check out. All of the above examples are available in the attached Visual Studio solution, so you can see the code in action. Alternatively, the Wikipedia app for Office is open source – you can dig through the source on Codeplex.

Use data in your documents!

Apps for Office that insert content into documents allow users to gather information without leaving Office. It saves time for the user and improves efficiency. Write apps that insert data to help your users get things done!

References

• App Insertion code samples
• Document.mode (MSDN)
• Document.setSelectedDataAsync (MSDN)
• How to: Determine Host Application Support for Specific API Members (MSDN)
• TableData (MSDN)
• Wikipedia App for Office source (the Wikipedia app is open source!) (CodePlex)
• Writing Data to the Active Selection of a Document/Spreadsheet (MSDN)