ConsumerConnectionPoint Class


The .NET API Reference documentation has a new home. Visit the .NET API Browser on to see the new experience.

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

Namespace:   System.Web.UI.WebControls.WebParts
Assembly:  System.Web (in System.Web.dll)


type ConsumerConnectionPoint = 
        inherit ConnectionPoint

System_CAPS_pubmethodConsumerConnectionPoint(MethodInfo, Type, Type, String, String, Boolean)

Initializes a new instance of the ConsumerConnectionPoint class.


Gets a value that indicates whether a connection point supports multiple simultaneous connections.(Inherited from ConnectionPoint.)


Gets the Type of the server control with which a connection point is associated.(Inherited from ConnectionPoint.)


Gets a string that serves as a friendly display name to represent a connection point in the user interface (UI). (Inherited from ConnectionPoint.)


Gets a string that contains the identifier for a connection point.(Inherited from ConnectionPoint.)


Gets the type of the interface used by a connection point.(Inherited from ConnectionPoint.)


Determines whether the specified object is equal to the current object.(Inherited from Object.)


Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)


Returns a value that indicates whether a connection point can participate in connections. (Inherited from ConnectionPoint.)


Serves as the default hash function. (Inherited from Object.)


Gets the Type of the current instance.(Inherited from Object.)


Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodSetObject(Control, Object)

Invokes the callback method in a consumer control and retrieves the interface instance from a provider control.

System_CAPS_pubmethodSupportsConnection(Control, ConnectionInterfaceCollection)

Determines whether a consumer connection point is currently capable of establishing a connection.


Returns a string that represents the current object.(Inherited from Object.)

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 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 ConsumerConnectionPoint object. For details on Web Parts connections and connection points, read the topics listed in the See Also section below.

To create a ConsumerConnectionPoint object, several steps are required:

  1. Enable a consumer control to reference an interface instance. A WebPart or other server control (any type of server control that will be added to a WebPartZoneBase zone can be used) must be able to consume data from a specific interface instance. The control need not implement the interface; only the provider must implement it. The consumer can either work with the exact interface type served by a provider or, if it does not, a WebPartTransformer object can be used to transform data from a provider's interface type to a type understood by the consumer. A typical way to enable a consumer is to declare a private field to contain a reference to the desired interface type.

  2. Identify a callback method. A method in the consumer must be identified as the callback method to establish a connection with the provider. This method retrieves an instance of the interface that the provider implements, and assigns it to (for example) the private field created in the first step. The Web Parts approach for identifying a callback method in the consumer is to add a ConnectionConsumer metadata attribute (defined by the ConnectionConsumerAttribute class) to the method that receives the interface instance. When the attribute is added, the only required parameter is a display name to use for the consumer connection point. Optional parameters can also be added, such as an ID.

  3. Process and output the data from the interface instance. Perform any internal processing as needed on the data, and then typically a consumer control will render the data to the page. A common way of doing this is to override the control's OnPreRender method.


    During a synchronous request, a consumer should request data directly from the provider during or immediately after the PreRender event. During an asynchronous request, if the provider's callback method is not called at any point during rendering, the developer can assume that no data was sent to the consumer.

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 DefaultID field.

To create a connection in code, developers must create a new ConsumerConnectionPoint object by calling the GetConsumerConnectionPoints method and passing to it the ID of the consumer control, along with the ID or index of the defined ConsumerConnectionPoint object in the consumer control. The returned ConsumerConnectionPoint object, along with a reference to the consumer control, a reference to the provider control, and a corresponding ProviderConnectionPoint object, are all passed to the ConnectWebParts method to create a new 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 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 ConsumerConnectionPoint object associates directly with a specific consumer control, and stores details about a connection in the properties it inherits from the base ConnectionPoint class. For example, in the inherited 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 WebPartTransformer object to translate the provider connection point's InterfaceType property into a type that the consumer can work with. Another important inherited property is the 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 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 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 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 ConsumerConnectionPoint class adds several unique methods to the members it inherits from the ConnectionPoint class. The SetObject method invokes the consumer's own defined callback method to retrieve the interface instance from the provider. The SupportsConnection 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.

The following code example shows simple ways to create a connection declaratively, programmatically, or through the UI, in each case making use of a consumer connection point.

The example has four parts:

  • A user control that enables you to change the Web Parts display mode on a page.

  • Source code for an interface and two WebPart controls acting as the provider and the consumer for a connection.

  • A Web page to host all the controls and run the code example.

  • An explanation of how to run the example page.

The first part of this code example is the user control that enables users to change display modes on a Web page. Save the following source code to an .ascx file, giving it the file name that is assigned to the Src attribute of the Register directive for this user control, which is near the top of the hosting Web page. For details about display modes and a description of the source code in this control, see Walkthrough: Changing Display Modes on a Web Parts Page.

No code example is currently available or this language may not be supported.

The second part of the code example is the source code for the interface and controls. The source file contains a simple interface named IZipCode. There is also a WebPart class named ZipCodeWebPart that implements the interface and acts as the provider control. The other WebPart class is named WeatherWebPart, and it acts as the consumer for the connection. This class has a method named GetZipCode that gets an instance of the IZipCode interface from the provider control. Note that this method is marked as the consumer's connection point method with a ConnectionConsumer attribute in its metadata. This is the mechanism for identifying the connection point method in the consumer control.

For the code example to run, you must compile this source code. You can compile it explicitly and put the resulting assembly in your Web site's Bin folder or the global assembly cache. Alternatively, you can put the source code in your site's App_Code folder, where it will be dynamically compiled at run time. This code example uses dynamic compilation. For a walkthrough that demonstrates how to compile, see Walkthrough: Developing and Using a Custom Web Server Control.

No code example is currently available or this language may not be supported.

The third part of the code example is the Web page. Near the top are Register directives to register the custom controls that form the connection, and the user control that enables users to change display modes on the page. The connection itself is created declaratively within the <staticconnections> element on the page. This demonstrates one way of creating a connection--note the ConsumerConnectionPointID attribute in the <asp:webpartconnection> element. You can also create the connection programmatically; the code for doing that is in the Button1_Click method. In this case, a ConsumerConnectionPoint object is created and then passed to a method that creates the actual connection. Whether the connection is created declaratively or programmatically, connection points must always be specified for both the provider and the consumer. The Button2_Click method accesses the ConnectionPoint objects for both the provider and the consumer, and writes some of their property values to a label in the page.

No code example is currently available or this language may not be supported.

After you load the page in a browser, click the Connection Point Details button. Information about the provider and consumer connection points established in the declarative connection appears. Next, use the Display Mode drop-down control to switch the page into connect mode. On the verbs menu of the ZIP Code ProviderWebPart control (represented by a downward arrow in the title bar), click the connect verb. The connection UI appears, created automatically by the <asp:connectionszone> control declared in the page. This is another way of creating a connection (through the UI), along with the declarative and programmatic methods discussed earlier. Click the Disconnect button to terminate the existing static connection. Click the Create a Connection to a Consumer link. The UI now displays a drop-down control that lists the consumer connection point display name. Select the connection point in the drop-down list, and then click Connect to complete the connection. Next, click Disconnect again. Click the Dynamic Connection button to create a connection programmatically. Use the Display Mode control to return the page to browse mode. Click the Connection Point Details button again, to indicate details about the consumer connection point object once more.

The example has demonstrated establishing a connection and using a consumer connection point in three ways: a static connection declared in the Web page markup; a connection created in code that used a ConsumerConnectionPoint object; and a connection created by a user through the connection UI.

.NET Framework
Available since 2.0

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top