Walkthrough: Implementing Web Parts Personalization with a User Control

Article
12/04/2014

This walkthrough shows you how to create an ASP.NET user control that relies on Web Parts personalization to provide user-specific default values on a Web page.

ASP.NET Web Parts enable you to build Web pages with modular layouts in which users can modify the appearance and content to suit their preferences. A key Web Parts feature known as personalization lets you save user-specific settings for each page and reuse those settings in future browser sessions.

Using Web Parts and personalization, you can build Web pages that include a feature useful for many Web applications: the ability to supply user-specific default values in a form. This walkthrough demonstrates how to supply user-specific default values by implementing a user control that can be treated as a personalizable Web Parts control. This development approach could be useful if you were creating an application for customer service agents to fill out online forms, for example. The Web Parts and personalization capabilities enable your page to recognize each agent. The user control allows each agent to save default values for the fields on the form, and then the default values can be automatically filled in on subsequent visits to the page.

Note

The user control you create in this walkthrough does not inherit from the WebPart class. But in this walkthrough you learn that a user control can function as a WebPart control. During the walkthrough you add the user control to a WebPartZoneBase zone. Doing so enables ASP.NET to wrap the user control in a GenericWebPart control. The user control will then work like any other WebPart control, and will allow you to explore personalization.

During this walkthrough, you will learn how to:

Create a user control with personalizable properties, whose values can be saved in long-term storage.
Display user-specific default values on a form in a Web page.
Work with the user control in a zone as a true WebPart control.

Note

This type of application could be developed using ASP.NET profiles. However, in this case you are not storing information about the user to be reused across an entire application, as in a shopping cart application. Instead, you are saving user-specific preferences or settings for each control, on a per-page basis. For more information about profiles, see ASP.NET Profile Properties Overview.

Prerequisites

In order to complete this walkthrough, you will need:

Internet Information Services (IIS) installed and configured on the computer that will host the site. For details about installing and configuring IIS, see the IIS Help documentation included with the installation, or see the online IIS documentation on the Microsoft TechNet site (Internet Information Services 6.0 Technical Resources).
An ASP.NET Web site that can identify individual users. If you have such a site already configured, you can use that site as a starting point for this walkthrough. Otherwise, for details on creating a virtual directory or site, see How to: Create and Configure Virtual Directories in IIS 5.0 and 6.0.
A configured personalization provider and database. Web Parts personalization is enabled by default, and it uses the SQL personalization provider (SqlPersonalizationProvider) with the Microsoft SQL Server Standard Edition to store personalization data. This walkthrough uses SSE and the default SQL provider. If you have SSE installed, no configuration is needed. SSE is available with Microsoft Visual Studio 2005 as an optional part of the installation, or as a free download. For details, see the Microsoft SQL Server 2005 Express Edition Web page. To use one of the full versions of SQL Server, you must install and configure an ASP.NET application services database, and configure the SQL personalization provider to connect to that database. For details, see Creating and Configuring the Application Services Database for SQL Server. You can also create and configure a custom provider to use with other, non-SQL databases or storage solutions. For details and a code example see Implementing a Membership Provider.

Creating a Personalizable User Control

In this part of the walkthrough, you create a user control that provides the user interface (UI) for an agent information form. The control also exposes personalizable properties for name and phone information.

Note

You do not need to enable Web Parts personalization; it is enabled by default. For more information about personalization, see Web Parts Personalization Overview.

To create personalizable properties for the user control

In a text editor, create a new file and add the following control declaration to the beginning of the file, along with opening and closing <script> tags:

<%@ control language="VB" classname="AccountUserControl" %>
<script runat="server">
</script>

<%@ control language="C#" classname="AccountUserControl" %>
<script runat="server">
</script>

Within the <script> tags, add code to create two personalizable properties: one named UserName, the other named Phone, as shown in the following example.

Note

Each property has a Personalizable attribute. This enables Web Parts personalization to store the property values in a database.

  <Personalizable()> _
  Property UserName() As String

    Get
      If Textbox1.Text Is Nothing Or Textbox1.Text.Length < 0 Then
          Return String.Empty
      Else
          Return Textbox1.Text
      End If
    End Get

    Set(ByVal value As String)
      Textbox1.Text = value
    End Set

  End Property

  <Personalizable()> _
  Property Phone() As String

    Get
      If Textbox2.Text Is Nothing Or Textbox2.Text.Length < 0 Then
          Return String.Empty
      Else
          Return Textbox2.Text
      End If
    End Get

    Set(ByVal value As String)
      Textbox2.Text = value
    End Set

  End Property

  [Personalizable]
  public string UserName
  {
    get
    {
      if(Textbox1.Text == null | Textbox1.Text.Length < 0)
        return String.Empty;
      else
        return Textbox1.Text;
    }

    set
    {
      Textbox1.Text = value;
    }
  }

  [Personalizable]
  public string Phone
  {
    get
    {
      if(Textbox2.Text == null | Textbox2.Text.Length < 0)
        return String.Empty;
      else
        return Textbox2.Text;
    }

    set
    {
      Textbox2.Text = value;
    }
  }

