System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint Class

Defines a connection point object that enables a server control acting as a consumer to form a connection with a provider.

See Also: ConsumerConnectionPoint Members


public class ConsumerConnectionPoint : ConnectionPoint


In every Web Parts connection between two server controls, each control must have (among other requirements) an associated connection point object that enables it to connect to the other control and to either provide or consume data, depending on whether the control is designated as the provider or consumer for the connection. A System.Web.UI.WebControls.WebParts.ConnectionPoint object in general contains the details for how a control can connect to another control and the type of data it can share. For a control acting as the consumer in a connection, its connection point must be a System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint object. For details on Web Parts connections and connection points, read the topics listed in the See Also section below.

To create a System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint object, several steps are required:

[The 'ordered' type of list has not been implemented in the ECMA stylesheet.]

After a control has been equipped to act as a consumer, the control can participate in connections (assuming that a provider control is also equipped and available). To create a static, declarative connection in the markup of a Web page, developers can use the <asp:webpartconnection> element. If the ConnectionConsumer attribute in the consumer source code that identifies the callback method specifies an ID for the connection point, then that value must be assigned to the ConsumerConnectionPointID attribute in the <asp:webpartconnection> element on a page. A reason that a developer might specify an ID for a consumer connection point is if there are multiple connection points defined in the consumer control. If an ID is not specified for the consumer connection point in the consumer control, a value does not have to be assigned to the ConsumerConnectionPointID attribute in the page either, because the connection will be created using a default value obtained from the ConnectionPoint.DefaultID field.

To create a connection in code, developers must create a new System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint object by calling the WebPartManager.GetConsumerConnectionPoints(WebPart) method and passing to it the ID of the consumer control, along with the ID or index of the defined System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint object in the consumer control. The returned System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint object, along with a reference to the consumer control, a reference to the provider control, and a corresponding System.Web.UI.WebControls.WebParts.ProviderConnectionPoint object, are all passed to the WebPartManager.ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint) method to create a new System.Web.UI.WebControls.WebParts.WebPartConnection object.

Although developers can use consumer connection points as part of establishing connections either declaratively or programmatically, users can also interact with consumer connection points to establish connections through the user interface (UI). If developers declare a System.Web.UI.WebControls.WebParts.ConnectionsZone control on a Web page, it provides a run-time UI for users to create connections. If users choose the provider control as the starting point for establishing the connection by clicking its connect verb (they could also choose the consumer; there is no difference in the resulting connection), in the UI they will see a drop-down list control with the display names of the available consumer connection point (or points if there are multiple ones) that the provider can send the data to. Users must select a consumer connection point to establish a connection.

A System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint object associates directly with a specific consumer control, and stores details about a connection in the properties it inherits from the base System.Web.UI.WebControls.WebParts.ConnectionPoint class. For example, in the inherited ConnectionPoint.InterfaceType property, a consumer connection point keeps the type of interface it uses. If the provider and consumer in a connection both understand the interface type, the controls are compatible and capable of forming a direct connection. If the provider and consumer cannot work with the same interface type, they are incompatible and must use a System.Web.UI.WebControls.WebParts.WebPartTransformer object to translate the provider connection point's ConnectionPoint.InterfaceType property into a type that the consumer can work with. Another important inherited property is the ConnectionPoint.DisplayName property, which provides a friendly name to display in the UI for users to choose a consumer connection point when creating connections. The display name is the required parameter when developers add a ConnectionConsumer attribute to the callback method in a consumer control. The inherited ConnectionPoint.ID property is also useful, as indicated above, because it provides a unique identifier for a consumer connection point in the event that a consumer has multiple connection points. A consumer can have multiple System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint objects defined in it, and in this case, when developers add the ConnectionConsumer attribute to a method, they should specify an ID value to distinguish each connection point. One other notable inherited property is the ConnectionPoint.AllowsMultipleConnections property, which indicates whether a consumer connection point can connect simultaneously to multiple providers. This property value is false by default for consumer connection points (whereas it defaults to true for provider connection points).

The System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint class adds several unique methods to the members it inherits from the System.Web.UI.WebControls.WebParts.ConnectionPoint class. The ConsumerConnectionPoint.SetObject(System.Web.UI.Control, object) method invokes the consumer's own defined callback method to retrieve the interface instance from the provider. The ConsumerConnectionPoint.SupportsConnection(System.Web.UI.Control, ConnectionInterfaceCollection) method returns a Boolean value that indicates whether the connection point is able to establish connections, based on the current state of the associated consumer control.


Namespace: System.Web.UI.WebControls.WebParts
Assembly: System.Web (in System.Web.dll)
Assembly Versions:
Since: .NET 2.0