Introduce ASP. NET Web component connection

Release date: 2006-4-11 | Updated on: 2006-4-11

Ted Pattison

DownloadCode:Basicinstincts0602.exe(763kb)

Content on this page

	Create a Web part for the ASP. NET 2.0 application Program
	Design connectable Web Components
	timing a Web part connection
	define static Web part connection
	name the connection point
	dynamically establish a connection

When you start to use Microsoft. NET Framework 2.0 and ASP. NET, you will find that the new Web component infrastructure adds some very powerful functions to the basic platform. InMsdnMagazineIn November September 2005, Fritz onion and I wrote an article about programming Web components.ArticleEntitled "ASP. NET 2.0: personalize your portal with user controls and custom web parts ". In this month's column, I want to expand the information in that article by discussing how Web Part connections work.

For this column, I assume you have some basic knowledge about Web components, such as how to use the webpartmanager control, Web Part area, editor, directory, and persistence attributes. If you do not know, we recommend that you read the article you just mentioned before continuing to read this article.

Create web parts for ASP. NET 2.0 applications

You can create Web parts in two ways. The first method involves creating a custom Web Part class that inherits from the webpart class defined in the system. Web. UI. webcontrols. webparts namespace. When using this method, it is usually meaningful to package custom Web Part classes into an assembly DLL, this provides more control over reuse, version control, and Visual Studio 2005 integration. If you are familiar with using the previous ASP. NET version to generate custom controls, many of the same technologies apply to generating custom web parts into the DLL assembly.

The second method used to create ASP. NET 2.0 web parts involves using user controls. Although this method does not produce the same reuse and version control levels, it does allow you to use the Visual Studio Form Designer to create the user interface section of Web parts. This method is applicable if you want to create an application by dragging the control used for user input, verification, and data binding to the design interface. Of course, if you have spent time creating a user control that you want to use as a Web part, it is also a good way to use it.

When creating a user control specially designed for Web parts, we recommend that you implement the iwebpart interface. In this way, the Web Part background code can be programmed to allocate several internal Web Part attributes, such as its title and titleiconurl.

The sample code that comes with this month's column uses a custom base class named webpartbase, which inherits from usercontrol and implements iwebpart. The definition of this base class is deployed in the source file webpartbase. VB in the app_code directory. Whenever you use a user control to create a new Web part, you only need to change the base class in the hidden code file to use this technology:

 
Partial class webparts_customersinherits webpartbasesub new () Title = "northwind customer list" titleiconimageurl = "~ \ IMG \ customers.gif "End subend class
 

Back to Top

Design connectable Web Components

Web component connection allows you to easily visualize the relationships between different data items. For example, a Web part connection can be used to model a master-slave solution, where the Web Part displaying the customer list is connected to another Web part that displays the details of the currently selected customer.Figure 1This design may generate a user interface.

Web component connections can also be used to model one-to-multiple relationships. For example, a Web part that displays the customer list can be connected to another Web part that displays all orders for the currently selected customer.

