Export (0) Print
Expand All

WebPartPersonalization Class

Implements low-level personalization operations.

System.Object
  System.Web.UI.WebControls.WebParts.WebPartPersonalization

Namespace:  System.Web.UI.WebControls.WebParts
Assembly:  System.Web (in System.Web.dll)

public class WebPartPersonalization

The WebPartPersonalization type exposes the following members.

  NameDescription
Public methodWebPartPersonalizationInitializes a new instance of the WebPartPersonalization class.
Top

  NameDescription
Public propertyCanEnterSharedScopeReturns a value indicating whether the user is authorized to enter Shared scope.
Public propertyEnabledReturns a value indicating whether personalization is requested to be enabled for the associated WebPartManager control.
Public propertyHasPersonalizationStateReturns a value indicating whether the current page and personalization scope have associated personalization data.
Public propertyInitialScopeGets or sets the default personalization scope.
Public propertyIsEnabledGets a value that indicates whether personalization is enabled and has successfully loaded personalization data for this instance of the WebPartPersonalization class.
Protected propertyIsInitializedGets a value that indicates whether personalization is enabled and has successfully loaded personalization data for this instance of the WebPartPersonalization class.
Public propertyIsModifiableGets a value that indicates whether the current user is authorized to modify state information.
Public propertyProviderNameGets or sets the provider name for personalization.
Public propertyScopeGets the current personalization scope for the parent WebPartManager control.
Protected propertyShouldResetPersonalizationStateGets or sets a value that indicates whether the personalization data of the current page has been reset (for example, a request was made to delete the personalization data from the underlying data store).
Protected propertyUserCapabilitiesGets the set of user capabilities from WebPartUserCapability granted to the current user.
Protected propertyWebPartManagerGets an instance of the current parent WebPartManager control associated with this WebPartPersonalization instance.
Top

  NameDescription
Protected methodApplyPersonalizationState()Applies personalization data to the parent WebPartManager control.
Protected methodApplyPersonalizationState(WebPart)Applies personalization data to the specified WebPart control when requested to do so by the parent WebPartManager control.
Protected methodChangeScopeChanges the current page's PersonalizationScope instance to the scope specified.
Protected methodCopyPersonalizationStateExtracts the personalization state from one Web Parts control and applies it to a second Web Parts control.
Public methodEnsureEnabledEnsures that the WebPartPersonalization instance has completed initialization or that the current user has rights to modify personalization state.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodExtractPersonalizationState()Extracts personalization data from the parent WebPartManager control.
Protected methodExtractPersonalizationState(WebPart)Extracts personalization data from a Web Parts control when requested to do so by the parent WebPartManager control.
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Protected methodGetAuthorizationFilterRetrieves the authorization filter, if any, associated with the specified Web Parts control.
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodLoadInitializes personalization.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodResetPersonalizationStateResets personalization data for the current page, scope, and user in the underlying data store.
Protected methodSaveSaves personalization data for the current page, scope, and user to the underlying data store.
Protected methodSetDirty()Marks the parent WebPartManager control as having personalization data that has changed (is "dirty").
Protected methodSetDirty(WebPart)Marks the specified Web Parts control as having personalization data that has changed (is "dirty").
Public methodToggleScopeSwitches the current page's personalization scope from User to Shared or from Shared to User.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

  NameDescription
Public fieldStatic memberEnterSharedScopeUserCapabilityRepresents the WebPartUserCapability instance of a user's authorization to enter Shared scope.
Public fieldStatic memberModifyStateUserCapabilityRepresents the WebPartUserCapability instance of a user's authorization to modify personalization state.
Top

This class implements the logic required to carry out lower-level personalization operations. Although the WebPartManager class manages the high-level life cycle of personalization, it is the WebPartPersonalization class that is responsible for actually implementing the physical steps necessary to carry out specific personalization actions. The WebPartPersonalization class in turn relies on an implementation of PersonalizationProvider to communicate with the underlying data store for personalization information.

If you use the default implementation of the WebPartManager, it creates an instance of the WebPartPersonalization class that you can use by referencing the Personalization property. For example, to access the InitialScope property, you would specify WebPartManager.Personalization.InitialScope.

Notes to Inheritors

The WebPartPersonalization class works closely with a WebPartManager control and the rest of the personalization infrastructure. The default implementation of personalization is a very robust subsystem that should meet your personalization needs. In most cases, if you want to customize personalization, you can create a data provider for use as a personalization provider by creating a class that inherits from PersonalizationProvider.

