I have found Web Service Controllers in Office Add-ins to be quite useful. There are a number of reasons you might want to keep functions of your add-in on a server, including obfuscation, complex calculation, data intense, service mashups, and much more. However, every time you want to use your Web Ser4vice from the JavaScript interface, there is a lot of code associated with the AJAX call you have to make. This begs for simplicity and that is what I have done. In my App.js project, I added a simple makeAjaxCall function that takes the command you want to invoke, the parameters you want to pass it (as an array) a callback when the call is complete and a callback if there was an error. Here is the core code for the makeAjaxCall() method:
[code lang=”javascript” collapse=”true” title=”click to expand if the docs.com embedding below is not visible.”]
// Helper function to call the web service controller
app.makeAjaxCall = function (command, params, callback, error) {
var dataToPassToService = {
Command: command,
Params: params
};
$.ajax({
url: ‘../../api/WebService’,
type: ‘POST’,
data: JSON.stringify(dataToPassToService),
contentType: ‘application/json;charset=utf-8’
}).done(function (data) {
callback(data);
}).fail(function (status) {
error(status);
})
};
[/code]
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
// Helper function to call the web service controller | |
app.makeAjaxCall = function (command, params, callback, error) { | |
var dataToPassToService = { | |
Command: command, | |
Params: params | |
}; | |
$.ajax({ | |
url: '../../api/WebService', | |
type: 'POST', | |
data: JSON.stringify(dataToPassToService), | |
contentType: 'application/json;charset=utf-8' | |
}).done(function (data) { | |
callback(data); | |
}).fail(function (status) { | |
error(status); | |
}) | |
}; |
Here is a sample of my web service controller:
[code lang=”javascript” collapse=”true” title=”click to expand if the docs.com embedding below is not visible.”]
/// <summary>
/// CORE SERVICE FUNCTION
/// This function will take a web request which will contain the command the caller wants
/// to initate and then the paramaters needed for that call. We enter a SELECT statement
/// below to determine the command given and we then call the proper helper function
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
[HttpPost()]
public WebServiceResponse WebService(WebServiceRequest request)
{
WebServiceResponse response = null;
switch(request.Command)
{
case "DoFunctionA":
return functionA(request.Params);
case "DoFunctionB":
return functionB(request.Params);
case "DoFunctionC":
return functionC(request.Params);
case "DoFunctionD":
return functionD(request.Params);
}
response = new WebServiceResponse();
response.Message = "Unknown command";
return response;
}
[/code]
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/// <summary> | |
/// CORE SERVICE FUNCTION | |
/// This function will take a web request which will contain the command the caller wants | |
/// to initate and then the paramaters needed for that call. We enter a SELECT statement | |
/// below to determine the command given and we then call the proper helper function | |
/// </summary> | |
/// <param name="request"></param> | |
/// <returns></returns> | |
[HttpPost()] | |
public WebServiceResponse WebService(WebServiceRequest request) | |
{ | |
WebServiceResponse response = null; | |
switch(request.Command) | |
{ | |
case "DoFunctionA": | |
return functionA(request.Params); | |
case "DoFunctionB": | |
return functionB(request.Params); | |
case "DoFunctionC": | |
return functionC(request.Params); | |
case "DoFunctionD": | |
return functionD(request.Params); | |
} | |
response = new WebServiceResponse(); | |
response.Message = "Unknown command"; | |
return response; | |
} |
And here is how you call it:
[code language=”javascript”]
app.makeAjaxCall("DoFunctionA", ["Value1", "Value2"], function (data) {
var result = $.parseJSON(data.Message);
// do something with the retuirned result here…
});
[/code]
For more information on how to create a Web Service controller, there is a great blog post from a colleague of mine, Michael Zlatkovsky on how to do this:
Create a web service for an app for Office using the ASP.NET Web API