Apps for Office and SharePoint blog

Roadmap for Apps for Office, VSTO, and VBA

Michael Zlatkovsky (MSFT) — Tue, 18 Jun 2013 16:00:00 GMT

With all the buzz around the new apps for Office programming model, developers might be wondering: What benefits does the new app model bring, and which of the three technology choices―apps for Office, managed VSTO add-ins, or VBA macros―are best suited for particular scenarios?

Apps for Office is a recognition that the technology landscape around us is changing: that ubiquitous connectivity, mobile devices, powerful and personalized cloud services, real time collaboration, and social are fast becoming the norm, and that a new app model must be brought forth to capture these evolving needs. At the same time, however, it’s important to note that all three technologies will be supported in the foreseeable future. This means that if you have an existing VBA or VSTO project, and if you’re satisfied with the capabilities, tooling, and marketability of your existing solution, you can be confident that your investments are safe. However, if you’re looking to expand the exposure of your product or service to a larger audience and allow for greater monetization opportunities, apps for Office can be a great option to start looking into. This post will guide you through the strengths of each of the three technologies, and suggest some factors by which to choose which Office customization approach is right for you.

Apps for Office

The newest addition to the Office developer toolbox, apps for Office are a new way for users to interact with Office customizations. Instead of having to install add-ins or enable macros, users can download, install, and use apps alongside a document, message, or appointment straight from the Office Store or from an internal corporate app catalog, and those apps run in a protected sandbox environment. Built with web technologies, apps for Office are particularly well suited for creating web mash-ups and using Office as a surface for exposing existing web functionality. Apps also offer lifecycle management capabilities, such as distributing or removing apps for the users in your corporation, managing updates, and tracking telemetry.

Figure 1 shows a content app and a task pane app embedded within an Excel document. The apps expose the existing web services of Bing Maps and Merriam-Webster, respectively, surfacing these through a convenient app that interacts with the user’s Excel environment.

Figure 1. Apps for Office: A content app and a task pane app embedded within an Excel document

The friction-free ease of distribution is a huge draw for apps for Office. Additionally, the Office Store is designed to make it easy for you to monetize your apps. Another neat aspect is that apps for Office can be used both in the Office 2013 and in a growing selection of Office Web Apps as well. For example, a mail app can use the same JavaScript API calls both for the desktop Outlook client and for Outlook Web App, spanning a breadth of devices. Most importantly, due to the web-based approach of the apps for Office model, developers can use their existing coding skills to develop apps with virtually any web programming technology, and apps can connect to virtually any backend data store. This makes the transition to the apps for Office model easier and smoother for web developers, allowing folks to re-use their existing web services and web development skills.

The sweet spot for apps―connecting rich web content and services contextually with Office―offers great public exposure and a host of deployment and web-technology benefits. The additional benefit that is exclusively available with apps for Office is the potential to monetize your app by making it available for purchase in the Office Store. Additionally, companies can lock down access to any internally-built apps by using a corporate app catalog that is only accessible to internal users. These two features offer great potential for both app distribution and IT management that has not been available to Office developers and enterprises in the past.

Managed add-ins built with Visual Studio Tools for Office (VSTO)

Visual Studio Tools for Office uses the .NET Framework to customize and extend Office. VSTO offers the full language support of C# and Visual Basic, and can therefore leverage the same frameworks, tools, and programming paradigms as the rest of the .NET Framework. VSTO also provides very tight integration with the Office client applications, both in terms of the rich sets of APIs, and the customizability of the user interface.

The following figure shows a VSTO solution running in PowerPoint. Notice the customized ribbon, the custom task pane (built with Windows Presentation Foundation), and a free-floating Windows Forms window.

Figure 2. A VSTO solution running in PowerPoint

For developers and businesses that need to leverage more extensive customizability of Office, or that need to target Office 2007 or 2010 (apps are only available starting in Office 2013), VSTO is the primary option. In addition to UI customization, VSTO excels at automation scenarios, such as adding or modifying shapes or charts, manipulating or merging documents on the user’s behalf, and interacting with other programs or resources on the host computer. Of course, not all automation-like tasks require automation: inserting a new paragraph with formatting, for example, could be done with VSTO through automation, or it could be done with apps for Office by writing out an Open-XML formatted string. The exact technology choice, and the suitability of using apps for automation, would depend on carefully analyzing the business requirements and the user workflow for the application.

VSTO is not lightweight, however. Deploying a VSTO add-in requires users to install the application, much as they would install any other desktop application. This often requires that the IT organization be involved in determining how safe the add-in is to the existing corporate environment, as well as often requiring that IT determine the upgrade path of this add-in for future releases of Office, and other application and environmental dependencies. This can lengthen time-to-deploy and create maintenance dependencies for the IT and business organizations. It is also important to note that VSTO add-ins run with the same security privileges as any other desktop program. This is a double-edged sword: it allows VSTO to use the power of the host computer and interact with the file system, which might be necessary for working across documents or interacting with external programs; but it also means that a malicious add-in could compromise the computer security. Even a well-intentioned add-in might affect the performance or stability of the host Office application, leading to slower startup or application failures. Ultimately, it’s up to the user (or IT admin) to ensure that an add-in is trustworthy before installing it. At the end of the day, VSTO is a very powerful tool, but this power does come at a cost.

Visual Basic for Applications (VBA) macros

VBA and the Visual Basic Editor is a tool that offers an in-product experience for automating Office client applications. Rooted in “classic” Visual Basic 6, and with support for a macro recorder in Word, Excel, and Access, VBA offers a simple onramp for writing an Office automation task to get the job done. However, as a decade-old technology, VBA is also more limited in terms of UI customizability and the overall tooling and framework support.

Figure 3. The VBA programming environment (built on “classic” Visual Basic 6) that is included with Office

An important distinction to note with VBA is that the customization code gets stored directly in the document. This makes initial deployment and distribution very easy, but makes updating code within any existing documents much more difficult. Within a corporate environment, this can create IT management and governance issues, as there is really no way to manage the proliferation of copies of the documents among users. Office documents are often emailed and duplicated, so there may have hundreds or thousands of documents based on the same VBA macro. Updating the code to improve features or to fix bugs would require that the Office artifact be re-emailed, re-structured, and re-worked by every single user and in every single file that has been using the customization. In a corporate environment, with no management or governance around such solutions, this is a risk to consider when creating or deploying VBA solutions.

In summary, VBA is the “classic” option for creating document-based customizations―particularly for programs that will require little upkeep, and which will be distributed to a fairly limited internal/departmental set of audience. Writing a 10,000-line program in VBA, or selling the program as a standalone product, would be more of a stretch.

Here is a comprehensive look at the choice of tools, across a broad set of categories:

