WebPart.RegisterInterface Method (String, String, Int32, ConnectionRunAt, Object, String, String, String)

NOTE: This API is now obsolete.

Registers an interface from the Microsoft.SharePoint.WebPartPages.Communication namespace for a connectable Web Part.

Namespace:  Microsoft.SharePoint.WebPartPages
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: No

Syntax

'Declaration
<ObsoleteAttribute("Use ConnectionProvider or ConnectionConsumer attribute to create ConnectionPoint instead.")> _
Protected Sub RegisterInterface ( _
    interfaceName As String, _
    interfaceType As String, _
    maxConnections As Integer, _
    runAtOptions As ConnectionRunAt, _
    interfaceObject As Object, _
    interfaceClientReference As String, _
    menuLabel As String, _
    description As String _
)
'Usage
Dim interfaceName As String
Dim interfaceType As String
Dim maxConnections As Integer
Dim runAtOptions As ConnectionRunAt
Dim interfaceObject As Object
Dim interfaceClientReference As String
Dim menuLabel As String
Dim description As String

Me.RegisterInterface(interfaceName, _
    interfaceType, maxConnections, runAtOptions, _
    interfaceObject, interfaceClientReference, _
    menuLabel, description)
[ObsoleteAttribute("Use ConnectionProvider or ConnectionConsumer attribute to create ConnectionPoint instead.")]
protected void RegisterInterface(
    string interfaceName,
    string interfaceType,
    int maxConnections,
    ConnectionRunAt runAtOptions,
    Object interfaceObject,
    string interfaceClientReference,
    string menuLabel,
    string description
)

Parameters

  • interfaceName
    Type: System.String

    The friendly name of the interface.

  • interfaceObject
    Type: System.Object

    A reference to the implemented interface.

  • interfaceClientReference
    Type: System.String

    The string used to reference the interface in script for client-side connections, for example RowProviderInterface_WPQ_.

  • menuLabel
    Type: System.String

    The label that will be used in the user interface for creating a Web Part connection with this interface.

  • description
    Type: System.String

    A brief description of the interface that will be used in the user interface for creating a Web Part connection with this interface.

Remarks

When developing a connectable Web Part, you should call this method one time for each interface in the EnsureInterfaces method for the Web Part.

This method is one of two overloaded RegisterInterface methods. It does not include the allowCrossPageConnection parameter in its function signature, which allows you to specify whether a connection interface is exposed in the user interface of authoring environments for creating a connection across two Web Part pages. In this version of the method, the allowCrossPageConnection parameter defaults to true for all connection interfaces that are supported by the connection compatibility rules defined by the Web Part infrastructure, and false for all other connection interfaces.

To specify the allowCrossPageConnection parameter, use the [RegisterInterface(String,String,Int32,Microsoft.SharePoint.WebPartPages.Communication.ConnectionRunAt,object,String,String,String,Boolean)] method instead.

Examples

The following code example shows an overridden EnsureInterfaces method that calls the RegisterInterface method. This code example is part of a larger example provided for the ICellProvider interface.

For an overview of the steps for creating a connectable Web Part, see Walkthrough: Creating Connectable Web Parts in SharePoint Foundation.