If you want to create a personalization subsystem significantly different from that provided by the WebPartPersonalization and the WebPartManager classes, you should create a custom WebPartPersonalization implementation by deriving from WebPartPersonalization and add your own custom logic. Then create a custom WebPartManager implementation by deriving from WebPartManager, add your own custom logic, and override the CreatePersonalization method to return your custom WebPartPersonalization implementation. Because a WebPartManager control makes requests to the personalization infrastructure by way of a WebPartPersonalization instance, the WebPartManager control does not directly interact with or hold references to PersonalizationProvider implementations.

TopicLocation
How to: Enable Shared Personalization of ASP.NET Web Parts PagesBuilding ASP .NET Web Applications
How to: Disable Web Parts PersonalizationBuilding ASP .NET Web Applications
How to: Enable Shared Personalization of ASP.NET Web Parts PagesBuilding ASP .NET Web Applications
How to: Disable Web Parts PersonalizationBuilding ASP .NET Web Applications

The following code example shows how the WebPartPersonalization class is used, as well as providing an example of how personalization scope affects the results of personalized properties. This example has five files:

  • An .aspx page that declaratively creates two Web Part zones, each with a control.

  • A user control called Color.ascx that allows a user to change a personalized property that applies a text box background color based on the user's authorization rights to modify state information and to enter shared scope.

  • A user control called Persmode.ascx that indicates what the current page scope is and what rights the current user has to enter shared scope or to modify data; it also provides two buttons; one to change scope and one to reset current user personalization information.

  • A login control that is used to authorize users.

  • A Web.config file with a section that provides an example of authorizing a user to modify personalization state and to enter shared scope.

The following code creates an aspx page with a WebPartManager and two Web Part zones and displays the Color.ascx and Persmode.ascx controls. The page loads a login page that is used to get the current user information. Use the ASP.NET Web Site Administration Tool in Microsoft Visual Studio 2005 to create users to access the page. See the Web.config file for an example of a user granted authorization in the configuration file to change scope and modify state information.

<%@ Page Language="C#" %>
<%@ Register TagPrefix="control"  TagName="colorcontrol" Src="~/color.ascx"%>
<%@Register TagPrefix="pmode" TagName="persmode" Src="~/persMode.ascx" %>


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
        <!-- Create Web Part manager and zone for the color user control. -->
        <asp:WebPartManager ID="WebPartManager1" runat="server"></asp:WebPartManager>
            <asp:WebPartZone ID="WebPartZone1" runat="server" HeaderText="Color Change Zone">
                <ZoneTemplate>
                <!-- Note that the control is Shared since it is declared on the page. -->
                    <control:colorcontrol id="color1" title="Color Control" runat="server" />
                </ZoneTemplate>
            </asp:WebPartZone>

        <br />
            <!-- Create Web Part zone for the personalization mode user control. -->
            <asp:WebPartZone ID="WebPartZone2" runat="server" HeaderText="Scope Change Zone" Height="109px">
                <ZoneTemplate>
                    <pmode:persmode  ID="Persmode1" runat="server" title="Scope Tool"/>
                </ZoneTemplate>
            </asp:WebPartZone>

    </form>
</body>
</html>

The following example code creates a login page. After a successful login, it redirects to the main aspx page.

Security noteSecurity Note

This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

<%@ 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">

</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:Login ID="Login1" runat="server" BorderWidth="1px" BorderColor="#E6E2D8" BorderPadding="4"
            BorderStyle="Solid" BackColor="#F7F6F3" ForeColor="#333333" Font-Names="Verdana"
            Font-Size="0.8em" DestinationPageUrl="~/Defaultcs.aspx">
            <InstructionTextStyle ForeColor="Black" Font-Italic="True" Font-Size="0.8em" />
            <LoginButtonStyle Font-Names="Verdana" Font-Size="0.8em" BorderStyle="Solid" BorderWidth="1px"
                BorderColor="#CCCCCC" BackColor="#FFFBFF" ForeColor="#284775" />
            <TextBoxStyle Font-Size="0.8em" />
            <LabelStyle Font-Size="0.8em" />
            <TitleTextStyle ForeColor="White" Font-Size="0.9em" Font-Bold="True" BackColor="#5D7B9D" />
            <HyperLinkStyle Font-Size="0.8em" />
            <CheckBoxStyle Font-Size="0.8em" />
            <FailureTextStyle ForeColor="#FF0000" Font-Size="0.8em" />
        </asp:Login>   
You can create new users with the ASP.NET Web Site Administration Tool in Microsoft Visual Studio 2005. 
See also the web.config file for user authorization examples.
    </div>
    </form>
</body>
</html>