Security Note
This control has a textbox that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate user input to ensure that the input does not contain HTML elements or script. For more information, see Script Exploits Overview.

Name the file AccountUserControlCS.ascx or AccountUserControlVB.ascx (depending on which language you are using), and save it in the root directory of your Web site.

Now that you have added personalizable properties to save the default values, you can add UI controls to the user control to display a user's name and phone number.

To add UI controls to the user control

Beneath the <script> tags, add a Label control and a TextBox control wrapped by <div> tags to contain the user's name, as shown in the following code example:
```
<div>
<asp:label id="Label1" runat="server">Name</asp:label>
<asp:textbox id="Textbox1" runat="server" />
</div>
```
Beneath the control you just added, add a Label control and a TextBox control wrapped by <div> tags to contain the user's phone number, as in the following example:
```
<div>
<asp:label id="Label2" runat="server">Phone</asp:label>
<asp:textbox id="Textbox2" runat="server" />
</div>
```
Beneath the control you just added, add an <asp:button> element wrapped by <div> tags, to save the user's information by performing a postback:
```
<div>
<asp:button id="Button1" runat="server" 
  text="Save Form Values" />
</div>
```
Save the file.

Referencing the User Control as a Web Parts Control

Now that you have created a user control with personalizable properties, you can create an ASP.NET Web page to host the user control as a Web Parts control. It is necessary to host the control as a Web Parts control in order for personalization features to work.

To reference the user control as a Web Parts control

In a text editor, create a new file and add the following page declaration to the beginning of the file:
```
<%@ page language="VB" %>
```
```
<%@ page language="C#" %>
```

Beneath the page declaration, add a declaration to reference the user control you created previously, as shown in the following example:

<%@ register tagprefix="uc1" 
    tagname="AccountUserControl" 
    src="AccountUserControlvb.ascx"%>

<%@ register tagprefix="uc1" 
    tagname="AccountUserControl" 
    src="AccountUserControlcs.ascx"%>

Beneath the control reference, add the following basic page structure to host the user control as a Web Parts control.

Note

For the user control to work as a Web Parts control, the page must contain an <asp:webpartmanager> element, and the user control must be contained within an <asp:webpartzone> element and a <zonetemplate> element in succession.

<html>
<head runat="server">
    <title>Personalizable User Control</title>
</head>
<body>
    <form id="form1" runat="server">
      <asp:webpartmanager id="WebPartManager1" runat="server"  />
      <asp:webpartzone id="zone1" runat="server" headertext="Main">
        <zonetemplate>
          <uc1:AccountUserControl 
            runat="server" 
            id="accountwebpart"
            title="Agent Information" /> 
        </zonetemplate>
      </asp:webpartzone>
    </form>
</body>
</html>

Name the file Hostaccountcontrol.aspx and save it in the same directory as the user control.

You have now created a personalizable user control, and referenced it as a Web Parts control in a Web Forms page. The final step is to test your user control.

To test the personalizable user control

Load the Hostaccountcontrol.aspx page in a browser.
Enter values in the Name and Phone fields, and click the Save Form Values button.
Close the browser.
Load the page again in a browser.

The values you entered previously appear in the form. These are the values that were saved in the personalizable properties, and were restored from the database when you reloaded the page in the browser.
Enter new values in the form, but do not click the button to save them.
Close the browser.
Load the page again in a browser.

The original values you entered and saved in the personalized properties are the ones that reappear in the form, because you did not save the new values.

Next Steps

This walkthrough has demonstrated the basic tasks involved in creating a user control with personalizable properties. You created a control that allows you to save user-specific settings for the specific control and page, and display those saved settings when the user revisits the page in a new browser session. Suggestions for further exploration include:

Investigate the other components involved in creating a Web Parts page. For an introduction, see Walkthrough: Creating a Web Parts Page.
Learn more about working with user controls. For details, see ASP.NET User Controls Overview.
Learn to create your own custom Web Parts controls, which offer more programmatic control than a user control and provide the full range of Web Parts features. For more information, see How to: Treat a User Control as a Web Parts Control.

Share via

Walkthrough: Implementing Web Parts Personalization with a User Control

Prerequisites

Creating a Personalizable User Control

To create personalizable properties for the user control

To add UI controls to the user control

Referencing the User Control as a Web Parts Control

To reference the user control as a Web Parts control

To test the personalizable user control

Next Steps

See Also

Concepts

Additional resources