Overview of Integrating External Applications with Web Parts
Published: May 2010
This topic provides an overview of how to use Web Parts to integrate non-SharePoint applications into Microsoft SharePoint Foundation Web sites.
Within certain constraints, Web site users with contributor rights can add Web Parts that host non-SharePoint applications, such as Silverlight applications, to their SharePoint Web pages. These applications can even be hosted on servers outside of the domain of the SharePoint Foundation Web application and can read and write SharePoint data, provided that they have been properly registered as an application principal. These Web Parts provide development teams with a means to integrate quickly non-SharePoint applications into the SharePoint Foundation Web sites.
An application is external to a SharePoint Foundation Web application; that is, has a different domain, if the URI of the application’s executable differs from the URI of the Web application in any of four ways described in HTTP Communication and Security with Silverlight: Cross-Domain Communication.
The amount of development work that must be done to integrate an application into SharePoint Foundation varies depending primarily on the following factors.
Whether the application’s executable is hosted within the SharePoint Foundation Web application or in some external domain.
Whether the application needs to read and write SharePoint Foundation data.
Whether the default settings governing how the Web Part is rendered must be changed.
Whether the application needs custom configuration information to run in a SharePoint Foundation Web Part.
Whether a custom UI in SharePoint Foundation is needed to create and edit the properties of the Web Part that hosts the application.
In the simplest cases, the non-SharePoint application is either located within the same domain as the SharePoint Foundation Web application or it is hosted at an external URL but it does not need to access SharePoint data. In either of these situations, there is no required SharePoint development. After the executable is finished, the Web application administrator deploys the application to an application server or a document library. Users who add a Web Part that can host a non-SharePoint application are prompted to supply the URL of the executable when they add the Web Part. If the application is locally deployed, it can access SharePoint Foundation data by using the Managed Client Object Model in the context of the current user. (If the external application is a Silverlight application, it uses the special Silverlight version of the client object model.
If the application will be deployed to a different domain from that of the Web application and if it will need to access SharePoint data, then integration requires the use of Silverlight Cross-Domain Data Access (Silverlight CDA).
The advantage to SharePoint Foundation users of being able to host applications that are in a different domain from the SharePoint Foundation Web application is that many such applications can be hosted on an application server and made available to all Web applications in the server farm. Silverlight CDA enables administrators to control the permissions of the external servers that host the external applications without unduly restricting the ability of users to add Web Parts hosting these applications to Web Part pages. The application logs on to the SharePoint Foundation Web application as a distinct type of user known as an ‘application principal.’ The application’s permissions are the intersection of the permissions that the administrator has granted this special user and the permissions of the real user who has opened the Web page containing the Web Part that hosts the application.
Typically, if an external server hosts more than one application that is being used in SharePoint Foundation, all such applications would use the same application principal user credentials. It is possible to create different application principal users for each application, but nothing can prevent the server from using any of its application principal users for any of its applications.
The following are the critical elements in Silverlight CDA about which developers need to be aware.
Access to SharePoint Foundation data from an application on an external domain must be enabled by a farm administrator by registering an External Application Provider (EAP), and for security reasons this cannot be done in the SharePoint Foundation UI. Instead, it must be done programmatically. You can include instructions about the required code with your solution or supply a small utility for farm administrators to run. For more information about creating this utility code, see How to: Enable an External Application Provider.
The EAP only has to be registered once even when multiple external applications are being used.
You must create some External Application XML markup that will give SharePoint Foundation information it needs about the application. Users who add a Web Part that hosts the application are prompted to supply the markup, so you must make it available to the users. For more information about creating this markup, see How to: Create External Application XML Markup.
The farm administrator must create a user identity under which the external application will login to SharePoint Foundation and this user must be configured as an ‘application principal.’ For security reasons, this configuration cannot be performed in the UI. You must provide a utility that assigns values to certain properties of the SPUser object that logs in on behalf of an application that requires cross-domain access to SharePoint Foundation data. For more information about creating this utility, see How to: Create an Application Principal User. Web site owners who want their contributors to be able to add a Web Part hosting the application will add the application principal as a user on their Web sites.
You must create an HTTP Request Handler that is installed on the external application’s domain. Requests from the external application to a SharePoint Foundation Web application are directed first to this handler, which then forwards them, along with a security hash and user credentials, to the SharePoint Foundation front-end Web server. For more information about creating this handler, see How to: Create an HTTP Request Forwarder for External Applications.
The code in the Silverlight application that reads or writes data to the SharePoint Foundation Web application uses a special Silverlight version of the SharePoint Foundation client object model that is implemented in its own client assemblies. For more information about this object model and programming to it, see Using the Silverlight Object Model and Silverlight Deployment.
Although the above tasks must be done only if the application is in an external domain and it needs access to SharePoint Foundation data, you may want to carry out these tasks, even if one of those conditions is not met. For example, you may want to use External Application XML to customize the width and height of the Web Part.
An EAP is a kind of configuration and provisioning engine for Web Parts that host non-SharePoint applications. It interprets the External Application XML, manages the creation of Web Parts that host the application, and manages the editing of the properties of the Web Parts.
There is a default EAP that is used unless a custom EAP is registered. There can be only one EAP for each SPWebService object in the server farm. So all external applications hosted in Web Parts in all the Web applications that are children of the same Web service are managed by the same EAP. For more information about SPWebService and Web services, see The Services Hierarchy of Microsoft SharePoint Foundation and Background: Service Entities in Microsoft SharePoint Foundation.
You can create a custom EAP and substitute it for the default EAP. Some of the scenarios in which you might want to do this are as follows:
The Web Part that hosts the non-SharePoint application needs a customized tool part that users will employ to edit the properties of the Web Part or to do other work such as automatically create an application principal user for the external application.
The Web Part needs customized chrome.
The Silverlight application, or more precisely, the request forwarder of the application, needs a client hash so that it can verify that query responses received from the SharePoint Foundation front-end Web server have not been tampered with. For more information about request forwarders, see How to: Create an HTTP Request Forwarder for External Applications.
The External Application XML for the Web Part needs to contain custom configuration properties.
Custom logic needs to be executed when the Web Part’s child controls are created.
For more information about creating a custom EAP, see How to: Create a Custom External Application Provider.
A Silverlight Web Part is built-in to SharePoint Foundation. If you want to host another kind of application in a Web Part, you can derive a new Web Part type from ClientApplicationWebPartBase. For more information about creating a Web Part that hosts a non-SharePoint application, see How to: Create a Web Part that Hosts an External Application.