The following example code is a portion of the Web.config file for this application. This section shows how to set authorization for a user, in this case "user2", to enter shared personalization scope and to modify personalization state information. It also shows an example of a role, in this case "admin", that can be used to allow users in the "admin" role to enter shared personalization scope and to modify personalization state information.

		<webParts>
			<personalization defaultProvider="AspNetSqlPersonalizationProvider">
				<authorization>
					<allow users="user2" verbs="enterSharedScope, modifyState"/>
					<allow roles="admin" verbs="enterSharedScope, modifyState"/>
				</authorization>
			</personalization>
		</webParts>

The following example code creates a user control, called Color.ascx, that allows the user to change a personalized property, in this case the background color of two text boxes, based on the current personalization scope and the authorization rights of the user.

Security noteSecurity Note

This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

<%@ Control Language="C#" %>

<script runat="server">
    // User a field to reference the current WebPartManager.
    private WebPartManager _manager;

    //  Defines personalized property for User scope. In this case, the property is
    //   the background color of the text box.
    [Personalizable(PersonalizationScope.User)]
    public System.Drawing.Color UserColorChoice
    {
        get
        {
            return _coloruserTextBox.BackColor;
        }
        set
        {
            _coloruserTextBox.BackColor = value;
        }
    }

    // Defines personalized property for Shared scope. In this case, the property is
    //   the background color of the text box.
    [Personalizable(PersonalizationScope.Shared) ]
    public System.Drawing.Color SharedColorChoice
    {
        get
        {
            return _colorsharedTextBox.BackColor;
        }
        set
        {
            _colorsharedTextBox.BackColor = value;
        }
    }


    void Page_Init(object sender, EventArgs e)
    {
       _manager = WebPartManager.GetCurrentWebPartManager(Page);       
    }

    protected void Page_Load(object src, EventArgs e) 
    {
     // If Web Parts manager scope is User, hide the button that changes shared control.
       if (_manager.Personalization.Scope == PersonalizationScope.User)
       {
           _sharedchangeButton.Visible = false;
                  if (!_manager.Personalization.IsModifiable)
                      _userchangeButton.Enabled = false;
       }
       else
       {
           _sharedchangeButton.Visible = true; 
                  if (!_manager.Personalization.IsModifiable)
                    {
                      _sharedchangeButton.Enabled = false;
                      _userchangeButton.Enabled = false;
                    }
       } 
    }

    // Changes color of the User text box background when button clicked by authorized user.
    protected void _userButton_Click(object src, EventArgs e)
    {
        switch(_coloruserTextBox.BackColor.Name)
        {
            case "Red":
                _coloruserTextBox.BackColor = System.Drawing.Color.Yellow;
                break;
            case "Yellow":
                _coloruserTextBox.BackColor = System.Drawing.Color.Green;
                break;
            case "Green":
                _coloruserTextBox.BackColor = System.Drawing.Color.Red;
                break;
        }
    }

    // Changes color of the Shared text box background when button clicked by authorized user.
    protected void _sharedButton_Click(object src, EventArgs e)
    {
        switch (_colorsharedTextBox.BackColor.Name)
        {
            case "Red":
                _colorsharedTextBox.BackColor = System.Drawing.Color.Yellow;
                break;
            case "Yellow":
                _colorsharedTextBox.BackColor = System.Drawing.Color.Green;
                break;
            case "Green":
                _colorsharedTextBox.BackColor = System.Drawing.Color.Red;
                break;
        }        
    }   

</script>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>WebParts Personalization Example</title>
</head>
<body>
<p>
    <asp:LoginName ID="LoginName1" runat="server" BorderWidth="500" BorderStyle="none" />
    <asp:LoginStatus ID="LoginStatus1" LogoutAction="RedirectToLoginPage" runat="server" />
</p>
    <asp:Label ID="ScopeLabel" Text="Scoped Properties:" runat="server" Width="289px"></asp:Label>
    <br />
    <table style="width: 226px">

        <tr>
            <td>
                <asp:TextBox ID="_coloruserTextBox" Font-Bold="True" Height="110px" 
                runat="server" Text="User Property" BackColor="red" Width="110px" /> 
            </td>
            <td>       
                <asp:TextBox ID="_colorsharedTextBox" runat="server" Height="110px" 
                Width="110px" Text="Shared Property" BackColor="red" Font-Bold="true" />
            </td>
       </tr>
        <tr>
            <td>
                <asp:Button Text="Change User Color" ID="_userchangeButton" 
                runat="server" OnClick="_userButton_Click" />
            </td>
            <td >
                <asp:Button Text="Change Shared Color" ID="_sharedchangeButton" 
                runat="server" OnClick="_sharedButton_Click" />
            </td>
        </tr>
    </table>