Comparison Dimensions	Apps for Office	VSTO	VBA
Automation and interaction with the host computer		a	a
Interaction with the web	a	a
User Interface customization	partial *	a	partial
Interaction with the Office client object models	partial *	a	a
Offline Availability	partial **	a	a
Support for latest tools and technologies	a	a
Support for team development and source-control	a	a
Ability to target multiple host applications with one codebase	a
Ability to run code at application-level, across documents		a	partial
Security and sandboxed environment	a
Ease of distribution, lifecycle, and telemetry	a
Built-in monetization opportunity	a
Cloud and Desktop Compatibility	Office 2013+, and web-based O365 clients	Office 2007+ (desktop only)	Office 2000+ (desktop only)

*: Indicates a dimension where support might be partial today, but where future investments are expected to be made.

**: Relies on standard web offlining capabilities (for example, AppCache, Web Storage, page caching) supported by the browser.

Summary

Given the increasing array of choices―apps for Office vs. add-ins vs. macros―it is important for developers to know the value of each tool. Add-ins and macros are existing forms of solutions, aimed at solving existing needs for existing users, and will continue to be supported on the desktop for the foreseeable future. Apps for Office, meanwhile, come with a forward-looking platform, aimed at bringing web services and web technologies closer to Office developers. For add-ins and macros, Office is a highly-customizable, but siloed platform; for apps, Office is more of an integrated surface for exposing loosely-coupled web functionality using the web technology of your choice, with the potential for monetization, IT governance, and ease of lifecycle management and deployment. Both approaches have their merits, with add-ins and macros providing robust interaction and automation of existing Office client applications, and with apps for Office better-suited for creating easily-deployable, web-based solutions that work across a growing base of platforms including desktop, web and mobile. In cases where multiple approaches are equally possible, apps for Office are a natural choice for new projects.

Just like comparing Windows 8 apps with traditional Win32 desktop applications, or redesigning traditional websites for mobile devices, apps for Office represent a paradigm shift from add-ins and macros. In many cases, converting an existing managed add-in to the new apps for Office model would require significant re-imagining of the application. Thus, instead of thinking of a 1-for-1 conversion, it might be more fruitful to enable a few key scenarios using apps for Office, and see where that leads. Perhaps those key scenarios are enough to gain business on their own; or perhaps the re-imagined app can lead to entirely new scenarios and services, based on the cloud-optimized and multi-platform nature and the huge potential of the new app model. The capabilities of the new app model will continue to evolve, so even if your scenario does not fit the scope of the new app model today, keep an eye out for the new features of tomorrow.

Happy coding―with whatever Office technology(ies) you choose! Please leave a comment if you have any questions.

―Michael Zlatkovsky | Program Manager, Visual Studio Tools for Office and Apps for Office

Special thanks to Sonya Koptyev, Jim Nakashima, Rolando Jimenez Salgado, Sean Laberee, Angela Chu-Hatoun, and Sudheer Maremanda for their input into this post.

Upgrading your app for SharePoint

Miguel Caballero Pinto — Thu, 13 Jun 2013 19:50:00 GMT

Once you have submitted an app to the Office Store or published it to your corporate app catalog, you will probably start planning the next version of your app. An important part of that planning is ensuring that the app upgrade process will be smooth for your users and their data. This post explains how SharePoint enables developers to correctly upgrade their apps and how Office Developer Tools can make the process even easier.

To enable upgrading for your app, you have to consider things beyond the implementation of your first version, and your main concern will be to keep your app updated without losing any data on the process. On the other hand, as a developer, you also want a comprehensive way to track your changes with each version submitted.

SharePoint provides you with fine grained control over how each element of your app for SharePoint is upgraded. Office Developer Tools for Visual Studio 2012 helps you declare all the necessary information and performs some of the steps automatically for you. In the following sections, I’ll briefly walk you through how upgrade works in apps for SharePoint, and then talk about how you can use the Office Developer Tools to simplify this work.

How app upgrade works

The upgrade for all elements at the app package level (that is, client Web Parts, host web custom actions, etc.) are tracked by the version specified in the app manifest. This means that once the user decides to upgrade an app for SharePoint, and if the version in the app manifest changes, SharePoint will find the difference in those files automatically and perform the upgrade for you.

For the files inside a WSP package in the app package (for example, lists or modules), you need to declare how SharePoint should handle them in an upgrade. They must be specified in a declarative way in their Feature manifest, along with the version range where the upgrade actions should be triggered. Here is an example:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
         Version="1.0.0.2">
  <UpgradeActions>
    <VersionRange EndVersion="1.0.0.1">
      <ApplyElementManifests>
        <ElementManifest Location="Pages\Elements.xml" />
        <ElementManifest Location="Scripts\Elements.xml" />
        <ElementManifest Location="Content\Elements.xml" />
        <ElementManifest Location="Images\Elements.xml" />
      </ApplyElementManifests>
    </VersionRange>
    <VersionRange BeginVersion="1.0.0.2" >
      <ApplyElementManifests>
        <ElementManifest Location="List1Instance\Elements.xml" />
        <ElementManifest Location="List1\Elements.xml" />
      </ApplyElementManifests>
    </VersionRange>
  </UpgradeActions>

  <ElementManifests>
    <!-- Elements manifests are declare here. 
         Not relevant for this example -->
  </ElementManifests>
</Feature>

In this particular example, the new Feature version is 1.0.0.2, and this Feature manifest specifies the upgrade actions for the different element manifests included in the Feature. The element manifest for Pages, Scripts, Content, and Images were added in version 1.0.0.1, and a list was added in version 1.0.0.2. This way, if the app is updated from version 1.0.0.0 to version 1.0.0.2, the only modification SharePoint has to do for this Feature is to add the new list, as declared in the Feature manifest:

<VersionRange BeginVersion="1.0.0.2" >
  <ApplyElementManifests>
    <ElementManifest Location="List1Instance\Elements.xml" />
    <ElementManifest Location="List1\Elements.xml" />
  </ApplyElementManifests>
</VersionRange>

There are many more actions we can declare in the Feature manifest, which are well documented on MSDN: Upgrading Features.

Office Developer Tools support for app upgrade

Office Developers Tools supports the process of creating an app upgrade in many ways. In fact, for most scenarios, you can simply rely on what the tooling does for you. The tools also provide the flexibility to customize the upgrade actions. I will explain each of these in the following sections.

Module files upgrade support

By default, when you add a new file to a module, it will be added when the user deploys the next version of the app. This configuration is set up in the module elements manifest that contains the file. In particular, the attribute that enables upgrade is “ReplaceContent="TRUE"”, which is declared in the file element. Here is an example of a default Page module elements manifest for an app for SharePoint:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="Pages">
    <File Path="Pages\Default.aspx"
          Url="Pages/Default.aspx"
          ReplaceContent="TRUE" />
  </Module>
</Elements>

If you do not want to have to replace a particular file during upgrade, just remove that attribute.

Feature manifest and app manifest version kept in sync

