Determines whether a WebPart or other server control can be added to a page.
This member is overloaded. For complete information about this member, including syntax, usage, and examples, click a name in the overload list.
Part of the flexibility of the Web Parts feature is the ability to add server controls to Web pages at run time. There are a number of common scenarios in which a server control (which can be a custom WebPart control, a custom server control, a user control, or an ASP.NET control) can be added.
In the following common scenarios, the Web Parts control set attempts to add server controls to a page, and the method is called to authorize them:
When a server control is added by declaring it in the markup of a Web page within a WebPartZoneBase zone.
When a server control is added programmatically to a zone.
When a user imports a server control into a Web Parts catalog of controls.
When an existing server control is loaded from the personalization data store.
When a server control is added to a DeclarativeCatalogPart control to make it available in a catalog of server controls.
In each scenario where controls are added, the method is called to ensure that all authorization criteria have been met to allow a control to be added. When a control is authorized, it is added normally as it would be if there was no filtering scenario. When a control is not authorized, the Web Parts control set can respond in several ways, depending on the context. The control set can silently fail to add an unauthorized part (if there is no need to inform the user), it can display an error message, or it can add an instance of the UnauthorizedWebPart class as a placeholder. This placeholder object is not visible on the page, but is visible in the page source code to indicate that an unauthorized control was excluded.
The determinant of whether a control is authorized is the authorization filter. An authorization filter is a feature in the Web Parts control set that enables developers to exclude from a page any controls that do not meet the specified criteria.
To create a filtering scenario, developers must do two things. First, they must assign a string value (the value can be arbitrary) to the AuthorizationFilter property of each WebPart control they plan to use in the scenario. They can also assign a value to this property for other types of server controls that are not WebPart controls, because if they are placed in WebPartZoneBase zones, such controls are wrapped with a GenericWebPart control at run time, and this control inherits the AuthorizationFilter property.
The second necessary step for creating a filtering scenario is to either override the IsAuthorized(Type, String, String, Boolean) method, or to create an event handler for the AuthorizeWebPart event. In these methods, a developer can check the AuthorizationFilter property, and if the value indicates that the control should not be authorized, the developer ensures that the method returns a value of false.
For code examples and a description of how to set up a customized filtering scenario using the method, see the topics for the overloads of the method.