</body>
</html>

The following example code creates a user control, called Persmode.ascx, that shows the current personalization scope and the user rights to modify state and to enter shared scope. It also has a reset button for resetting the current personalization state.

<%@ control language="C#" %>

<script runat="server">

 // Use a field to reference the current WebPartManager.
  private WebPartManager _manager;

    protected void Page_Load(object src, EventArgs e)
    {
        // Get the current Web Parts manager.
        _manager = WebPartManager.GetCurrentWebPartManager(Page);

        // All radio buttons are disabled; the button settings show what the current state is.
        EnterSharedRadioButton.Enabled = false;
        ModifyStateRadioButton.Enabled = false;

        // If Web Parts manager is in User scope, set scope button.
        if (_manager.Personalization.Scope == PersonalizationScope.User)
            UserScopeRadioButton.Checked = true;
        else
            SharedScopeRadioButton.Checked = true;

        // Based on current user rights to enter Shared scope, set buttons.
        if (_manager.Personalization.CanEnterSharedScope)
        {
            EnterSharedRadioButton.Checked = true;
            No_Shared_Scope_Label.Visible = false;
            Toggle_Scope_Button.Enabled = true;
        }
        else
        {
            EnterSharedRadioButton.Checked = false;
            No_Shared_Scope_Label.Visible = true;
            Toggle_Scope_Button.Enabled = false;
        }

        // Based on current user rights to modify personalization state, set buttons.
        if (_manager.Personalization.IsModifiable)
        {
            ModifyStateRadioButton.Checked = true;
            Reset_User_Button.Enabled = true;
        }
        else
        {
            ModifyStateRadioButton.Checked = false;
            Reset_User_Button.Enabled = false;
        }
    }
  // Resets all of a user and shared personalization data for the page.
    protected void Reset_CurrentState_Button_Click(object src, EventArgs e)
    {
        // User must be authorized to modify state before a reset can occur.
        //When in user scope, all users by default can change their own data.
        if (_manager.Personalization.IsModifiable)
        {
            _manager.Personalization.ResetPersonalizationState();
        }
    }

    // Allows authorized user to change personalization scope.
    protected void Toggle_Scope_Button_Click(object sender, EventArgs e)
    {
        if (_manager.Personalization.CanEnterSharedScope)
        {
            _manager.Personalization.ToggleScope();
        }

    }
</script>
<div>
    &nbsp;<asp:Panel ID="Panel1" runat="server" 
    Borderwidth="1" 
    Width="208px" 
    BackColor="lightgray"
    Font-Names="Verdana, Arial, Sans Serif" Height="214px" >
    <asp:Label ID="Label1" runat="server" 
      Text="Page Scope" 
      Font-Bold="True"
      Font-Size="8pt"
      Width="120px" />&nbsp;<br />


      <asp:RadioButton ID="UserScopeRadioButton" runat="server" 
        Text="User" 
        AutoPostBack="true"
        GroupName="Scope"  
         Enabled="false" />
      <asp:RadioButton ID="SharedScopeRadioButton" runat="server" 
        Text="Shared" 
        AutoPostBack="true"
        GroupName="Scope" 
        Enabled="false" />
        <br />
        <asp:Label BorderStyle="None" Font-Bold="True" Font-Names="Courier New" ID="No_Shared_Scope_Label" Font-Size="Smaller" ForeColor="red"
           runat="server" Visible="false" Width="179px">User cannot enter Shared scope</asp:Label>
        <br />
        <asp:Label ID="Label2" runat="server" 
      Text="Current User Can:" 
      Font-Bold="True"
      Font-Size="8pt"
      Width="165px" />
      <br />
        <asp:RadioButton ID="ModifyStateRadioButton" runat="server" 
        Text="Modify State" Width="138px" />
        <br />
        <asp:RadioButton ID="EnterSharedRadioButton" runat="server" 
        Text="Enter Shared Scope" 
        AutoPostBack="true"  />&nbsp;<br />
        <br />
        <asp:Button ID="Toggle_Scope_Button" OnClick="Toggle_Scope_Button_Click" runat="server"
            Text="Change Scope" Width="186px" /><br />
        <br />
        <asp:Button ID="Reset_User_Button" OnClick="Reset_CurrentState_Button_Click" runat="server"
            Text="Reset Current Personalization" Width="185px" /></asp:Panel>
    &nbsp; &nbsp;
</div>

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0, 2.0

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft