WebPartManager.ConnectWebParts Method

Reference

Definition

Namespace:: System.Web.UI.WebControls.WebParts

Assembly:: System.Web.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Creates a connection between two WebPart controls (or other server controls capable of forming connections) that reside in a WebPartZoneBase zone.

Overloads

ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint)	Creates a connection between two WebPart or GenericWebPart controls using only the references to the controls and their specified ConnectionPoint objects.
ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint, WebPartTransformer)	Creates a connection between two WebPart or GenericWebPart controls using the references to the controls, their specified ConnectionPoint objects, and a WebPartTransformer object.

Remarks

The ConnectWebParts method forms a connection between any two WebPart controls that can be connected. Before calling this method to create a connection, you might also want to call the CanConnectWebParts method in a conditional check to ensure that the controls meet the requirements for forming a connection.

Note

It is also possible to create a connection between two server controls that are not WebPart controls. In general, the two controls would have to be custom server controls (for example, controls that inherit from WebControl or existing ASP.NET server controls) so that you could add the required members. The controls would also have to meet the requirements specified below.

Any type of connection scenario between two controls must meet the following requirements to be able to connect:

Each control resides in a WebPartZoneBase zone (it does not have to be the same zone).
As implemented in the Web Parts control set, the provider control in a connection implements an interface as a public method that serves as a callback to the provider, and has a ConnectionProvider metadata attribute on the method to identify it as a provider connection point. Because the GetProviderConnectionPoints method that retrieves provider connection points is virtual, a derived WebPartManager control does not necessarily have to use the same metadata attribute.
As implemented in the Web Parts control set, the consumer control in a connection also has a special method that enables it to get a reference to the interface that is exposed in the provider's callback method, and the consumer has a ConnectionConsumer metadata attribute on the method to identify it as a consumer connection point. Because the GetConsumerConnectionPoints method that retrieves consumer connection points is virtual, a derived WebPartManager control does not necessarily have to use the same metadata attribute.
The callback methods must either be compatible, in that the consumer can use the type of interface supplied in the provider's callback method (meaning that the consumer and provider can share data directly), or the developer must use a WebPartTransformer object to transform the data from the provider into a form that the consumer can use.

Important

When you do not need a transformer, use the ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint) method overload. When you need a transformer, use the ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint, WebPartTransformer) method overload.

ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint)

Creates a connection between two WebPart or GenericWebPart controls using only the references to the controls and their specified ConnectionPoint objects.

public:
 System::Web::UI::WebControls::WebParts::WebPartConnection ^ ConnectWebParts(System::Web::UI::WebControls::WebParts::WebPart ^ provider, System::Web::UI::WebControls::WebParts::ProviderConnectionPoint ^ providerConnectionPoint, System::Web::UI::WebControls::WebParts::WebPart ^ consumer, System::Web::UI::WebControls::WebParts::ConsumerConnectionPoint ^ consumerConnectionPoint);

public System.Web.UI.WebControls.WebParts.WebPartConnection ConnectWebParts (System.Web.UI.WebControls.WebParts.WebPart provider, System.Web.UI.WebControls.WebParts.ProviderConnectionPoint providerConnectionPoint, System.Web.UI.WebControls.WebParts.WebPart consumer, System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint consumerConnectionPoint);

member this.ConnectWebParts : System.Web.UI.WebControls.WebParts.WebPart * System.Web.UI.WebControls.WebParts.ProviderConnectionPoint * System.Web.UI.WebControls.WebParts.WebPart * System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint -> System.Web.UI.WebControls.WebParts.WebPartConnection

Public Function ConnectWebParts (provider As WebPart, providerConnectionPoint As ProviderConnectionPoint, consumer As WebPart, consumerConnectionPoint As ConsumerConnectionPoint) As WebPartConnection

Parameters

provider: WebPart

A WebPart control that has the role of furnishing data to another connected control.

providerConnectionPoint: ProviderConnectionPoint

A method that serves as a callback method for the connection. As implemented in the Web Parts control set, this is a public method in provider that is marked with a ConnectionProvider metadata attribute.

consumer: WebPart

A WebPart control that has the role of receiving data from provider, and then processing or displaying it.

consumerConnectionPoint: ConsumerConnectionPoint

A method that connects with providerConnectionPoint to receive the data for the connection. As implemented in the Web Parts control set, this is a public method in consumer that is marked with a ConnectionConsumer metadata attribute.

Returns

WebPartConnection