Besides the version of the app, Features of an app also have their own versions. The Feature version number needs to be updated to be larger than the previous version so that it can participate in the upgrade process. To make sure that the different version numbers are addressed when you update your app version number in the manifest editor, Office Developer Tools keeps the app and Feature version numbers in sync. This means that if you change the version of the app in the app manifest editor, the Feature version will automatically be changed to the same version.

Element manifests kept in sync with Feature manifest

Every time a new element manifest is added to the project, Office Developer Tools will modify the Feature manifest by adding that element manifest to the first version range inside the declared upgrade actions. In this way, all the web artifacts of your project will be brought up-to date by default.

Customize Feature upgrade actions using Office Developer Tools

There are two ways in which Office Developer Tools will help you editing the Feature manifest.

Update through Feature manifest template editor

You can access the Feature manifest editor by double-clicking the project Feature file, selecting the manifest tab, and then clicking Edit options at the bottom of the screen.

The editor looks like this:

Figure 1. Feature manifest editor.

At the bottom of the editor is an area where you can add your own declarations. By default, the editor adds all the elements that are already in the project. You can modify these elements by adding them in the manifest editor, and Office Developer Tools will automatically match it with the one in the project.

For example, consider the scenario at the start of this post. A new list was added in version 1.0.0.2, and you want your users who are using the previous version to get this new list through upgrading, but the upgrade should only apply to the new list. In that case, you would introduce this text in the editor to specify the new list manifests in UpgradeActions of the Feature manifest:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/">
  <UpgradeActions>
    <VersionRange EndVersion="1.0.0.1">
    </VersionRange>
    <VersionRange BeginVersion="1.0.0.2">
      <ApplyElementManifests>
        <ElementManifest Location="List1Instance\Elements.xml" />
        <ElementManifest Location="List1\Elements.xml" />
      </ApplyElementManifests>
    </VersionRange>
  </UpgradeActions>
</Feature>

The actual Feature manifest will then become:

Figure 2. Feature manifest preview on editor after update.

Notice that Office Developer Tools always adds the project items to the first VersionRange element so they will be updated by default for all the artifacts in the project. If you only want a specific set of artifacts to be upgraded, you can specify an end version for the first version range, as the above sample does, to restrict when this action will be triggered.

Advanced Feature manifest editing

If the Feature manifest editor does not meet your needs, you can always edit the Feature manifest by hand. To do this, click Overwrite generated XML and edit manifest in the XML editor in the Feature Designer (see Figure 3 below). Be aware that after clicking that link, Office Developer Tools will no longer update the Feature manifest, and you will have to handle all changes manually.

Figure 3. Option for editing the Feature manifest manually.

In summary, this post explained how upgrade works in apps for SharePoint, and how Office Developer Tools can help you with the upgrade process. Let me know if you have any issues or feedback by adding a comment to this post or at the Developing Apps for SharePoint 2013 forum.

Happy coding!

~ Miguel Caballero Pinto| Software Development Engineer, Visual Studio Tools for Office & Apps for Office

Create a web service for an app for Office using the ASP.NET Web API

Michael Zlatkovsky (MSFT) — Mon, 10 Jun 2013 17:00:00 GMT

You may have heard that apps for Office use client-side programming when communicating with the Office object-model. You may also have heard that apps for Office are especially well-suited for web mash-up scenarios, and are ideal for calling into web services and interacting with Web content. As a developer, how do you author your own web service? This post will lead you step-by-step through creating your own Web API service and calling into it from client-side app for Office code.

Sample code: All relevant code will be shown here. To download a copy of the sample code, see Apps for Office: Create a web service using the ASP.NET Web API.

Getting started

First, when would you need to author your own web service for an app for Office?

To do this	Consider this…
Establish a database connection, or connect to a service with a username and password.	Encoding those in JavaScript is a serious security risk, as JavaScript code is trivially easy to inspect. Such calls should always be done on the server
Perform any functionality where the algorithm/logic should be kept hidden from users	Just as above, if your app encodes or transforms data (and if the algorithm for the transformation is something you need to keep secret), keeping the logic behind the server might be your only option.
Retrieve external data that is not available in JSON-P format	Browsers implement a same-origin policy that prevents scripts loaded from one domain to manipulate content in another domain. Data in JSON-P format can pass through, but other formats may not. Creating your own web service allows it to act as a “wrapper” around the external data, bypassing the browser same-origin policy limitations.
Use existing server-side code or libraries (or to share a common back-end across multiple platforms)	Suppose your app uses existing .NET Framework logic or libraries, or that you need to share a common back-end across multiple platforms. Exposing that functionality via a web service allows you to keep more of your existing code and libraries as is, without re-writing it to JavaScript.
Perform licensing validation	For apps posted to the Office Store, license checks must be performed via server-side code.

Just to be clear, not all web-service scenarios require that you author your own web service. In particular, if your app consumes data from a public service that returns data in JSON-P format, you may not need to write your own web service at all. For purposes of this article, however, we’ll assume that there is some inherent business logic or data transformation that you need to expose to your app by means of writing your own web service. Let’s get started.

Using Web API

There are several possible choices for server-side technologies. For purposes of this article, I will be demonstrating the use of the ASP.NET Web API. Web API is an excellent framework for building REST applications, and Visual Studio provides first-class tooling support for it. The ability of Web API to communicate across a broad range of platforms makes it a particularly compelling choice for communicating between an app for Office and a corresponding web service.

Scenario

Let’s take a real-life example: You have an app, and now you want to add a “Send Feedback” page. To send the feedback, you’ll need to either log it to a database or maybe just email it to your development team – but in either case, you have sensitive data (connection string or a username/password combo) that you certainly wouldn’t want to expose via JavaScript. As we saw in the “Getting started” section, this is a canonical example of masking the back-end functionality behind a web service.

To make this example match real-world scenarios as closely as possible, let’s send multiple bits of information to the service: for example, an overall rating (an integer on a 1-5 scale) along with a string for the actual feedback. Likewise, the response we’ll get from the service will include both a Boolean status flag to indicate success, and a message back from the server (e.g., “Thank you for your feedback” or an error description). By framing the problem this way, you can see how this sample is analogous to more complex scenarios, like fetching data from a database via a web service (for example, sending a query with certain parameters, returning a data structure that represents the list of results, etc.)

Figure 1 shows a screenshot of the app we’re aiming to build. Again, to download the full sample project, see Apps for Office: Create a web service using the ASP.NET Web API.

Figure 1. Screenshot of the “Send Feedback” sample app.

Create the app project

To get the example up and running quickly, let’s just create a new task pane app for Office project, and place the “send feedback” functionality as part of the home screen. Of course, if you have an existing project where you’d like to append this functionality, you could create a SendFeedback folder, add two files called SendFeedback.html and SendFeedback.js within it, and place the functionality there, instead.

This example assumes you’re using the latest version of Office Developer Tools. Thus, when you create a new project, you should get a project structure as shown in Figure 2.

Figure 2. Visual Studio project structure.

Open Home.html, and replace its <div id=”content-main”> section with the following code.

