Creating .NET Connectivity Assemblies and Web Services
Applies to: SharePoint Server 2010
In this article
Design Best Practices
Implementation Steps
Defining Stereotyped Operations in Your Service
Best Practices for Writing .NET Connectivity Assemblies and Web Services
Microsoft Business Connectivity Services (BCS) enables you to bring external data from various types of external systems into Microsoft SharePoint 2010 and Microsoft Office 2010 applications. These external systems include the following:
Databases
Web services
If your external system is not directly supported by Business Connectivity Services, you can expose your external system via Business Connectivity Services by writing code. If the entities in the external system are static and do not change often and have a small set of known types, you can write Web services or .NET Connectivity Assemblies to expose the data from your external system in the format Business Connectivity Services best understands. On the other hand, if the entities are dynamic, have custom types, and are large scale, consider creating a custom connector for that data source type. However, you must handle the connection, data transfer, setup, and tools for a custom connector. For more information, see Differences Between Using the .NET Assembly Connector and Writing a Custom Connector.
The following figure is a high-level architecture diagram of Microsoft Business Connectivity Services (BCS). It shows the different connectors provided by Business Connectivity Services and how the .NET assembly, Web service, and the custom connectors fit into the overall architecture.
.gif "High-level architecture of BCS")
This topic describes the best practices for writing .NET Connectivity Assemblies and Web Services. After you have a Web service or a .NET Connectivity Assembly, you can use Microsoft SharePoint Designer 2010 to connect to it and discover external content types.
The following table compares and contrasts the two approaches.
Table 1. Approaches for writing .NET Connectivity Assemblies or Web Services
Web Service |
.NET Connectivity Assembly |
|
|---|---|---|
Implementation Technology |
Can be any SOAP 1.1 or SOAP 1.2 compliant Web service. Examples: ASP.NET Web service, WCF Web Service End Point |
Microsoft .NET Framework 3.5 |
Hosting |
Business Connectivity Services will not host the Web service. You must host the service. |
Hosting is not necessary for a .NET Connectivity Assembly. You can simply deploy the .NET Connectivity Assembly to the BDC Metadata Store and Business Connectivity Services will take care of the rest. |
Tool Support |
You can use a development tool such as Microsoft Visual Studio to write your Web service. No special project templates or tools are provided to create Web services for Business Connectivity Services in Visual Studio. |
You can use a development tool such as Microsoft Visual Studio to write your .NET Connectivity Assembly. Microsoft Visual Studio 2010 provides a new project template named Business Data Connectivity Model that comes with a set of visual designers and code management capabilities to enable you to easily create, debug, and deploy .NET Connectivity Assemblies and the associated model to Business Connectivity Services. |
Authentication Support |
For Web services, Business Connectivity Services supports the following authentication mechanisms: Passthrough, RevertToSelf, WindowsCredentials, Credentials, and DigestCredentials. See Available Authentication Modes for more information. |
In a .NET Connectivity Assembly, you must handle the security and authentication. If you want to use the Secure Store Service, you can use the Secure Store object model to programmatically store and get credentials. Alternatively, you can also use the Username/Password filter to fetch the user name and password. |
Types |
In a .NET Connectivity Assembly, you can use .NET types that are not available in Web services. Example: Non-serialized types. |
Design Best Practices
Regardless of whether you are creating a Web service or a .NET Connectivity Assembly, in the code you are writing, you will connect to the external system, define the external content types needed in the external system, and include the code required to perform each stereotyped operation (method instances) you want to support for each of the external content types.
And because you are writing code in the Web service and the .NET Connectivity Assembly, the options of where you can get your data and what you can do with it before it gets to Business Connectivity Services and SharePoint are many. In the code, you can perform actions such as aggregating data from multiple sources, applying transformations and business logic, and handling custom security schemes.
Note
The key to writing Web services and .NET Connectivity Assemblies is to think in terms of external content types and ensure that the Web methods in the Web service and the methods in the .NET Connectivity Assembly match the stereotyped operations supported by the BDC. This is also to ensure that Microsoft SharePoint Designer 2010 is able to connect to the Web service and the .NET Connectivity Assembly and, therefore, provide a discover-and-use approach for creating external content types after you have created and published the service.
For example, in a Web service, ensure that there is one Web method for each stereotyped operation you want to support for your external content type and its signature matches with the recommended method signature for the stereotyped operations (see the following section).
Similarly, in a .NET Connectivity Assembly, ensure that you have methods in your .NET code for each stereotyped operation required for your external content type. Business Connectivity Services will call these methods at run time when a user performs an action on the external content type, such as read an item or update an item.
Implementation Steps
Typically, in a .NET Connectivity Assembly, each external content type will map to a class and each stereotyped operation will be a method inside the class. In a Web service, each stereotyped operation will be a Web method.
.NET Connectivity Assembly
In a .NET Connectivity Assembly, for each external content type, create a class and define the fields it should contain. Always include an identifier for the external content type. Usually, this is the primary key in a database table. BDC supports up to 20 field compound identifier.
Create another class and add methods to it to define the stereotyped operations you want to support for each external content type. For an example, see Defining Stereotyped Operations in Your Service later in this topic.
Web Service
Web service development usually begins with the definition of complex types. Define the structure of each external content type. Again, ensure that you always include an identifier for the external content type. Usually this is the primary key in a database table. BDC supports up to 20 field compound identifier.
Define Web methods for each stereotyped operation you want to support for your external content types. For an example, see the Defining Stereotyped Operations in Your Service section.
Defining Stereotyped Operations in Your Service
The stereotyped operations you implement will depend on your requirements. The following table lists the stereotyped operations we recommend you implement for the most common requirements.
Requirement |
Stereotyped Operations |
Comments |
|---|---|---|
Read external items |
SpecificFinder and Finder method instances. These are required for all of the Business Connectivity Services client features. Consider BulkSpecificFinder, IDEnumerator, BulkIDEnumerator, ChangedIDEnumerator, and DeletedIDEnumerator for optimized data synchronization to client computers. This can become critical in scenarios where a many users or large data volumes must be taken offline. |
|
Write back external items |
Creator, Updater, and Deleter method instances if Create, Update, and Delete operations are desired on the external content type. |
If the external system does not support write-back, then mark all the fields of the external content type as read-only. If you are creating declarative or advanced code-based solutions in Outlook based on the external content type, mark the Outlook folder as read-only as well. |
Related external items |
AssociationNavigator Associator Disassociator BulkAssociationNavigator, BulkAssocatedIDEnumerator |
Associator and Disassociator are used only for foreign key-less associations. See the Microsoft.BusinessData.MetadataModel.IAssoication class for more information. |
Search |
IDEnumerator and BulkIDEnumerator AccessChecker BinarySecurityDescriptorAccessor |
|
Offlining to client |
The Finder and SpecificFinder methods must return the same set of fields or there will be a performance impact. If the Finder and SpecificFinder methods return different sets of fields, then users will not be able to take the external content type offline to Microsoft Office 2010 clients. |
When they are offline, if there is complex filtering logic used, you may not get the result sets you would get when you are online. |
BLOB data |
StreamAccessor |
Best Practices for Writing .NET Connectivity Assemblies and Web Services
When writing .NET connectivity Assemblies and Web services, consider the following best practices:
Include identifiers. Ensure that you always include an identifier for each external content type. Usually, this is the primary key in a database table. BDC supports up to 20 field compound identifier.
Handle null values. Usually the Read operation queries the external system and then fills the type to be returned. Ensure that you properly handle null values in the SpecificFinder method. Chances are that some fields are null in the external system (such as hobbies or address). Having proper error and exception handling is essential. Therefore, check for null and empty strings in your code and then fix them in the code. Also, consider using NormalizeString interpretation on type descriptors.
Match parameter names. The names of the parameters must match what is in the external system. If the names of the parameters are not uppercase identical on all the methods, then SharePoint Designer 2010 interprets them as different fields.
Handle exceptions. Ensure that you handle exceptions properly. Anticipate operation failures and raise exceptions.
If a method should return a single item (for example, specific finder), and the requested item is not found, the code should do the following:
Return null. This is the simplest way to go, and will be the most compatible.
Throw ObjectNotFoundException. This exception is useful only if there is a specific message you want to log. Avoid throwing this exception for Web services.
Throw ObjectDeletedException. This exception should only be used when the object is known to be deleted. Avoid throwing this exception for Web services.
Not throw other exceptions.
Not return incomplete or fake data.
If a method is supposed to return multiple items (for example, finder), and there are no items found, the code should do the following:
Return an empty collection/enumeration of items. This is preferred.
Return null.
Not throw any exceptions.
If a method does not have a return value (for example, update), and there is a problem with the update, the code should do the following:
Throw an exception.
Not rely on return values or error codes. BDC does not currently have a way to interpret these values.
For more information, see Implementing Stereotyped Operations in Your Methods.
See Also
Tasks
How to: Publish a .NET Connectivity Assembly to the BDC Metadata Store
Concepts
How to: Create a .NET Connectivity Assembly
How to: Use the Secure Store Service from within a .NET Connectivity Assembly