Form query is another method for connecting to modeling using Web parts. In this solution, a Web component provides a user interface that allows you to select the search or filter conditions used to query data (such as database tables. The Web part is connected to another Web part that displays the query result. A Web part connection is used to pass filtering conditions from one Web part to another before running a query.

Web parts are connected based on the concepts of providers and users. The provider Web component provides information for one or more user Web parts through a programming interface. The information exchanged between the provider and the user can be simple data items (such as numbers or strings ), it can also be special content (for example, a reference to a complex array or a set of custom objects ).

If you have compiled a Web part for Windows SharePoint Services 2.0 (WSS), you may already be familiar with its model for connecting to Web parts. In WSS, Web parts can only be connected using a set of predefined interface pairs. Examples of these interface pairs include icellprovider and icellconsumer, and irowprovider and irowconsumer.

The Web part connection model in ASP. NET 2.0 is easier and more flexible than the old model in WSS, because you can use your own custom interfaces. This means that you do not need to use the interface definition created by Microsoft personnel. In addition, you do not need to perform any operations on interfaces. They must be implemented by providers and users. With ASP. NET 2.0, only the provider needs to implement an interface.

To learn how it works, first create a connection between two Web components. For the example I want to provide in this month's column, I decided to use the northwind database because it has a mers MERs table and an orders table. This allows me to show you how to design Web Components for master-slave and one-to-many relationships. Note that if SQL Server 2005 is used, this example northwind database is not installed during product installation. To install it, you must download and run the scripts available on the Microsoft Web site (seeMicrosoft SQL Server Homepage).

Now, assume that you want to establish a web part connection between a web part that displays the customer list and a customer Web part that displays the details of the currently selected customer, as shown in figureFigure 1. The Web part that displays the customer list assumes the provider role, and the Web part that displays the details of the currently selected customer acts as the user. In this case, you want the provider to provide the user with the customerid field of the currently selected customer.

First, create a simple interface named icustomeridprovider:

 
Public interface icustomeridproviderreadonly property customerid () as stringend Interface
 

In the sample code that comes with this month's column, I used a user control with the sqldatasource and gridview controls to create a provider Web part to display customers from northwind. The source files of the Web parts are MERs. ascx and customers. ascx. VB, as shown in figureFigure 2.

You can see that webparts_customers acts as the provider and implements the interface for connecting the Web part. In this example, webparts_mers MERs implements the icustomeridprovider interface. Although the most common mode is that the provider implements the connection interface, it does not need to do so. The only actual requirement is that the connectionprovider method returns an instance of the specified interface. Therefore, as an alternative, the provider Web component can return a helper object that implements the connection interface. This is usually necessary if a provider Web part has multiple connection points of the same interface type.

Return the value of the selecteddatakey attribute of the gridview control. The webparts_mers MERs class implements the customerid attribute. The gridview control has been set to display records from the northwind MERs table, and recognizes the customerid field as the selecteddatakey value.

You should note that the webparts_mers MERs class has a method named getcustomerprovider, which has a return type defined according to the icustomeridprovider interface. In this case, because the Web part itself implements the required interface, getcustomerprovider can only return the me reference to the current instance of this class. You should also note that this method has been defined using the connectionprovider attribute:

 
<Connectionprovider ("Customer ID provider")>
 

Webpartmanager is responsible for connecting Web Components at runtime. When webpartmanager sees a Web part that contains a method defined using the connectionprovider property, it knows that the Web part exposes a connection point, so it can act as a provider and connect to the user. When two Web parts need to be connected together, webpartmanager will call the getcustomerprovider method to obtain a strong type reference to the Web parts of the provider.

It is possible to define whether a provider Web part accepts multiple connections from the user. In some cases, a provider can connect to multiple users at the same time. In other cases, you may want to restrict the provider so that it can have at most one connection to the user's Web parts. By default, the provider allows multiple connections, but the user does not. To change this point, when you apply the connectionprovider attribute, you can use the named parameter allowsmultipleconnections, as shown below:

 
<Connectionprovider ("Customer ID provider", _ allowsmultipleconnections: = false)>
 

Now that you have seen how to create a method to expose the connection point in the provider Web part, let's see how this is implemented in the user Web part. The user webpart discloses the connection point by providing a method defined using the connectionconsumer attribute. The user's connection point method is different from the provider's connection method because it does not define the return value. Instead, it gets a parameter defined by the interface type of the connection:

 
<Connectionconsumer ("Customer ID consumer")> _ Sub registercustomerprovider (byval provider as icustomeridprovider)... 'implementationend sub
 

Remember that the provider's connection point method name is not important to the user's connection point method name. The only thing to note is that each method uses the connectionprovider attribute and the connectionconsumer attribute for definition.

Now let's take a look at how webpartmanager establishes the connection at runtime. Webpartmanager calls the provider's connection point method to obtain references to the provider object. Next, webpartmanager calls the user's connection point method to pass a strong type reference to the provider for it.

Once webpartmanager completes its work, the user's Web part has an active connection that is returned to the provider's Web part. In this case, you can use the methods and attributes defined in the referenced access interface to directly interact with the provider. However, the ASP. Net Team recommends that you do not use methods and attributes on the provider interface before the prerender stage. Specifically, they should not use methods and attributes on the provider interface in the method itself. The reason is that these connections may depend on each other. You may have a providerwebpart that connects to providerconsumerwebpart and then consumerwebpart. Before the two connections are established, consumerwebpart cannot query the provider interface, and the order in which the connections are established depends on the framework.

Figure 3Displays the complete list of user Web parts in customerdetails. ascx. VB. You can see that the user's Web parts are responsible for continuous reference, so that you can track the connection of the provider. The user's Web part contains a private field named provider, which is defined according to the icustomeridprovider interface.

When webpartmanager calls registercustomerprovider, the user obtains the passed reference parameter and assigns it to the provider field. After the provider field is assigned the reference, the user's Web part can directly interact with the provider's Web part. When designing this interface for a connection, you should add any methods and attributes that will provide the interaction you need.

In some cases, a user's Web part may be designed to work properly regardless of whether there is any active connection to the provider. In this design, when the provider field has a nothing value, you may want to add the temporary code to the user's Web part that works properly:

 
If provider isnot nothing then... 'interact with providerelse... 'contingency code goes here if requiredend if
 

Back to Top

Timing A Web part connection

When you start designing web components that support connection, it is important to understand the timing involved.Figure 4Displays a small part of the page on which the provider Web parts and user Web parts run during http get. Although there are more page-level events that are triggered during http post, the timing of connection creation remains the same.

Figure 4The trace information displayed in explains when each connection method is triggered for standard ASP. NET 2.0 page-level events. You should be able to see from this trace information that webpartmanager connects Web parts in the page-level loadcomplete command.

Note that when the page-level event preinit, init, preload, and load are executed, the Web part connection has not yet been established. This means that you should never try to access the provider in the processing method of the user's Web parts (it is bound to one of these events. Before attempting to access the provider's Web part, the code in the user's Web Part must wait until the loadcomplete event is executed.

In this example, the user's Web Part processes the selecting event of the sqldatasource control, which is triggered in the page-level prerender event. It is safe to access the provider and retrieve the customer ID.

Back to Top

Define static Web part connection

Now that you have seen how to create Web Components that support connection and understand the timing involved, you should explore how to actually connect them together. As you can see, you can add tags directly to a Web Part Page Definition to establish a static Web part connection. You can also dynamically establish a web part connection through code or user interaction at runtime. First, I want to demonstrate how to create a static connection between two Web parts, because this is the simplest method.

To create a static Web part connection between two Web parts on a page, add the staticconnections element to the webpartmanager Tag:

 
<Asp: webpartmanager id = "webpartmanager1" runat = "server"> <staticconnections> <asp: webpartconnection id = "C1" providerid = "customers1" consumerid = "customerdetails1"/> </staticconnections> </ASP: webpartmanager>
 

To make the code run properly, the provider Web parts named customers1 and the user Web parts named customerdetails1 must also be statically defined and named correctly in the Web parts area on the same page.

Note that each page has only one webpartmanager control. However, in many application designs involving Web Components, you will find it easy to add webpartmanager to a user control or master page because it can be reused on many pages.

When a Web Part Page is based on a master page or a user control containing the webpartmanager control, you cannot add the second example of the webpartmanager control to define the staticconnections tag. To address these problems, the ASP. NET 2.0 web part control set provides the proxywebpartmanager control. The following is an example of how to use it:

 
<Asp: proxywebpartmanager id = "proxywebpartmanager1" runat = "server"> <staticconnections> <asp: webpartconnection id = "C1" providerid = "customers1" consumerid = "customerdetails1"/> </staticconnections> </ASP: proxywebpartmanager>
 

The value of the proxywebpartmanager control is that it allows you to add static connections at the page level when the page cannot contain the webpartmanager tag. In the example Page default. aspx attached to this column, you must use proxywebpartmanager to establish a static Web part connection because webpartmanager has been encapsulated in the user control named webpartmanagerpanel. ascx.

Back to Top

Name the connection point

In my current example, the connection between the provider Web part and the user Web part is based on the default connection point. However, it is possible that the Web part connection method provides a named connection point. To add a named connection point to the provider, you only need to add the second string parameter to the connectionprovider attribute:

<Connectionprovider ("Customer ID provider", "customeridprovider")> _ Public Function getcustomerprovider () as icustomeridproviderreturn meend Function
 

One reason for using a named connection point is that the provider or user may have multiple connection points, so they must be differentiated. To add a named connection point to a user's Web part, you can add the second string parameter to the connectionconsumer attribute:

 
<Connectionconsumer ("Customer ID" & "consumer", "customeridconsumer")> _ Sub registercustomerprovider (byval provider as icustomeridprovider) me. provider = providerend sub
 

When you start to use the named connection point and define the staticconnections tag at the page level, you must provide two additional attribute values for providerconnectionpointid and consumerconnectionpointid.

Back to Top

Dynamically establish a connection

When you want to connect web parts together, sometimes you cannot rely on static Web parts for connection. For example, if you want to connect a Web Part dynamically created by using custom code, or you want to dynamically create a web part by adding a Web part to the page using the Web Part directory, this will happen.

When you cannot use a static Web part to connect to a Web part, you must use dynamic technology to connect to the Web part. To do this, you can use custom code or the connectionszone Control attached to the ASP. NET 2.0 web part control set.

Let's first take a look at the custom code that creates two Web parts and dynamically connects them together, as shown inFigure 5. This Code creates Web parts instances for the provider and the user through the user control and adds them to the existing Web parts area on the Web parts page of the host. Then, the Code establishes a connection between them. Note that Web parts and connections are saved as part of User Personalization information, so they should be added only once to webpartmanager. If you do not want to save Web parts and connections in this way, you can also use other APIs.

Figure 6 connection Display Mode

You can see,Figure 5The technology shown in must use the providerconnectionpoint object and consumerconnectionpoint. You can retrieve these objects by calling the methods provided by webpartmanager and passing the string identifiers that name the connection points.

Another technology that you and your users can use to establish a dynamic Web part connection involves the connectionszone control. To effectively use this technology, you should create a Web parts page with a task pane containing the connectionszone control on the right. When the user puts the page in connection View display mode, the connect command is added to the Web Part menu of each Web part of the public connection point, as shown in 6.

When you select the connect command, the connectionszone control is displayed on the web parts page, allowing you to view all compatible connection points of all Web parts that can be connected to the page (seeFigure 7). With this technology, you can connect users to the provider. You can also connect the provider to the user.

Please send TED-related questions and commentsInstinct@Microsoft.com.

Ted PattisonAs a writer and lecturer, he provides hands-on training through his own company. His company name isTed Pattison Group. Ted is currently researching and writing a new book focusing on Windows SharePoint Services "V3" and office 12 server technologies.