<div id="content-main">
    <div class="padding">
        <p>This sample app demonstrates how an app for Office can 
           communicate with a Web API service.</p>
        <hr />
        <label>Overall rating: </label>
        <select id="rating" class="disable-while-sending" 
            style="width: inherit">
            <option value=""></option>
            <option value="5">&#9733;&#9733;&#9733;&#9733;&#9733;</option>
            <option value="4">&#9733;&#9733;&#9733;&#9733;</option>
            <option value="3">&#9733;&#9733;&#9733;</option>
            <option value="2">&#9733;&#9733;</option>
            <option value="1">&#9733;</option>
        </select>
        <br />
        <br />
        <label>Feedback:</label>
        <br />
        <textarea id="feedback" class="disable-while-sending" 
            style="width: 100%; height: 200px"
            placeholder="What would you like to tell us?"></textarea>
        <button id="send" class="disable-while-sending">Send it!</button>
    </div>
</div>

As you can see, the HTML is very standard, containing a dropdown for the star rating (★ is the Unicode symbol for a star), a textarea for the textual feedback, and a button to send the data. Note that each of those components carries a unique ID, so that it can be easily referenced it via code. I also am applying a class called “disable-while-sending” to each of those three elements – again, just as a way to reference these elements from code – to be able to provide a status indication after the user has clicked “send”. Remember that web service calls are done asynchonrously, so disabling the controls provides both a visual indication, and prevents users from clicking “Send” multiple times while the first call is still underway.

Let’s add a corresponding JavaScript file as well, with a placeholder for the sending procedure. If you’re following along with Home.js, replace the entire contents of that file with the following code.

/// <reference path="../App.js" />

(function () {
    "use strict";
    // The initialize function must be run each time a new page is loaded
    Office.initialize = function (reason) {
        $(document).ready(function () {
            app.initialize();
            $('#send').click(sendFeedback);
        });
    };

    function sendFeedback() {
        $('.disable-while-sending').prop('disabled', true);
        // Magic happens
    }
})();

Okay, that’s as far as we can get for now. Let’s add our web service.

Adding a Web API controller

With Web API, anytime you call a method on a server, you’re doing so via a Controller. So, let’s add a Controller to handle our SendFeedback action.

You can add a controller anywhere within your web project. By convention, however, controllers go into a “Controllers” folder at the root of the project, so let’s go ahead and create it now.

After you create the folder, if you choose it and mouse over the “Add” menu, and you should see the option to add a Web API Controller class. The same option should be available under the “Add” > “New Item…” dialog, as well. Let’s add the Web API controller class now.

Figure 3. Adding a Web API Controller Class.

By another convention, that is somewhat more strictly enforced, Web API controllers must end with the suffix “Controller” in order to be properly recognized by the routing mechanism. This isn’t to say you can’t change it, but that does require a bit of extra legwork. So for now, let’s appease the Web API plumbing architecture, and name our controller “SendFeedbackController”.

We can leave the auto-generated code be for the present, and move onto the next step. We’ll be returning here in a moment.

Setting up the Web API routing

There is a quick side-step we need to take in order for our Web API Controller to function: we need to register it with the web application. Some flavors of web projects, like MVC, include support for Web API routing by default. The default app for Office does not include this plumbing, but it’s not hard to add.

Note that this step is best done after you’ve already added a Controller to the project; otherwise, you need to set up some references manually. This is why this post has you first add the controller, and only then register it.

To add the Web API routing registration, right-click on the root your web project, select “Add”, and you should see “Global Application Class” as one of the options. It should also be available under the “Add” > “New Item…” dialog box. The default name of “Global.asax” should suffice.

Figure 4. Adding a Global Application class.

Once you’ve added Global.asax, the file should automatically open, with empty method stubs filled out. Add the following two “using” statements somewhere at the top of the file.

using System.Web.Routing; 
using System.Web.Http;

The only method you need to touch is the Application_Start method. Add the following code into the Application_Start body (the rest of the methods can remain empty).