A WebPartConnection that contains the various information about the provider and the consumer needed for a connection.

Exceptions

InvalidOperationException

The WebPartManager control's collection of dynamic collections is read-only.

Examples

The following code example demonstrates how to use this method to create a connection programmatically. For the full code required to run the example, see the Example section of the WebPartManager class overview. From that example, you will need the source code for the user control that allows you to change display modes on the page, and the source code for the two custom WebPart controls.

The code for the Web page that hosts the two controls follows. The page uses Register directives at the top to declare the user control and the custom controls. The custom controls are then referenced declaratively within an <asp:webpartzone> element. The code that handles the Button1_Click method creates a connection between the controls by using the ConnectWebParts method.

<%@ Page Language="C#" %>
<%@ Register TagPrefix="uc1" 
    TagName="DisplayModeMenuCS"
    Src="~/displaymodemenucs.ascx" %>
<%@ Register TagPrefix="aspSample" 
    Namespace="Samples.AspNet.CS.Controls" 
    Assembly="ConnectionSampleCS"%>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

  protected void Button1_Click(object sender, EventArgs e)
  {
    ProviderConnectionPoint provPoint = 
      mgr.GetProviderConnectionPoints(zip1)["ZipCodeProvider"];
    ConsumerConnectionPoint connPoint = 
      mgr.GetConsumerConnectionPoints(weather1)["ZipCodeConsumer"];
    WebPartConnection conn1 = mgr.ConnectWebParts(zip1, provPoint,
      weather1, connPoint);
  }

  protected void mgr_DisplayModeChanged(object sender, 
    WebPartDisplayModeEventArgs e)
  {
    if (mgr.DisplayMode == WebPartManager.ConnectDisplayMode)
      Button1.Visible = true;
    else
      Button1.Visible = false;
  }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <asp:WebPartManager ID="mgr" runat="server" 
    OnDisplayModeChanged="mgr_DisplayModeChanged">
      </asp:WebPartManager>
      <uc1:DisplayModeMenuCS ID="menu1" runat="server" />
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <aspSample:ZipCodeWebPart ID="zip1" runat="server"
            Title="Zip Code Provider" />
          <aspSample:WeatherWebPart ID="weather1" runat="server" 
            Title="Zip Code Consumer" />
        </ZoneTemplate>
      </asp:WebPartZone>
      <asp:ConnectionsZone ID="ConnectionsZone1" runat="server">
      </asp:ConnectionsZone>
      <asp:Button ID="Button1" runat="server" 
        Text="Connect WebPart Controls" 
        OnClick="Button1_Click" 
    Visible="false" />
    </div>
    </form>
</body>
</html>

<%@ Page Language="vb" %>
<%@ Register TagPrefix="uc1" 
    TagName="DisplayModeMenuVB"
    Src="~/displaymodemenuvb.ascx" %>
<%@ Register TagPrefix="aspSample" 
    Namespace="Samples.AspNet.VB.Controls" 
    Assembly="ConnectionSampleVB"%>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

  Protected Sub Button1_Click(ByVal sender As Object, _
    ByVal e As System.EventArgs)
    
    Dim provPoint As ProviderConnectionPoint = _
      mgr.GetProviderConnectionPoints(zip1)("ZipCodeProvider")
    Dim connPoint As ConsumerConnectionPoint = _
      mgr.GetConsumerConnectionPoints(weather1)("ZipCodeConsumer")
    mgr.ConnectWebParts(zip1, provPoint, weather1, connPoint)

  End Sub

  Protected Sub mgr_DisplayModeChanged (ByVal sender as Object, _
    ByVal e as WebPartDisplayModeEventArgs)

    If mgr.DisplayMode is WebPartManager.ConnectDisplayMode Then
    Button1.Visible = True
    Else
    Button1.Visible = False
    End If

  End Sub
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <asp:WebPartManager ID="mgr" runat="server" 
    OnDisplayModeChanged="mgr_DisplayModeChanged">
      </asp:WebPartManager>
      <uc1:DisplayModeMenuVB ID="menu1" runat="server" />
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <aspSample:ZipCodeWebPart ID="zip1" runat="server"
            Title="Zip Code Provider" />
          <aspSample:WeatherWebPart ID="weather1" runat="server" 
            Title="Zip Code Consumer" />
        </ZoneTemplate>
      </asp:WebPartZone>
      <asp:ConnectionsZone ID="ConnectionsZone1" runat="server">
      </asp:ConnectionsZone>
      <asp:Button ID="Button1" runat="server" 
        Text="Connect WebPart Controls" 
        OnClick="Button1_Click" 
    Visible="false" />
    </div>
    </form>
</body>
</html>

After you load the page in a browser, click the Connect WebPart Controls button to form the connection. You can then enter some data in the text box, and click the Enter 5-digit ZIP Code button to demonstrate that the controls are connected, and that data entered in the first control is updated in the second.

Remarks

This overload is used to connect controls when their connection points are sufficiently compatible that they can connect without using a WebPartTransformer object. When this overload of the method is called, it simply passes the call to the other overloaded version of the method, and passes null for the parameter that requires a WebPartTransformer object.

When you attempt to connect two controls programmatically, you can use the CanConnectWebParts method in a conditional check to determine whether the controls can be directly connected.

Applies to

ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint, WebPartTransformer)

Creates a connection between two WebPart or GenericWebPart controls using the references to the controls, their specified ConnectionPoint objects, and a WebPartTransformer object.

public:
 virtual System::Web::UI::WebControls::WebParts::WebPartConnection ^ ConnectWebParts(System::Web::UI::WebControls::WebParts::WebPart ^ provider, System::Web::UI::WebControls::WebParts::ProviderConnectionPoint ^ providerConnectionPoint, System::Web::UI::WebControls::WebParts::WebPart ^ consumer, System::Web::UI::WebControls::WebParts::ConsumerConnectionPoint ^ consumerConnectionPoint, System::Web::UI::WebControls::WebParts::WebPartTransformer ^ transformer);

public virtual System.Web.UI.WebControls.WebParts.WebPartConnection ConnectWebParts (System.Web.UI.WebControls.WebParts.WebPart provider, System.Web.UI.WebControls.WebParts.ProviderConnectionPoint providerConnectionPoint, System.Web.UI.WebControls.WebParts.WebPart consumer, System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint consumerConnectionPoint, System.Web.UI.WebControls.WebParts.WebPartTransformer transformer);

abstract member ConnectWebParts : System.Web.UI.WebControls.WebParts.WebPart * System.Web.UI.WebControls.WebParts.ProviderConnectionPoint * System.Web.UI.WebControls.WebParts.WebPart * System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint * System.Web.UI.WebControls.WebParts.WebPartTransformer -> System.Web.UI.WebControls.WebParts.WebPartConnection
override this.ConnectWebParts : System.Web.UI.WebControls.WebParts.WebPart * System.Web.UI.WebControls.WebParts.ProviderConnectionPoint * System.Web.UI.WebControls.WebParts.WebPart * System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint * System.Web.UI.WebControls.WebParts.WebPartTransformer -> System.Web.UI.WebControls.WebParts.WebPartConnection

Public Overridable Function ConnectWebParts (provider As WebPart, providerConnectionPoint As ProviderConnectionPoint, consumer As WebPart, consumerConnectionPoint As ConsumerConnectionPoint, transformer As WebPartTransformer) As WebPartConnection

Parameters

provider: WebPart

A WebPart that has the role of furnishing data to another connected control.

providerConnectionPoint: ProviderConnectionPoint

A public method in provider that is marked with a ConnectionProvider metadata attribute, and serves as a callback method for the connection.

consumer: WebPart

A WebPart that has the role of receiving data from provider or transformer, and then processing or displaying it.

consumerConnectionPoint: ConsumerConnectionPoint

A public method in consumer that is marked with a ConnectionConsumer metadata attribute, and connects with providerConnectionPoint to receive the data for the connection.

transformer: WebPartTransformer

A WebPartTransformer that enables a connection between two controls by converting the data from provider to a format that consumer can process.

Returns

WebPartConnection

A WebPartConnection that contains the information about the provider, consumer, and transformer needed for a connection.

Exceptions

InvalidOperationException

Connections have already been activated in PreRender.

Remarks

This overload is used to connect controls when their connection points are incompatible. The incompatibility occurs when consumer implements a different interface than provider as its connection point. The transformer converts the data into a type that can be understood by consumer.

Applies to

Partajați prin

WebPartManager.ConnectWebParts Method

Definition

Overloads

Remarks

ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint)

Parameters

Returns

Exceptions

Examples

Remarks

See also

Applies to

ConnectWebParts(WebPart, ProviderConnectionPoint, WebPart, ConsumerConnectionPoint, WebPartTransformer)

Parameters

Returns

Exceptions

Remarks

See also

Applies to

Resurse suplimentare