' Step #4: Override the EnsureInterfaces() method and call the RegisterInterface method.
Public Overrides Sub EnsureInterfaces()
    ' If your Web Part is installed in the bin directory and the Code Access Security (CAS) setting doesn't 
    ' allow Web Part Connections, an exception will be thrown. To allow your Web Part to behave 
    ' well and continue working, a try/catch block should be used when attempting to register interfaces.
    ' Web Part Connections will only work if the level attribute of the <trust> tag in the 
    ' web.config file is set to WSS_Minimal, WSS_Medium, or Full. By default a new SharePoint site
    ' is installed with the trust level set to WSS_Minimal.
    Try
       ' Register the ICellProvider Interface
       ' <param name="interfaceName">Friendly name of the interface that is being implemented.
       ' It must be unique on the client so the _WPQ_ token is used.</param>
       ' <param name="interfaceType">Specifies which interface is being implemented.</param>
       ' <param name="maxConnections">Defines how many times this interface can be connected.</param>
       ' <param name="runAtOptions">Determines where the interface can run.</param>
       ' <param name="interfaceObject">Reference to the object that is implementing this interface.</param>
       ' <param name="interfaceClientReference">Name used to reference the interface on the client. 
       ' It must be unique on the client so the _WPQ_ token is used.</param>
       ' <param name="menuLabel">Label for the interface which appears in the UI</param>
       ' <param name="description">Description of the interface which appears in the UI</param>
       ' <param name="allowCrossPageConnection">Specifies if the interface can connect to a Web Part
       ' on a different page. This is an optional parameter with a default of false. Note that only some 
       ' server-side interfaces are allowed to connect across pages by the Web Part Infrastructure. 
       ' The ICellProvider interface is not allowed to connect across pages.</param>
       RegisterInterface("MyCellProviderInterface_WPQ_", InterfaceTypes.ICellProvider, WebPart.UnlimitedConnections, ConnectionRunAt.Server, Me, "CellProviderInterface_WPQ_", "Provide Cell To", "Provides a single value to a cell consumer Web Part.") 

    Catch se As SecurityException
            _registrationErrorOccurred = True
    End Try
End Sub
// Step #4: Override the EnsureInterfaces() method and call the RegisterInterface method.
public override void EnsureInterfaces()
{
    // If your Web Part is installed in the bin directory and the Code Access Security (CAS) setting doesn't 
    // allow Web Part Connections, an exception will be thrown. To allow your Web Part to behave 
    // well and continue working, a try/catch block should be used when attempting to register interfaces.
    // Web Part Connections will only work if the level attribute of the <trust> tag in the 
    // web.config file is set to WSS_Minimal, WSS_Medium, or Full. By default a new SharePoint site
    // is installed with the trust level set to WSS_Minimal.
    try
    {
        // Register the ICellProvider Interface
        // <param name="interfaceName">Friendly name of the interface that is being implemented.
        // It must be unique on the client so the _WPQ_ token is used.</param>
        // <param name="interfaceType">Specifies which interface is being implemented.</param>
        // <param name="maxConnections">Defines how many times this interface can be connected.</param>
        // <param name="runAtOptions">Determines where the interface can run.</param>
        // <param name="interfaceObject">Reference to the object that is implementing this interface.</param>
        // <param name="interfaceClientReference">Name used to reference the interface on the client. 
        // It must be unique on the client so the _WPQ_ token is used.</param>
        // <param name="menuLabel">Label for the interface which appears in the UI</param>
        // <param name="description">Description of the interface which appears in the UI</param>
        // <param name="allowCrossPageConnection">Specifies if the interface can connect to a Web Part
        // on a different page. This is an optional parameter with a default of false. Note that only some 
        // server-side interfaces are allowed to connect across pages by the Web Part infrastructure. 
        // The ICellProvider interface is not allowed to connect across pages.</param>
        RegisterInterface("MyCellProviderInterface_WPQ_",            //InterfaceName    
            InterfaceTypes.ICellProvider,                            //InterfaceType
            WebPart.UnlimitedConnections,                            //MaxConnections
            ConnectionRunAt.Server,                                  //RunAtOptions
            this,                                                    //InterfaceObject
            "CellProviderInterface_WPQ_",                            //InterfaceClientReference
            "Provide Cell To",                                       //MenuLabel
            "Provides a single value to a cell consumer Web Part."); //Description
    }
    catch(SecurityException se)
    {
        _registrationErrorOccurred = true;
    }
}

See Also

Reference

WebPart Class

WebPart Members

RegisterInterface Overload

Microsoft.SharePoint.WebPartPages Namespace