WebPart.AuthorizationFilter Property
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.
Gets or sets an arbitrary string to determine whether a WebPart control is authorized to be added to a page.
public:
virtual property System::String ^ AuthorizationFilter { System::String ^ get(); void set(System::String ^ value); };[System.Web.UI.Themeable(false)]
[System.Web.UI.WebControls.WebParts.Personalizable(System.Web.UI.WebControls.WebParts.PersonalizationScope.Shared)]
public virtual string AuthorizationFilter { get; set; }[<System.Web.UI.Themeable(false)>]
[<System.Web.UI.WebControls.WebParts.Personalizable(System.Web.UI.WebControls.WebParts.PersonalizationScope.Shared)>]
member this.AuthorizationFilter : string with get, setPublic Overridable Property AuthorizationFilter As StringProperty Value
A string that authorizes a control to be added to a Web page. The default value is an empty string ("").
- Attributes
Examples
The following code example demonstrates the use of the AuthorizationFilter property. It shows how to set a custom method 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 code, notice that the <asp:webpartmanager> element has the OnAuthorizeWebPart attribute with the name of the event handler assigned to it. This method checks whether the controls on the page have their AuthorizationFilter property value 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 that does not use roles).
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 Web Parts control set does not implement any default behavior for the AuthorizationFilter property. However, the property is provided so that you can assign an arbitrary string value to a custom WebPart control; this property can be checked by the WebPartManager control during its AuthorizeWebPart event to determine whether the control can be added to the page.
In some cases, the AuthorizationFilter property might be used with the ASP.NET role manager feature, so that if a user is in a certain role, and if the string value of the AuthorizationFilter property meets certain conditions set by the developer, then the control can be added. This approach allows developers to create custom views of a page based on a combination of roles and other authorization criteria that they specify.
This property cannot be set by themes or style sheet themes. For more information, see ThemeableAttribute and ASP.NET Themes and Skins.
The personalization scope of this property is set to Shared and can be modified only by authorized users. For more information, see PersonalizableAttribute and Web Parts Personalization Overview.
Notes to Inheritors
To use this property, you must create a custom WebPartManager control, and override either its OnAuthorizeWebPart(WebPartAuthorizationEventArgs) method or its IsAuthorized(WebPart) method to handle the check for the AuthorizationFilter property.