RouteTable.Routes.MapHttpRoute(
    name: "DefaultApi",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

What does this means? In a nutshell, the method registers your controllers to be available under the “api” route, followed by the name of the controller and an optional ID (in case of parameterized queries). The {ID} will not be used for our final SendFeedback controller, but it doesn’t hurt. Note that you can also specify other parameters under routeTemplate, such as “{action}”, to include the name of the action as part of the URL. Refer to "Routing in ASP.NET Web API" for more information on configuring Web API routing, if you’re curious.

Filling out the Controller

The SendFeedbackController class has some auto-generated code that demonstrates some of the capabilities of Web API, including responding to various HTTP verbs (“GET” vs. “POST”, and so on), routing based on the ID parameter, and so forth. While these capacities are certainly worth exploring on your own (e.g., for an example of how to return a list of values), they are not necessary for our current “Send Feedback” scenario. For our purposes, all we want is a single method that takes in some data (overall rating and feedback text), and returns some data (a status and a message).

Data structures

Let’s write some data structures to hold the request and response objects. You can write them as inner classes within SendFeedbackController.

public class FeedbackRequest
{
    public int? Rating { get; set; }
    public string Feedback { get; set; }
}

public class FeedbackResponse
{
    public string Status { get; set; }
    public string Message { get; set; }
}

Nothing fancy – we’re using built-in data types (strings, integers) to build up the more complex request and response classes. If you’re curious why Rating is a nullable (int?) type, this is both to demonstrate that you can do this, and to handle the case where the user does not fill out a rating in the dropdown.

Method signature

Now let’s create the actual SendFeedback method. Go ahead and delete the other method stubs (they’re only there as examples, and you can always re-generate them by creating a new Web API Controller). In their place, let’s put a single SendFeedback method, which takes in a FeedbackRequest, and returns a FeedbackResponse.

[HttpPost()] 
public FeedbackResponse SendFeedback(FeedbackRequest request) 
{ 
 // Magic happens 
}

We will be using the HTML “Post” verb to post data to the controller. (For a discussion of POST versus GET, search the web for “when to use POST versus GET”). Note that you can either put the word “Post” as part of the method name, or you can name the method what you’d like, and annotate it with a “[HttpPost()]” attribute. It’s a matter of personal preference.

Try-catch

Let’s wrap our method body in a try-catch block, so we can gracefully handle any errors that occur as part of the method. The “catch” is shorter, so let’s fill that out first.

try
{
// Magic moved to here
}
catch (Exception)
{
    // Could add some logging functionality here.

    return new FeedbackResponse()
    {
        Status = "Sorry, your feedback could not be sent",
        Message = "You may try emailing it directly to the support team."
    };
}

What’s happening here? Because the controller’s method is the very outer layer of the API, we want to ensure that any exceptions are caught and handled appropriately. Thus, on failing, we will still send a response via the data structure we defined, with an appropriate status text and message. Note that as part of the “catch”, we could instead throw a new HttpResponseException rather than returning a FeedbackResponse, and handle the exception on the client – it’s a matter of preference / convenience. However, performing a try-catch on the server-side code is still be useful for logging or for a potential fallback mechanism. For a more thorough discussion of Web API error handling, see “ASP.NET Web API Exception Handling” on the ASP.NET Blog.

The mail-sending functionality

Now let’s tackle the body of the “try”. First, if we’re going to send feedback via email, we’ll probably need to gather up some credentials.

const string MailingAddressFrom = app_name@contoso.com;
const string MailingAddressTo = "dev_team@contoso.com";
const string SmtpHost = "smtp.contoso.com";
const int SmtpPort = 587;
const bool SmtpEnableSsl = true;
const string SmtpCredentialsUsername = "username";
const string SmtpCredentialsPassword = "password";

For the subject, let’s use the name of the app and the current date, so that it’s easy to distinguish individual feedback items.

var subject = "Sample App feedback, " 
 + DateTime.Now.ToString("MMM dd, yyyy, hh:mm tt");

For the body, we will append the rating and the feedback. Notice how we’re using the request object to read these values, just like we would with any normal function parameters.

var body = "Rating: " 
 + request.Rating + "\n\n" + "Feedback:\n" 
 + request.Feedback;

Now we create the mail message and send it via the SmtpClient class (note that you’ll need to add a “using System.Net.Mail;” statement to the top of the file).

MailMessage mail = 
 new MailMessage(MailingAddressFrom, MailingAddressTo, subject, body); 
// Send as plain text, to avoid needing to escape special characters, etc. 
mail.IsBodyHtml = false; 
var smtp = 
 new SmtpClient(SmtpHost, SmtpPort) { EnableSsl = SmtpEnableSsl, 
 Credentials = 
   new NetworkCredential(SmtpCredentialsUsername, 
 SmtpCredentialsPassword) }; 
smtp.Send(mail);

Because we’re using a try-catch block, we know that if the code has reached past the Send command, the feedback was sent successfully. So we can return a FeedbackResponse object back to the user.

// If still here, the feedback was sent successfully.
return new FeedbackResponse()
{
    Status = "Thank you for your feedback!",
    Message = "Your feedback has been sent successfully."
};

Our controller is now done! Now we just need the client-side piece.

Back to JavaScript

Let’s return to our sendFeedback() method stub that we left in the JavaScript code in Home.js. We’re just about ready to finish the app.

First, we want to disable the “send” button and the other fields while sending is underway.

$('.disable-while-sending').prop('disabled', true);

Next, prepare the data to send. Note that we create a JavaScript object to hold this data, but with property names (“Feedback” and “Rating”) matching the names of the FeedbackRequest fields from our .NET Controller.

var dataToPassToService = { 
 Feedback: $('#feedback').val(), 
 Rating: $('#rating').val() 
};

Finally, we make a jQuery AJAX call. The URL is relative to the page form which we’re calling the request, hence we go back two levels (to escape “App/Home/”) before turning to “api/SendFeedback”. The data type is “POST”, which matches what the controller expects. For the data, we stringify the above “dataToPassToService” object, and add the appropriate content type. (Tip: While it’s not necessary for POST request, you may want to specify an explicit “cache:true” or “cache:false” for GET requests, depending on whether or not those should be cached).

$.ajax({
    url: '../../api/SendFeedback',
    type: 'POST',
    data: JSON.stringify(dataToPassToService),
    contentType: 'application/json;charset=utf-8'
}).done(function (data) {
    // placeholder
}).fail(function (status) {
    // placeholder
}).always(function () {
    // placeholder
});

Now onto the final stretch of filling out the placeholders above. If the AJAX call succeeds, we’ll display a message to the user, using the Status and Message fields that we get from the controller’s FeedbackResponse object. Let’s substitute that into the “done” placeholder above.

app.showNotification(data.Status, data.Message);

If the call fails (for example, you are offline), let’s add a similar notification (“fail” placeholder).

app.showNotification('Error', 'Could not communicate with the server.');

Finally, regardless of whether the call succeeded or failed, let’s re-enable the controls so that the user can try again, or send another bit of feedback, or copy-paste the feedback and send it via email. Thus, for the “always” placeholder, let’s do.

$('.disable-while-sending').prop('disabled', false);

Our code is now officially complete.

Run it!

Let’s have a celebratory run. Press F5 to launch the project, and add some feedback text and a rating in the appropriate fields. Press “Send”. If all is well – and if you have substituted the Controller’s email account constants with appropriate credentials – you should see a notification in the UI that your feedback has been sent, and you should also receive an email with a copy of the feedback. If you’re curious about what is happening behind the covers, you can use a tool like Fiddler to analyze the serialization “magic” that’s happening behind the covers. You can also use Visual Studio to pause on breakpoints, both in the JavaScript code and in the Controller.

Figure 5. Fiddler trace showing data passing in and out of the web service

The example in this post is just the tip of the iceberg: I am excited to see what apps folks will build, leveraging the flexibility and responsiveness of client-side code, and the power and security of server-side code. Please leave a comment below if you have any questions or comments.

~ Michael Zlatkovsky | Program Manager, Visual Studio Tools for Office & Apps for Office

Office Store now accepting listings in four additional languages – French, German, Japanese, and Spanish

Krishnan Raghupathi — Tue, 04 Jun 2013 15:17:00 GMT

We’re excited to announce that the Office Store is now accepting listings in four additional languages!

Whether you have existing apps listed in the Office Store or you’re ready to add your first new app, you can now list additional languages for your app: French, German, Japanese, and Spanish. In early summer this year, we plan to open stores for markets that are associated with these four languages as well as the English-language markets beyond the United States. Now is a great time to be among the first apps listed in these new markets.

Three steps to preparing your app for release in additional languages

1. Update your app’s manifest to declare language and locale support. Depending on the app type, you declare language support in the manifest with different manifest elements. For apps for Office, see Designing an app for Office for specific locales. For apps for SharePoint, see Explore the app manifest and the package of an app for SharePoint.

Note: The maximum number of allowable locales that can be declared for apps in the Office Store is 25.

2. Add localized app metadata in Seller Dashboard to provide a language-specific Store experience. When submitting your app in the Seller Dashboard, you can select 1–5 languages that your app will be listed in. Learn how to add apps in the Microsoft Seller Dashboard.

Note: You can declare more languages in your app's package than are available for submission in the Seller Dashboard.

3. Localize your app functionality. The apps that offer the best customer experience are localized for the language for which they are submitted. To learn more see How to: Build a localized app for Office or How to: Localize apps for SharePoint.

For more information about how to submit an app to the Office Store, see How to: Add apps in the Microsoft Seller Dashboard.

Here are a few important things to keep in mind on the availability of apps in these new markets.

1. All apps that have English as a submission language in the Seller Dashboard:

Will be published and available, upon validation approval, in the US-based Office Store.
Will be distributed to all markets as they are opened. You can explicitly indicate markets where you don't want to distribute your app using the Seller Dashboard. For more information, see How to: Add apps in the Microsoft Seller Dashboard.

2. Apps which do not include English as a submitted language in Seller Dashboard can reach validation approval, but will not be available in a store until the additional language-specific store locales open in early summer.

- Krishnan Raghupathi | Program Manager, Office Store Team

New Office developer blogs network and Office developer highlights at TechEd North America 2013

Nina Ruchirat — Fri, 31 May 2013 20:34:00 GMT

Blogs for Office developers network

We've launched a new top-level blog network that joins all the primary Microsoft-supported Office developer blogs in one central place.

http://blogs.msdn.com/b/officedevblogs

Figure 1. Office developer blog network main page

At the top level, you can view a combined summary feed of all four blogs in the network, or you can easily navigate to each individual blog where you can subscribe to posts:

We hope that this effort will create a more connected experience for developers who work across different Office products.

Please share your thoughts and feedback on this new blog network structure in the comments of this post—we would love to hear from you!

TechEd highlights for Office and SharePoint developers

From June 3–6 in New Orleans, thousands of developers and IT professionals will converge at the Ernest N. Morial Convention Center for TechEd North America 2013 to network and learn about Microsoft technologies, tools, platforms, and services.

There will be a lot of great programming for Office and SharePoint developers.

If you are attending, be sure to check out the content in these two tracks:

Office 365 & Unified Communications (OUC)
SharePoint & Enterprise Social (SES)

If you are a Cloud App Model developer, you won't want to miss this foundational keynote session:

Office & SharePoint 2013 Development: Introduction to the new Cloud App Model
Speaker: Brian Jones
Monday, June 3rd 11:00am–12:00pm
Session #FDN04

With Office and SharePoint 2013, we introduced a new unified Cloud App Model based on web standards. It provides a consistent way to rapidly build and deploy apps that integrate with the tools and web hosting platforms you are most familiar and comfortable with. In this session, you will learn about the ways in which you can enhance Office and SharePoint with light-touch, robust web solutions; deploy apps into Office and SharePoint for easy discovery and sharing; and manage the portfolio of app investments you’ve made across your enterprise.

Several hands-on labs are offered, including:

Building SharePoint-Hosted Apps with "Napa" (#SES-H306)

And be sure to catch these 0–60 sessions as well:

0 to 60: Developing Apps for Microsoft Office 2013 (#SES-B201)

0 to 60: Developing Apps for Microsoft SharePoint 2013 (#SES-B202)

In the TechExpo Hall, the Microsoft Solutions Experience area will have a robust section for Office, SharePoint, Exchange, and related products, including the scenario booths "Build Apps" and "Enterprise Social," as well as deep-dive areas for Office, Office 365, Exchange, SharePoint, and Project.

Nine members of Office Content Publishing will be attending and staffing the booths, including myself. You can find more info on our activities in this post on the Office IT Pro blog:

Join us at TechEd North America 2013 in New Orleans

Also - for Exchange here is a great post with a list of sessions in that track:

Exchange at TechEd North America 2013

We are looking forward to networking with TechEd attendees! If you are on Twitter, be sure to track the hashtag #msTechEd.

If you are unable to attend TechEd North America in person, you still have a chance to tune in for the keynote and technical sessions. Register here for the live streaming keynote and sessions on Channel 9.

Add search capabilities to your apps for SharePoint

Chakkaradeep Chandran — Thu, 30 May 2013 13:00:00 GMT

With Office Developer Tools for Visual Studio 2012, developers can deploy custom search configurations to a search-enabled site. Custom search configurations include all customized query rules, result sources, result types, and site search settings.

The MSDN article How to: Deploy custom search configurations by using Visual Studio explains how to deploy custom search configurations by using Visual Studio with an app. The article focuses on creating a custom Microsoft Developer Network (MSDN) query source and a custom query rule, which can help you get results from the MSDN website. The custom search configuration is then exported from the SharePoint site, imported into Visual Studio, and deployed with the app.

Exporting and deploying custom search configurations only deploys the search configurations to the respective SharePoint site. To provide a better search experience, we can easily extend the sample app to include a custom search results page that will display results from the custom search configuration deployed with the app. This is great, especially if you want to deliver a customized search experience to your users.

Getting ready

First, make sure you have followed the steps in the MSDN article to create the app with the custom search configuration imported into Visual Studio.

Figure 1 shows how my Solution Explorer appeared after I followed the steps in the MSDN article.

Figure 1. MSDN Search Sample Solution Explorer

Considerations to deploying your search app to a Developer Site

You can deploy the app to any Developer Site where the search features are enabled. However, that will not provide the full-fledged search experience for your app. Deploying the app to an Enterprise Search Center site will integrate the app into your Search Center to provide the customized search experience.

In this blog post, we will deploy the app to an Enterprise Search Center. Follow the steps in Quickly start developing apps with the new “0-60” developer experience to enable side loading of apps in the Search Center site. Side loading allows Visual Studio to deploy an app to a SharePoint site. This is required because the Enterprise Search Center is not a Developer Site.

App permissions

In the MSDN how-to, the app is required to have Full Control on the site collection. This is required if the custom configurations are deployed to the site collection. However, this is not required if you want to deploy the custom configurations in the app (that is, the app web) itself.

In the article, the DeployToParent attribute is set to true in the search schema. You can change it back to false if you want to deploy the configurations in the app.

In this blog post, we will change the DeployToParent to false so that the custom search configurations are included in the app, and thus no special permissions are required to deploy the custom search configurations.

MSDN search results page

We can now create the page that will return search results from the MSDN query source.

Instead of creating a new page, let’s modify the Default.aspx.

Rename Default.aspx to Results.aspx. Open Results.aspx and perform the following:

1. Paste the following code at the top, just before the PlaceHolderAdditionalPageHead content placeholder:

<%@ Register 
    TagPrefix="Search" 
    Namespace="Microsoft.Office.Server.Search.WebControls" 
    Assembly="Microsoft.Office.Server.Search, 
            Version=15.0.0.0, 
            Culture=neutral, 
            PublicKeyToken=71e9bce111e9429c" %>
<%@ Import Namespace="Microsoft.Office.Server.Search.Internal.UI" %>

2. Edit the title text in the PlaceHolderPageTitleInTitleArea content placeholder:

Search Microsoft Developer Network

3. Paste the following code inside the PlaceHolderLeftNavBar content placeholder:

<div class="ms-sitesearch-refinement">
    <Search:RefinementScriptWebPart ID="RefinementScriptWebPart1" 
        runat="server" 
        ChromeType="None" />
</div>

This code will render the refinement panel in the page.

4. Paste the following code inside the PlaceHolderMain content placeholder:

<div class='ms-srch-siteSearchResults'>
    <div id="searchInputBox">
        <Search:SearchBoxScriptWebPart ID="SearchBoxScriptWebPart1" 
     runat="server" 
            PageTitlePrefix="MSDN Search Results" 
            RenderTemplateId="~sitecollection/_catalogs/masterpage/
Display Templates/Search/Control_SearchBox.js" 
            EmitStyleReference="false" 
            ChromeType="None"                 
            ResultsPageAddress="Results.aspx" 
            ShowPreferencesLink="false"/>
    </div><br /><br />
    <Search:ResultScriptWebPart ID="ResultScriptWebPart1" 
        runat="server" 
        ChromeType="None" 
        UseSharedDataProvider="false" 
        ShowAdvancedLink="false" 
        ScrollToTopOnRedraw="true" 
        ShowUpScopeMessage="true"
        ShowPreferencesLink="false" 
        UseSimplifiedQueryBuilder="false" 
        DataProviderJSON="{ &quot;SourceName&quot;:&quot;MSDN Query Source
&quot;, &quot;SourceLevel&quot;:&quot;SPWeb&quot; }"
        ItemTemplateId="~sitecollection/_catalogs/masterpage/
Display Templates/Search/Item_Default.js"  />
</div>

The code performs the following:

Adds two Web Parts

SearchBoxScriptWebPart adds a search input box and initiates the query.
ResultsScriptWebPart displays the search results.

Sets the MSDN Query Source as the data provider for the ResultScriptWebParts using the DataProviderJSON property. It is a JavaScript Object Notation (JSON) serialized version of the data provider:
{ “SourceName”: ”<query-source-name>”,”’SourceLevel”:”SPWeb”}
This enables the ResultsScriptWebPart to return the search results by querying the data source provided.

5. Open Content\App.css and paste the following custom styles:

#searchInputBox {
    float: left !important;
}

.ms-srch-upscope-top {
    margin: 0px !important;
}

Modify the DeployToParent attribute

Open SearchConfigurationSettings.xml and modify the value of the DeployToParent attribute to false.

Figure 2. DeployToParent attribute

Change app permissions

Because we are deploying the search configurations in the app itself, we no longer require the app to request special permissions.

1. Open AppManifest.xml.

2. Switch to the Permissions tab.

3. Delete the permission scoped to Site Collection.

Verify your app

Press F5 to start debugging your app.

If the app is deployed successfully, Visual Studio will open the app in your browser.

Figure 3. MSDN Search Sample

Type SharePoint 2013 app development in the Search box and press Enter.

Search results will be returned from MSDN and displayed in the page.

Figure 4. Search results

Enterprise Search site integration

Because we deployed this app to an Enterprise Search Center, the app is now integrated with the Search Center.

Navigate to your Developer Site by clicking the top-left link (Enterprise Search Center Dev Site in Figure 4). Because it is deployed to an Enterprise Search Center, clicking the Developer Site takes you to the Enterprise Search Center site.

Type SharePoint 2013, and press Enter to search.

As you can see from the following screen shot (Figure 5), we get local results. Notice we have a query source named MSDN added. This is the app we just deployed!

Figure 5. Enterprise Search Center results

Clicking MSDN will open the app with search results for the query term!

Figure 6. MSDN search results

Conclusion

We now have a great app that is integrated into the default search experience to query the MSDN site.

You can further extend this sample by including a custom result block or a custom display template.

Feel free to leave a comment if you have any questions or feedback regarding building search apps, and don’t forget to let us know if you have any search apps published too!

Some helpful links below to get you started with search configurations:

Localizing host web features in apps for SharePoint

Ricardo Loo — Wed, 29 May 2013 13:00:00 GMT

Visual Studio 2012 can’t localize host web features by itself. Learn about a tool that you can use to localize your host web features, such as app parts and custom actions.

SharePoint is used in many countries, regions, and languages. Because of this, you may want to maximize your reach to potential customers by localizing your apps. There are resources out there that can help you localize your app, like How to: Localize apps for SharePoint and Localize the app web, host web, and remote components of an app.

In this post, I want to focus in some components that provide an important link from the host web to the app itself. Host web features, such as app parts and custom actions, are vital in connecting experiences in SharePoint to your app. Localizing host web features is of the utmost importance.

Localizing app parts and custom actions can be a little difficult because Visual Studio 2012 does not properly package resource files for these features. If you try to use a resource string in an app part, the app part displays the resource string name, and not the value as expected. The following image shows the result of trying to localize an app part by using the strings in the host web resource file.

Figure 1. Failed attempt to localize an app part with strings in the host web resource file

However, the workaround is not too complicated. Resource files are actually included in the app package. The only missing parts are the OPC (Open Packaging Conventions) relationships to resource files in the app package. OPC relationships define an association between two items—in this case, the resource file and the package.

You can manually add the relationships to the app package, as explained in How to: Localize apps for SharePoint. But manually adding the relationships prevents you from using F5 to automatically build, deploy, and debug your app. To be able to use F5 to debug a localized app, you can use a program or script in the pre-deployment event of the app project in Visual Studio. The sample project in this article is a Visual Studio solution that does exactly what we need: it adds the missing relationships to resource files in the app package.

You can build the AddRelsToAppPackage project and use the compiled executable in the pre-deployment event of your app for SharePoint project. Just follow these steps:

Build the AddRelsToAppPackage project.
Copy the executable file to the root folder of your app for SharePoint project.
Right-click your app for SharePoint project, and click Properties.
Click the SharePoint property page.
Type the following command in the pre-deployment command line:
"$(ProjectDir)\AddRelsToAppPackage.exe" "$(TargetDir) "
Important: The trailing space after $(TargetDir) is required.

Now you can debug your app for SharePoint by using F5. The following image shows a localized app part that uses the workaround.

Figure 2. Successfully localized app part using the AddRelsToAppPackage tool

The AddRelsToAppPackage project should meet the basic requirements to localize host web features in apps for SharePoint. Feel free to edit the Visual Studio solution if your app has additional requirements. As a reference, here are the tasks performed by the AddRelsToAppPackage project:

Opens the folder provided as the first parameter
Retrieves the first file that matches the search pattern *.*app
Extracts the file that includes the OPC relationships for the host web features
Loads the contents of the file in an Xml object
Adds an OPC relationship to the Xml object for every resource file in the root folder of the app package
Writes the content back to the file

I hope you are successful in localizing your app for SharePoint. By localizing your app, you can provide a better experience and reach more customers.

June 3 session: Develop apps for SharePoint 2013 with Visual Studio 2012

Xiaoying Guo — Tue, 28 May 2013 13:00:00 GMT

My name is Xiaoying Guo, and I’m a program manager on the Microsoft Office Developer Tools team in Visual Studio. On June 3, I’m giving a talk on building apps for SharePoint using Visual Studio 2012. The talk is organized by the .NET Developers Association and will be held in Building 40 on the Microsoft Redmond campus. You can find more information about the session on the .NET Developers Association site.

If you have heard about the new app model in SharePoint 2013, but you are wondering how you can actually build apps, this is the right session for you. In this demo-heavy session, you will learn how to best use Office Developer Tools for Visual Studio 2012 to build great apps for SharePoint. We will explore the SharePoint development experience and see the first-class support for common app features, including client Web Parts, custom actions, remote event receivers, and more. You will also learn how to use Team Foundation Server (TFS) for apps for SharePoint continuous integration.

I’m looking forward to seeing you there!

Xiaoying Guo

Program Manager, Office Developer Tools

Office and SharePoint 2013 Continuous Integration Using Team Foundation Service and Office 365

Xiaoying Guo — Wed, 22 May 2013 13:00:00 GMT

When your team is collaborating on a project, you need a regular and reliable development process to ensure smooth delivery while maintaining high quality. This process typically includes frequent integrations from team members, regular builds, and testing against the new build to measure quality. Continuous integration is a great way to manage this kind of process.

In SharePoint development, continuous integration has historically meant setting up a SharePoint server together with a build server in your organization to get regular builds and run tests on it. With the launch of Office 365 and Team Foundation Service (TFS), this onerous setup is no longer required. Instead, you can simply sign-up for each of these services. In this post, we’ll walk through configuring these services so that you can enable continuous integration for your projects.

Get an Office 365 Developer account

To develop, test, and deploy apps for Office and SharePoint, you can sign up for an Office 365 Developer Site. Follow the instructions in Sign up for an Office 365 Developer Site to start your free trial.

Get your Team Foundation Service account

Team Foundation Service lets you plan projects, collaborate with your team, and manage your code online from anywhere without needing to set up your own Team Foundation server. Instead, it stores your source code and work items in the cloud. You can check your code directly into the cloud through Team Foundation Service using Visual Studio or Eclipse, and you can manage your work items and bugs in the browser.

Team Foundation Service offers a free plan for up to five users per account. It provides features including version control (through Team Foundation Version Control or Git), work item tracking, agile planning tools, feedback management, and build and test management. Go to the Team Foundation Service site to get started. The cloud-hosted build service on Team Foundation Service is preconfigured with the right environment for apps for Office and SharePoint 2013, and also for SharePoint 2010 or 2013 farm and sandboxed solutions.

Note that the build machines on Team Foundation Service can access only public visible SharePoint (and web) servers. This means that your target SharePoint site should be either on Office 365 (for apps) or on a SharePoint virtual machine (VM) in the cloud (for SharePoint farm and sandboxed solutions).

Start your continuous integration on Team Foundation Service

Earlier this year, we shipped Office Developer Tools for Visual Studio 2012 for developing apps for Office and SharePoint 2013. At the same time, we also published a CodePlex project to support continuous integration for Office and SharePoint 2013 projects using TFS 2012: see Office/SharePoint 2013 Continuous Integration with TFS 2012.

This CodePlex project contains a set of Windows PowerShell scripts for deployment and a custom TFS Build workflow template, which lets you build and deploy (for testing purpose) apps for Office and SharePoint 2013 projects using TFS 2012. Here’s all you need to do:

Check the files (deployment scripts and workflow template) into the root of your source control team project.
Update the parameters.ps1 file in the project to specify the parameters used for deployment, including your SharePoint site URL and your credentials.
Create a new build definition using OfficeToolsAppTemplate.xaml, and specify the corresponding deployment scripts offered in the CodePlex project. The build definition also lets you specify what projects to build and when to trigger a build.

For detailed instructions, see the Documentation page of the CodePlex project.

Using these resources, you will be able to do continuous integration for Office and SharePoint 2013 projects. Depending on your project, you may find these tips helpful:

Project contains a NuGet package
If the NuGet package delivers some assemblies that your project references (for example, you use the EntityFramework NuGet package in the web project of your app for SharePoint, which references EntityFramework.dll), make sure the assemblies are checked into source control. You can find the assemblies from the NuGet package in the “packages” folder under your solution folder.
Autohosted app for SharePoint includes a SQL Database project
This is a known issue in the Office Developer Tools for Visual Studio 2012. If you are using Team Foundation Service, the TFS build service will copy the .dacpac file built from the SQL Database project to a different folder defined in the app for SharePoint project target file. To work around this, add the following code at the end of your app project file:

<Target Name="xxx" BeforeTargets="PackageSharePointApp">
    <PropertyGroup>
        <SqlPackage>%OutDir%\YourDacpacName.dacpac</SqlPackage>
    </PropertyGroup>
</Target>

Project is a SharePoint farm or sandboxed solution
Continuous integration is also supported for SharePoint farm and sandboxed solutions. Hosting SharePoint in a VM in Windows Azure is a great way to enable continuous integration with Team Foundation Service because it is hosted outside of a firewall. Check out the Downloads page for instructions about configuration.
Although the build service on Team Foundation Service has been configured with essential SharePoint assemblies, your farm solutions may contain some assemblies that are not available in the default build environment because solutions can actually reference any assembly. In that case, you will need to check those missing assemblies into the source control with your project. You will know that your project is in this state if an assembly that you reference in your SharePoint farm solution cannot be found (and Team Foundation Service throws the “System.IO.FileNotFoundException: Could not load file or assembly” exception when you build the project).

I hope that you will give continuous integration a try. Like always, I’d love to hear from you. If you have a suggestion, question, bug, or anything else, please don’t hesitate to let me know!

Have fun!

Creating a mail app to check out Active Directory org information for mail senders and recipients

angelgolfer — Wed, 15 May 2013 13:00:00 GMT

In an organization or enterprise setting, you frequently get included in emails with unfamiliar people. If your organization uses Active Directory, Exchange Server 2013, and Outlook 2013, you can now use the Who's Who AD mail app to conveniently display organization metadata for email senders and recipients in Outlook or Outlook Web App. Figure 1 is an example of the mail app in action.

Figure 1. Who’s Who AD mail app displaying Active Directory information for the message sender

After installing the mail app, whenever you open a message in Outlook, simply choose Who's Who AD in the app bar and the app pane will display the following organization metadata:

Job title and contact info for the message sender (Belinda Newman in the example)
The sender's manager (Alicia Thornber)
Any direct reports of the sender (Ben Miller, Jeff Price, Robin Wood, and so on).

You can display similar information for each message recipient. You can also drill down on each of the displayed managers and their direct reports.

Behind the scenes, when you select a sender or recipient, the mail app calls the Who web service to get that person’s data from Active Directory. The web service includes a wrapper that uses Active Directory Domain Services (AD DS) to access information from Active Directory. After getting the data, the Who web service serializes the data in JSON format and sends it back as the web service response. The mail app then pulls the data and displays it in the app pane. Figure 2 shows the design and major components of the mail app.

Figure 2. Relationships among the Outlook user, mail app, Who web service, and Active Directory

The Who's Who AD mail app is a prototype you can customize to your needs. Learn more about the mail app design at How to: Create a mail app to display hierarchy information from Active Directory.