WebPartManager.OnAuthorizeWebPart(WebPartAuthorizationEventArgs) Method
Definition
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.
Raises the AuthorizeWebPart event and invokes a handler for the event, if one exists.
protected:
virtual void OnAuthorizeWebPart(System::Web::UI::WebControls::WebParts::WebPartAuthorizationEventArgs ^ e);protected virtual void OnAuthorizeWebPart (System.Web.UI.WebControls.WebParts.WebPartAuthorizationEventArgs e);abstract member OnAuthorizeWebPart : System.Web.UI.WebControls.WebParts.WebPartAuthorizationEventArgs -> unit
override this.OnAuthorizeWebPart : System.Web.UI.WebControls.WebParts.WebPartAuthorizationEventArgs -> unitProtected Overridable Sub OnAuthorizeWebPart (e As WebPartAuthorizationEventArgs)Parameters
A WebPartAuthorizationEventArgs that contains event data.
Examples
The following code example demonstrates how to set a custom event handler for the AuthorizeWebPart event, so that the handler can provide custom filtering code for the OnAuthorizeWebPart method. This example would be a typical way for a page developer to provide a filtering scenario and authorization of WebPart controls to be added to a page.
In the Web page, notice that the <asp:webpartmanager> element has the OnAuthorizeWebPart attribute with the name of the event handler assigned to it. The method checks whether the controls on the page have their respective AuthorizationFilter property values set to admin and, if so, returns true, which means that they will be authorized and added to the page.
Note
Note that controls that do not have any value assigned to the AuthorizationFilter property are added as well, because they are assumed not to be part of a filtering scenario. This would be a common approach in a filtering scenario: some controls would be filtered, and others would not be, because they are presumed to be available for all users.
<%@ Page Language="C#" %>
<!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 mgr1_AuthorizeWebPart(object sender,
WebPartAuthorizationEventArgs e)
{
if (!String.IsNullOrEmpty(e.AuthorizationFilter))
{
if (e.AuthorizationFilter == "user")
e.IsAuthorized = true;
else
e.IsAuthorized = 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="mgr1" runat="server"
OnAuthorizeWebPart="mgr1_AuthorizeWebPart" />
<asp:WebPartZone ID="WebPartZone1" runat="server">
<ZoneTemplate>
<asp:BulletedList
ID="BulletedList1"
Runat="server"
DisplayMode="HyperLink"
Title="Favorite Links"
AuthorizationFilter="admin">
<asp:ListItem Value="http://msdn.microsoft.com">
MSDN
</asp:ListItem>
<asp:ListItem Value="http://www.asp.net">
ASP.NET
</asp:ListItem>
<asp:ListItem Value="http://www.msn.com">
MSN
</asp:ListItem>
</asp:BulletedList>
<asp:Label ID="Label1" runat="server"
Text="Hello World"
Title="Filter Test"
AuthorizationFilter="admin" />
<asp:Calendar ID="Calendar1" runat="server"
Title="My Calendar"/>
</ZoneTemplate>
</asp:WebPartZone>
</div>
</form>
</body>
</html>
<%@ Page Language="vb" %>
<!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 mgr1_AuthorizeWebPart(ByVal sender As Object, _
ByVal e As WebPartAuthorizationEventArgs)
If Not String.IsNullOrEmpty(e.AuthorizationFilter) Then
If e.AuthorizationFilter = "user" Then
e.IsAuthorized = True
Else
e.IsAuthorized = False
End If
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="mgr1" runat="server"
OnAuthorizeWebPart="mgr1_AuthorizeWebPart" />
<asp:WebPartZone ID="WebPartZone1" runat="server">
<ZoneTemplate>
<asp:BulletedList
ID="BulletedList1"
Runat="server"
DisplayMode="HyperLink"
Title="Favorite Links"
AuthorizationFilter="admin">
<asp:ListItem Value="http://msdn.microsoft.com">
MSDN
</asp:ListItem>
<asp:ListItem Value="http://www.asp.net">
ASP.NET
</asp:ListItem>
<asp:ListItem Value="http://www.msn.com">
MSN
</asp:ListItem>
</asp:BulletedList>
<asp:Label ID="Label1" runat="server"
Text="Hello World"
Title="Filter Test"
AuthorizationFilter="admin" />
<asp:Calendar ID="Calendar1" runat="server"
Title="My Calendar"/>
</ZoneTemplate>
</asp:WebPartZone>
</div>
</form>
</body>
</html>
Because setting up users in roles is beyond the scope of this topic, this code example does not check user roles in the filtering. However, the scenario of filtering controls according to user roles is likely to be one of the most common uses of this filtering feature. If you have roles on your site, and you want to check user roles in this method to filter controls, the method would resemble the following code block (versus the simpler approach in the preceding code example, which does not use roles).
Protected Sub WebPartManager1_AuthorizeWebPart(ByVal sender _
As Object, ByVal e As WebPartAuthorizationEventArgs)
If String.IsNullOrEmpty(e.AuthorizationFilter) Then
If Roles.IsUserInRole(Page.User.Identity.Name, _
e.AuthorizationFilter) Then
e.IsAuthorized = True
Else
e.IsAuthorized = False
End If
End If
End Sub
protected void mgr1_AuthorizeWebPart(object sender,
WebPartAuthorizationEventArgs e)
{
if (!String.IsNullOrEmpty(e.AuthorizationFilter))
{
if(Roles.IsUserInRole(Page.User.Identity.Name, e.authorizationFilter))
e.IsAuthorized = true;
else
e.IsAuthorized = false;
}
}
Remarks
The OnAuthorizeWebPart method is called by the IsAuthorized method, when a WebPart control is being checked for authorization to be added to a page. When the OnAuthorizeWebPart method is called, it raises the AuthorizeWebPart event, and if there is a handler method for the event, it invokes the handler.
The process of authorizing WebPart controls is an important Web Parts feature. Every WebPart or server control that is added to a zone by the WebPartManager control goes through an authorization process to determine whether the control can be added. By default, the Web Parts control set does not provide any filtering criteria to prevent controls from being added to a zone. But the control set does provide the mechanisms necessary for developers to create their own filtering criteria. By using these mechanisms, you can create custom filtering scenarios. For example, you could create a filter so that, if a user is in an administrator role, certain controls would be added to a zone when the page is rendered, and if the user is in a user role, those controls would not be added.
The mechanisms for filtering controls during the authorization process are the AuthorizationFilter property on WebPart controls, the IsAuthorized and OnAuthorizeWebPart methods, and the AuthorizeWebPart event on the WebPartManager control.
To create a filtering scenario, there are essentially two tasks. First, you assign strings to the AuthorizationFilter property of each WebPart control you want to filter. These string values can be arbitrary, but they should contain the criteria you want to filter on. For example, if you wanted a given control to be added to a zone only if an administrator user is viewing the page, then you might assign a string value of admin to the property. Then you could use the ASP.NET roles feature, and add all users of your site to various roles such as administrator, manager, and user. When a page is loading, your filtering code would check what role a user is in, compare it to the authorization filter value on a control being checked, and if (for example) the user is in an administrator role and you had set the control's AuthorizationFilter value to admin, the control could be added.
The second step in creating a filtering scenario is to write code to check the AuthorizationFilter property values on WebPart controls, and determine whether each control is authorized before it is added to its zone. There are two options for where to place this filtering code. The first option is the preferred option for page developers. You can create a method to handle the AuthorizeWebPart event directly in the Web page server script code, or in a code separation file. Associate your method with the event by adding the OnAuthorizeWebPart attribute to the tag for the WebPartManager control in the page, as shown in the following sample markup code.
<asp:webpartmanager id="manager1" runat="server"
OnAuthorizeWebPart="manager1_AuthorizeWebPart" />
All your custom method has to do is check each WebPart control for the filtering criteria and then, based on the results, assign a Boolean value to the IsAuthorized property of the WebPartAuthorizationEventArgs object to indicate whether the WebPart control can be added. The code in the Example section demonstrates how to do this.
The second option for where to place your filtering code is to inherit from the WebPartManager class, and override a method to check the filter criteria. The two methods you can override to do this are the WebPartManager.IsAuthorized(Type, String, String, Boolean) method or the OnAuthorizeWebPart method. Although either method would work, in most cases it is preferable to override the IsAuthorized method, because it provides you with greater programmatic control over the whole authorization process, whereas the OnAuthorizeWebPart method does only one specific task, which is to raise the event and check for a handler. For a code example of a custom WebPartManager class that overrides the IsAuthorized method, see the WebPartManager.IsAuthorized(Type, String, String, Boolean) overload of the method.
