The Claims, Azure and SharePoint Integration Toolkit Part 4
This is part 4 of a 5 part series on the CASI (Claims, Azure and SharePoint Integration) Kit.
· Part 1: an introductory overview of the entire framework and solution and described what the series is going to try and cover.
· Part 2: the guidance part of the CASI Kit. It starts with making WCF the front end for all your data – could be datasets, Xml, custom classes, or just straight up Html. In phase 1 we take your standard WCF service and make it claims aware – that’s what allows us to take the user token from SharePoint and send it across application or data center boundaries to our custom WCF applications. In phase 2 I’ll go through the list of all the things you need to do take this typical WCF application from on premises to hosted up in Windows Azure. Once that is complete you’ll have the backend in place to support a multi-application, multi-datacenter with integrated authentication.
· Part 3: describes the custom toolkit assembly that provides the glue to connect your claims-aware WCF application in the cloud and your SharePoint farm. I’ll go through how you use the assembly, talk about the pretty easy custom control you need to create (about 5 lines of code) and how you can host it in a page in the _layouts directory as a means to retrieve and render data in web part. The full source code for the sample custom control and _layouts page will also be posted.
· Part 4: the web part that I’m including with the CASI Kit. It provides an out of the box, no-code solution for you to hook up and connect with an asynchronous client-side query to retrieve data from your cloud-hosted service and then display it in the web part. It also has hooks built into it so you can customize it quite a bit and use your own JavaScript functions to render the data.
· Part 5: a brief walk-through of a couple of sample applications that demonstrate some other scenarios for using the custom control you build that’s described in part 3 in a couple of other common scenarios. One will be using the control to retrieve some kind of user or configuration data and storing it in the ASP.NET cache, then using it in a custom web part. The other scenario will be using the custom control to retrieve data from Azure and use it a custom task; in this case, a custom SharePoint timer job. The full source code for these sample applications will also be posted.
In this post I’ll cover the web part that is included as part of this framework. It’s designed specifically to work with the custom control you created and added to the layouts page in Part 3.
Using the Web Part
Before you begin using the web part, it obviously is assumed that you a) have a working WCF service hosted in Windows Azure and b) that you have created a custom control and added it to the layouts page, as described in Part 3 of this series. I’m further assuming that you have deployed both the CASI Kit base class assembly and your custom control assembly to the GAC on each server in the SharePoint farm. I’m also assuming that your custom aspx page that hosts your custom control has been deployed to the layouts directory on every web front end server in the farm. To describe how to use the web part, I’m going to use the AzureWcfPage sample project that I uploaded and attached to the Part 3 posting. So now let’s walk through how you would tie these two things together to render data from Azure in a SharePoint site.
NOTE: While not a requirement, it will typically be much easier to use the web part if the WCF methods being called return HTML so it can be displayed directly in the page without further processing.
The first step is to deploy the AzureRender.wsp solution to the farm; the wsp is included in the zip file attached to this posting. It contains the feature that deploys the Azure DataView WebPart as well as jQuery 1.4.2 to the layouts directory. Once the solution is deployed and feature activated for a site collection, you can add the web part to a page. At this point you’re almost ready to begin rendering your data from Azure, but there is a minimum of one property you need to set. So next let’s walk through what that and the other properties are for the web part.
Web Part Properties
All of the web part properties are in the Connection Properties section. At a minimum, you need to set the Data Page property to the layouts page you created and deployed. For example, /_layouts/AzureData.aspx. If the server tag for your custom control has defined at least the WcfUrl and MethodName properties, then this is all you need to do. If you did nothing else the web part would invoke the page and use the WCF endpoint and method configured in the page, and it would take whatever data the method returned (ostensibly it returns it in HTML format) and render it in the web part. In most cases though you’ll want to use some of the other web part properties for maximum flexibility, so here’s a look at each one:
· Method Name* – the name of the method on the WCF application that should be invoked. If you need to invoke the layouts page with your own javascript function the query string parameter for this property is “methodname”.
· Parameter List* – a semi-colon delimited list of parameters for the WCF method. As noted in Parts 2 and 3 of this series, only basic data types are supported – string, int, bool, long, and datetime. If you require a more complex data type then you should deserialize it first to a string then call the method, and serialize it back to a complex type in the WCF endpoint. If you need to invoke the layouts page with your own javascript function the query string parameter for this property is “methodparams”.
· Success Callback Address – the javascript function that is called back after the jQuery request for the layouts page completes successfully. By default, this property uses the javascript function that ships with the web part. If you use your own function, the function signature should look like this: function yourFunctionName(resultData, resultCode, queryObject). For more details see the jQuery AJAX documentation at https://api.jquery.com/jQuery.ajax/.
· Error Callback Address – the javascript function that is called back if the jQuery request for the layouts page encounters an error. By default, this property uses the javascript function that ships with the web part. If you use your own function, the function signature should look like this: function yourFunctionName(XMLHttpRequest, textStatus, errorThrown). For more details see the jQuery AJAX documentation at https://api.jquery.com/jQuery.ajax/.
· Standard Error Message – the message that will be displayed in the web part if an error is encountered during the server-side processing of the web part. That means it does NOT include scenarios where data is actually being fetched from Azure.
· Access Denied Message* – this is the Access Denied error message that should be displayed if access is denied to the user for a particular method. For example, as explained in Part 2 of this series, since we are passing the user’s token along to the WCF call, we can decorate any of the methods with a PrincipalPermission demand, like “this user must be part of the Sales Managers” group. If a user does not meet a PrincipalPermission demand then the WCF call will fail with an access denied error. In that case, the web part will display whatever the Access Denied Message is. Note that you can use rich formatting in this message, to do things like set the font bold or red using HTML tags (i.e. <font color='red'>You have no access; contact your admin</font>). If you need to invoke the layouts page with your own javascript function the query string parameter for this property is “accessdenied”.
· Timeout Message* – this is the message that will be displayed if there is a timeout error trying to execute the WCF method call. It also supports rich formatting such as setting the font bold, red, etc. If you need to invoke the layouts page with your own javascript function the query string parameter for this property is “timeout”.
· Show Refresh Link – check this box in order to render a refresh icon above the Azure data results. If the icon is clicked it will re-execute the WCF method to get the latest data.
· Refresh Style – allows you to add additional style attributes to the main Style attribute on the IMG tag that is used to show the refresh link. For example, you could add “float:right;” using this property to have the refresh image align to the right.
· Cache Results – check this box to have the jQuery library cache the results of the query. That means each time the page loads it will use a cached version of the query results. This will save round trips to Azure and result in quicker performance for end users. If the data it is retrieving doesn’t change frequently then caching the results is a good option.
· Decode Results* – check this box in case your WCF application returns results that are HtmlEncoded. If you set this property to true then HtmlDecoding will be applied to the results. In most cases this is not necessary. If you need to invoke the layouts page with your own javascript function the query string parameter for this property is “encode”.
· Show Debug Information – check this box to have the web part output debugging information along with the data to help troubleshoot issues. Note that this will not do anything if the ReturnDiagnosticsInformation property of the user control is set to false.
* – these properties will be ignored if the custom control’s AllowQueryStringOverride property is set to false.
Typical Use Case
Assuming your WCF method returns HTML, in most cases you will want to add the web part to a page and set two or three properties: Data Page, Method Name and possibly Parameter List.
If you have more advanced display or processing requirements for the data that is returned by Azure then you may want to use a custom javascript function to do so. In that case you should add your javascript to the page and set the Success Callback Address property to the name of your javascript function. If your part requires additional posts back to the WCF application, for things such as adds, updates or deletes, then you should add that into your own javascript functions and call the custom layouts page with the appropriate Method Name and Parameter List values; the query string variable names to use are documented above. When invoking the ajax method in jQuery to call the layouts page you should be able to use an approach similar to what the web part uses. The calling convention it uses is based on the script function below; note that you will likely want to continue using the dataFilter property shown because it strips out all of the page output that is NOT from the WCF method:
$.ajax({
type: "GET",
url: "/_layouts/SomePage.aspx",
dataType: "text",
data: "methodname=GetCustomerByEmail&methodparams=steve@contoso.local",
dataFilter: AZUREWCF_azureFilterResults,
success: yourSuccessCallback,
error: yourErrorCallback
});
Try it Out!
You should have all of the pieces now to try out the end to end solution. Attached to this posting you’ll find a zip file that includes the solution for the web part. In the next and final posting in this series, I’ll describe how you can also use the custom control developed in Part 2 to retrieve data from Azure and use it in ASP.NET cache with other controls, and also how to use it in SharePoint tasks – in this case a custom SharePoint timer job.
UPDATED 3/6/2011: Support was added for hosting multiple CASI Kit web parts on a single page. Doing so required upgrading to jQuery 1.5.1. You will need to retract and redeploy the web part if you want to take advantage of this new functionality; when you deploy it will automatically copy jQuery 1.5.1 to the _layouts directory.