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 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:
· 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.
· 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.
· 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.
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.
You can download the attachment here: