ConnectionPoint Class
Assembly: System.Web (in system.web.dll)
Every Web Parts connection consists of two server controls sharing data: one control is the consumer, the other is the provider. For a discussion of the essential components of a Web Parts connection, and the connection object itself, see the WebPartConnection class overview. Every Web Parts connection requires connection points. The provider and the consumer control must each have at least one defined ConnectionPoint object (each of them can optionally have multiple connection points) that contains the details for how a control can connect to another control and the type of data it can share. In an actual connection, the provider has its own type of connection point object (derived from the base ConnectionPoint class), a ProviderConnectionPoint instance, and the consumer has its own object, a ConsumerConnectionPoint instance.
To create a provider connection point, developers must add a callback method to the provider that will return an implemented interface instance to a consumer. They must mark the callback method in the source code with a ConnectionProvider code attribute (see the ConnectionProviderAttribute class). Similarly, to create a consumer connection point, developers must add a method to the consumer that receives an interface instance, and they must mark that method with a ConnectionConsumer attribute (see the ConnectionConsumerAttribute class).
When developers create connections on a Web page, they can be created as static or dynamic connections. Static connections are declared in the markup of a Web page. When a static connection is declared, developers can designate which connection points are used for both the consumer and provider by assigning values to the ProviderConnectionPointID and ConsumerConnectionPointID attributes within the <asp:webpartconnection> element tag. This approach is especially useful if there are multiple connection points defined within the consumer and provider controls, because it enables the static connection to identify which connection points to use for the connection.
Dynamic connections are created programmatically, either by a developer's code or by users through the user interface (UI) provided by the ConnectionsZone control. To create a connection in code, developers must get an instance of a WebPartConnection object by calling the ConnectWebParts method on the WebPartManager control. Before they can call this method, developers must have references to the consumer and provider server controls and their respective connection point objects. To get references to the connection points for a provider and a consumer control, developers first call the GetProviderConnectionPoints and GetConsumerConnectionPoints methods on the WebPartManager control. These methods return the appropriate connection point objects, which in turn can be passed to the method for creating a connection.
When the provider's and the consumer's connection point objects both work with the same type of interface, they are compatible and can form a direct connection to share data. If they do not work with the same interface type, a WebPartTransformer object must be used to translate the interface instance from the provider into a type that the consumer can work with.
The abstract ConnectionPoint class provides the base details of connection points that are shared by both consumer and provider controls. Several properties contain these details. The AllowsMultipleConnections property indicates whether a connection point can participate in more than one connection at a time. By default, provider connection points can participate in multiple connections, and consumer connection points cannot. The ControlType property indicates the type of the server control associated with a connection point. Note that not only WebPart controls can form connections; any server control, whether an ASP.NET control, a custom control, or a user control, can be enabled to participate in connections if placed in a WebPartZoneBase zone. The DisplayName property provides a friendly name for the connection point that can be displayed in the UI to assist users who are creating connections. The ID property serves as a string identifier for the connection point object itself. The InterfaceType property indicates what type of interface instance the connection point understands. Whether a given connection point provides or consumes an instance of that interface is determined by whether it is a ProviderConnectionPoint or a ConsumerConnectionPoint object.
The ConnectionPoint class has one method. The GetEnabled method returns a Boolean value indicating whether a connection point is currently able to participate in connections.
The ConnectionPoint class also has one public field, DefaultID. This field contains a value used to identify the default connection point in a connection.
Note |
|---|
| The attributes for specifying connection point methods have only one required parameter, displayName, so it is possible to create the default connection point attribute without specifying an ID. In such cases, the DefaultID field supplies a base value to use. |
The following code example demonstrates the creation of a Web Parts connection that includes the required ConnectionPoint objects. Because the ConnectionPoint class is an abstract base class, instances of its child classes--ProviderConnectionPoint and ConsumerConnectionPoint--are the actual objects used to form a connection.
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.
<%@ control language="vb" classname="DisplayModeMenuVB"%> <script runat="server"> ' Use a field to reference the current WebPartManager. Dim _manager As WebPartManager Sub Page_Init(ByVal sender As Object, ByVal e As EventArgs) AddHandler Page.InitComplete, AddressOf InitComplete End Sub Sub InitComplete(ByVal sender As Object, ByVal e As System.EventArgs) _manager = WebPartManager.GetCurrentWebPartManager(Page) Dim browseModeName As String = WebPartManager.BrowseDisplayMode.Name ' Fill the dropdown with the names of supported display modes. Dim mode As WebPartDisplayMode For Each mode In _manager.SupportedDisplayModes Dim modeName As String = mode.Name ' Make sure a mode is enabled before adding it. If mode.IsEnabled(_manager) Then Dim item As New ListItem(modeName, modeName) DisplayModeDropdown.Items.Add(item) End If Next mode ' If shared scope is allowed for this user, display the scope-switching ' UI and select the appropriate radio button for the current user scope. If _manager.Personalization.CanEnterSharedScope Then Panel2.Visible = True If _manager.Personalization.Scope = PersonalizationScope.User Then RadioButton1.Checked = True Else RadioButton2.Checked = True End If End If End Sub ' Change the page to the selected display mode. Sub DisplayModeDropdown_SelectedIndexChanged(ByVal sender As Object, _ ByVal e As EventArgs) Dim selectedMode As String = DisplayModeDropdown.SelectedValue Dim mode As WebPartDisplayMode = _ _manager.SupportedDisplayModes(selectedMode) If Not (mode Is Nothing) Then _manager.DisplayMode = mode End If End Sub ' Set the selected item equal to the current display mode. Sub Page_PreRender(ByVal sender As Object, ByVal e As EventArgs) Dim items As ListItemCollection = DisplayModeDropdown.Items Dim selectedIndex As Integer = _ items.IndexOf(items.FindByText(_manager.DisplayMode.Name)) DisplayModeDropdown.SelectedIndex = selectedIndex End Sub ' Reset all of a user's personalization data for the page. Protected Sub LinkButton1_Click(ByVal sender As Object, _ ByVal e As EventArgs) _manager.Personalization.ResetPersonalizationState() End Sub ' If not in User personalization scope, toggle into it. Protected Sub RadioButton1_CheckedChanged(ByVal sender As Object, _ ByVal e As EventArgs) If _manager.Personalization.Scope = PersonalizationScope.Shared Then _manager.Personalization.ToggleScope() End If End Sub ' If not in Shared scope, and if user is allowed, toggle the scope. Protected Sub RadioButton2_CheckedChanged(ByVal sender As Object, _ ByVal e As EventArgs) If _manager.Personalization.CanEnterSharedScope AndAlso _ _manager.Personalization.Scope = PersonalizationScope.User Then _manager.Personalization.ToggleScope() End If End Sub </script> <div> <asp:Panel ID="Panel1" runat="server" Borderwidth="1" Width="230" BackColor="lightgray" Font-Names="Verdana, Arial, Sans Serif" > <asp:Label ID="Label1" runat="server" Text=" Display Mode" Font-Bold="true" Font-Size="8" Width="120" /> <asp:DropDownList ID="DisplayModeDropdown" runat="server" AutoPostBack="true" Width="120" OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" /> <asp:LinkButton ID="LinkButton1" runat="server" Text="Reset User State" ToolTip="Reset the current user's personalization data for the page." Font-Size="8" OnClick="LinkButton1_Click" /> <asp:Panel ID="Panel2" runat="server" GroupingText="Personalization Scope" Font-Bold="true" Font-Size="8" Visible="false" > <asp:RadioButton ID="RadioButton1" runat="server" Text="User" AutoPostBack="true" GroupName="Scope" OnCheckedChanged="RadioButton1_CheckedChanged" /> <asp:RadioButton ID="RadioButton2" runat="server" Text="Shared" AutoPostBack="true" GroupName="Scope" OnCheckedChanged="RadioButton2_CheckedChanged" /> </asp:Panel> </asp:Panel> </div>
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. Its ProvideIZipCode method is the callback method that implements the interface's only member. The method simply returns an instance of the interface. Note that the method is marked with a ConnectionProvider attribute in its metadata. This is the mechanism for identifying the method as the callback method for the provider's connection point. 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 Server Control.
Imports System Imports System.Web Imports System.Web.Security Imports System.Security.Permissions Imports System.Web.UI Imports System.Web.UI.WebControls Imports System.Web.UI.WebControls.WebParts Namespace Samples.AspNet.VB.Controls <AspNetHostingPermission(SecurityAction.Demand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ <AspNetHostingPermission(SecurityAction.InheritanceDemand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ Public Interface IZipCode Property ZipCode() As String End Interface <AspNetHostingPermission(SecurityAction.Demand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ <AspNetHostingPermission(SecurityAction.InheritanceDemand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ Public Class ZipCodeWebPart Inherits WebPart Implements IZipCode Private zipCodeText As String = String.Empty Private input As TextBox Private send As Button Public Sub New() End Sub ' Make the implemented property personalizable to save ' the Zip Code between browser sessions. <Personalizable()> _ Public Property ZipCode() As String _ Implements IZipCode.ZipCode Get Return zipCodeText End Get Set(ByVal value As String) zipCodeText = value End Set End Property ' This is the callback method that returns the provider. <ConnectionProvider("Zip Code Provider", "ZipCodeProvider")> _ Public Function ProvideIZipCode() As IZipCode Return Me End Function Protected Overrides Sub CreateChildControls() Controls.Clear() input = New TextBox() Me.Controls.Add(input) send = New Button() send.Text = "Enter 5-digit Zip Code" AddHandler send.Click, AddressOf Me.submit_Click Me.Controls.Add(send) End Sub Private Sub submit_Click(ByVal sender As Object, _ ByVal e As EventArgs) If input.Text <> String.Empty Then zipCodeText = Page.Server.HtmlEncode(input.Text) input.Text = String.Empty End If End Sub End Class <AspNetHostingPermission(SecurityAction.Demand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ <AspNetHostingPermission(SecurityAction.InheritanceDemand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ Public Class WeatherWebPart Inherits WebPart Private _provider As IZipCode Private _zipSearch As String Private DisplayContent As Label ' This method is identified by the ConnectionConsumer ' attribute, and is the mechanism for connecting with ' the provider. <ConnectionConsumer("Zip Code Consumer", "ZipCodeConsumer")> _ Public Sub GetIZipCode(ByVal Provider As IZipCode) _provider = Provider End Sub Protected Overrides Sub OnPreRender(ByVal e As EventArgs) EnsureChildControls() If Not (Me._provider Is Nothing) Then _zipSearch = _provider.ZipCode.Trim() DisplayContent.Text = "My Zip Code is: " + _zipSearch End If End Sub 'OnPreRender Protected Overrides Sub CreateChildControls() Controls.Clear() DisplayContent = New Label() Me.Controls.Add(DisplayContent) End Sub End Class End Namespace
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. You can also create the connection programmatically; the code for doing that is contained in the Button1_Click method. 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.
<%@ Page Language="VB" %> <%@ register tagprefix="uc1" tagname="DisplayModeMenuVB" src="~/displaymodemenuvb.ascx" %> <%@ Register TagPrefix="aspSample" Namespace="Samples.AspNet.VB.Controls" %> <!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") If mgr.CanConnectWebParts(zip1, provPoint, weather1, connPoint) Then mgr.ConnectWebParts(zip1, provPoint, weather1, connPoint) End If End Sub Protected Sub Button2_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) Dim conn As WebPartConnection = mgr.Connections(0) lblConn.Text = "<h2>Connection Point Details</h2>" & _ "<h3>Provider Connection Point</h3>" & _ " Display name: " & conn.ProviderConnectionPoint.DisplayName & _ "<br />" & _ " ID: " & conn.ProviderConnectionPoint.ID & _ "<br />" & _ " Interface type: " & conn.ProviderConnectionPoint.InterfaceType.ToString() & _ "<br />" & _ " Control type: " & conn.ProviderConnectionPoint.ControlType.ToString() & _ "<br />" & _ " Allows multiple connections: " & _ conn.ProviderConnectionPoint.AllowsMultipleConnections.ToString() & _ "<br />" & _ " Enabled: " & conn.ProviderConnectionPoint.GetEnabled(zip1).ToString() & _ "<hr />" & _ "<h3>Consumer Connection Point</h3>" & _ " Display name: " & conn.ConsumerConnectionPoint.DisplayName & _ "<br />" & _ " ID: " & conn.ConsumerConnectionPoint.ID & _ "<br />" & _ " Interface type: " & conn.ConsumerConnectionPoint.InterfaceType.ToString() & _ "<br />" & _ " Control type: " & conn.ConsumerConnectionPoint.ControlType.ToString() & _ "<br />" & _ " Allows multiple connections: " & _ conn.ConsumerConnectionPoint.AllowsMultipleConnections.ToString() & _ "<br />" & _ " Enabled: " & conn.ConsumerConnectionPoint.GetEnabled(zip1).ToString() End Sub Protected Sub Page_Load(ByVal sender As Object, _ ByVal e As System.EventArgs) lblConn.Text = String.Empty End Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head id="Head1" runat="server"> <title>Untitled Page</title> </head> <body> <form id="form1" runat="server"> <div> <asp:WebPartManager ID="mgr" runat="server" > <StaticConnections> <asp:WebPartConnection ID="conn1" ConsumerConnectionPointID="ZipCodeConsumer" ConsumerID="weather1" ProviderConnectionPointID="ZipCodeProvider" ProviderID="zip1" /> </StaticConnections> </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="Dynamic Connection" OnClick="Button1_Click" /> <br /> <asp:Button ID="Button2" runat="server" Text="Connection Point Details" OnClick="Button2_Click" /> <br /> <asp:Label ID="lblConn" runat="server" /> </div> </form> </body> </html>
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 one of the WebPart controls (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. Click the Disconnect button to terminate the existing connection. Use the Display Mode control to return the page to browse mode. Next, click the Dynamic Connection button to create a connection programmatically. Click the Connection Point Details button again, to indicate details about the two connection point objects.
- AspNetHostingPermission for operating in a hosted environment. Demand value: LinkDemand; Permission value: Minimal.
- AspNetHostingPermission for operating in a hosted environment. Demand value: InheritanceDemand; Permission value: Minimal.
System.Web.UI.WebControls.WebParts.ConnectionPoint
System.Web.UI.WebControls.WebParts.ConsumerConnectionPoint
System.Web.UI.WebControls.WebParts.ProviderConnectionPoint
Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.
Note