A Web Parts connection is a link or association between two server controls that enables them to share data. A connection always involves exactly two controls: one is the provider of data, and the other is the consumer of the data from the provider. A control can be both a consumer and a provider, and any type of server control, whether a WebPart control, a custom control, or a user control, can be designed to participate in connections. A provider control by default can establish connections with multiple consumers at the same time (like the previous example of a postal code control that provides a postal code to a weather information control, a news headline control, and a business listing control). A consumer control by default can connect to only one provider at a time.

Connections always take place in the context of a Web Parts application, which means that at a minimum, besides the two server controls participating in the connection, two additional controls are required on the Web page. One of them is the WebPartManager control, which is present on every page that contains Web Parts controls. The second required control is a zone that inherits from the WebPartZoneBase class, such as the WebPartZone control. Any two server controls, in order to form a connection, must reside within a WebPartZoneBase type of zone.

In a connection relationship, the consumer and the provider each have at least one associated object called a connection point. Based on the ConnectionPoint class, a connection point contains the details necessary for a server control to connect to another control, such as the type of the control itself, the type of data the control recognizes, an ID for the connection point object, and whether the control can form multiple connections. A server control can have multiple connection points. A provider's connection points are defined by instances of the ProviderConnectionPoint class, and the consumer's are defined by instances of the ConsumerConnectionPoint class.

To form a connection, the consumer and provider must both recognize the same type of data, which in Web Parts connections is passed by means of an interface instance. The type of data that a control recognizes is specified in the control's associated connection point, in the InterfaceType property. If the provider and consumer recognize the same type of data, they are compatible. If a provider and consumer are incompatible, a developer must use a special transformer object to translate the provider's data into a form the consumer can work with. This transformer object inherits from the base WebPartTransformer class, and a developer can either inherit from the base class to develop a custom transformer, or use one of the provided transformer objects (RowToFieldTransformer or RowToParametersTransformer).

After a connection has been created, it is contained in a WebPartConnection object. The connection object encapsulates all the details about a connection, including references to its consumer and provider objects, the IDs of the consumer and provider, references to any connection points and their IDs, references to any transformers associated with the connection, and details about the state of the connection, such as whether it is active and whether it is static or dynamic.

You can provide users with a way to create and manage connections by using the ConnectionsZone control. You can declare an <asp:connectionszone> element on a Web page, which provides users with a run-time UI that allows them to connect or disconnect controls, and to configure certain connection details.

Web Parts connections are based on a "pull" model of connectivity, where the consumer gets data from the provider. To create a connection, a control acting as a data provider defines a communication contract indicating the data it can provide. Another control, acting as the consumer and with knowledge of the communication contract, retrieves that data.

The mechanism for establishing a connection is a special callback method: one in the consumer and one in the provider. However, the Web Parts control set handles all the callback and communication details, so the steps required of developers are minimal. As a developer, if you want to use the simplest approach, all you have to do is select a method in the provider to use as the callback method, and mark it in the source code with a ConnectionProvider attribute. Then within that method, return the interface instance containing the data to pass to the consumer. The interface instance can be very simple (for example, a single property that contains a string value such as a postal code). A provider can implement one of the provided interfaces (IWebPartField, IWebPartRow, or IWebPartTable), but in most cases it is preferable to create a simple, custom interface with one or more properties or methods containing the data you want to share with a consumer, and implement that interface in the provider. The consumer's callback method retrieves the instance of the interface from the provider. Again, all that is required of a developer is to identify which method in the consumer (using a ConnectionConsumer attribute) will retrieve the interface instance, and assign it to some internal variable for processing and rendering. Note that the data from the provider is passed during the prerendering phase of the page and control cycle, so you should plan to process the data and update any logic in the consumer after prerendering is complete.

Note
As mentioned previously, the consumer and provider must be compatible with regard to the interface type, or else they must use a WebPartTransformer object to establish the connection.

The pipelines through which data is exchanged are the connection points for the consumer and provider. You can create a connection point for a control in several ways. As mentioned in the preceding paragraph, you can use the ConnectionConsumerAttribute or ConnectionProviderAttribute classes, which each create a connection point for you. In this approach, you can add a ConnectionConsumer attribute to the consumer's callback method in the source code, and similarly add a ConnectionProvider attribute to the provider's callback method. This identifies the respective callback methods, and allows you to specify some details about the connection point, such as an ID and a display name (which appears in the UI for users to form connections). As another alternative, you can create a custom connection point by inheriting from ConnectionPoint, or you can use or inherit from the ConsumerConnectionPoint or ProviderConnectionPoint classes. As noted previously, a control acting as either a consumer or a provider can have multiple connection points.

A connection between controls can be either static or dynamic. Static connections are coded declaratively in the hosting page and created during the prerendering phase of the page. This ensures that the connection is active when a user views the page. For an example, see How to: Declare a Static Connection between Two Web Parts Controls. Dynamic connections can be created either programmatically in the control's code or declaratively on the hosting page. If you declare two compatible server controls within a WebPartZoneBase zone on a Web page, and declare an instance of the ConnectionsZone control on the page, users can create and configure a dynamic connection between the controls at run time.

Connections contrast in several ways with the other ASP.NET techniques for transferring information between controls in a Web application:

• Connections are a feature of Web Parts. You can only connect controls that are designed for Web Parts connections and that reside within a WebPartZoneBase zone.

  Note
  As noted previously, any ASP.NET server control, custom control, or user control can be used as a Web Parts control to take advantage of connections.

• Connections are different from data binding. Connections between controls in a Web Parts zone use an interface to create a contract between the controls. Data binding is a connection between a control and a storage device or back-end database. Web Parts connections move data only between controls on a page.

• Connections can be personalized. Connection settings that indicate which controls are connected can be safely stored with other personalization data. For more information on personalization, see Web Parts Personalization Overview.

The following table shows three components in the Web Parts control set that are essential to connections, and that you work with directly or indirectly whenever you use connections.

Tasks

Reference

Concepts