Partager via

UpdateProgress Control Overview

  • Article

The UpdateProgress control provides status information about partial-page updates in UpdatePanel controls. You can customize the default content and the layout of the UpdateProgress control. To prevent flashing when a partial-page update is very fast, you can specify a delay before the UpdateProgress control is displayed.

This topic contains information about the following:

  • Scenarios

  • Background

  • Code Examples

  • Class Reference

Scenarios

The UpdateProgress control helps you design a more intuitive UI when a Web page contains one or more UpdatePanel controls for partial-page rendering. If a partial-page update is slow, you can use the UpdateProgress control to provide visual feedback about the status of the update. You can put multiple UpdateProgress controls on a page, each associated with a different UpdatePanel control. Alternatively, you can use one UpdateProgress control and associate it with all UpdatePanel controls on the page.

Background

The UpdateProgress control renders a <div> element that is displayed or hidden depending on whether an associated UpdatePanel control has caused an asynchronous postback. For initial page rendering and for synchronous postbacks, the UpdateProgress control is not displayed.

Associating an UpdateProgress Control with an UpdatePanel Control

You associate an UpdateProgress control with an UpdatePanel control by setting the AssociatedUpdatePanelID property of the UpdateProgress control. When a postback event originates from an UpdatePanel control, any associated UpdateProgress controls are displayed. If you do not associate the UpdateProgress control with a specific UpdatePanel control, the UpdateProgress control displays progress for any asynchronous postback.

If the ChildrenAsTriggers property of a UpdatePanel control is set to false and an asynchronous postback originates from inside that UpdatePanel control, any associated UpdateProgress controls will be displayed.

Creating Content for the UpdateProgress Control

Use the ProgressTemplate property to declaratively specify the message displayed by an UpdateProgress control. The <ProgressTemplate> element can contain HTML and markup. The following example shows how to specify a message for an UpdateProgress control.

<asp:UpdateProgress ID="UpdateProgress1" runat="server">
<ProgressTemplate>
  An update is in progress...
</ProgressTemplate>
</asp:UpdateProgress>

<asp:UpdateProgress ID="UpdateProgress1" runat="server">
<ProgressTemplate>
  An update is in progress...
</ProgressTemplate>
</asp:UpdateProgress>

The following example shows one UpdateProgress control that shows update status for two UpdatePanel controls.

<%@ Page Language="VB" %>

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

<script runat="server">
    Protected Sub Button_Click(ByVal sender As Object, ByVal e As System.EventArgs)
        System.Threading.Thread.Sleep(3000)
    End Sub
</script>

<html xmlns="https://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>UpdateProgress Example</title>
    <style type="text/css">
    #UpdatePanel1, #UpdatePanel2, #UpdateProgress1 { 
      border-right: gray 1px solid; border-top: gray 1px solid; 
      border-left: gray 1px solid; border-bottom: gray 1px solid;
    }
    #UpdatePanel1, #UpdatePanel2 { 
      width:200px; height:200px; position: relative;
      float: left; margin-left: 10px; margin-top: 10px;
     }
     #UpdateProgress1 {
      width: 400px; background-color: #FFC080; 
      bottom: 0%; left: 0px; position: absolute;
     }
    </style>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <asp:ScriptManager ID="ScriptManager1" runat="server" />
    <asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button1" runat="server" Text="Refresh Panel" OnClick="Button_Click" />    
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdatePanel ID="UpdatePanel2" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button2" runat="server" Text="Refresh Panel" OnClick="Button_Click"/>    
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdateProgress ID="UpdateProgress1" runat="server">
    <ProgressTemplate>
      Update in progress...
    </ProgressTemplate>
    </asp:UpdateProgress>
    </div>
    </form>
</body>
</html>

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

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

<script runat="server">
    protected void Button_Click(object sender, EventArgs e)
    {
        System.Threading.Thread.Sleep(3000);
    }
</script>

<html xmlns="https://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>UpdateProgress Example</title>
    <style type="text/css">
    #UpdatePanel1, #UpdatePanel2, #UpdateProgress1 { 
      border-right: gray 1px solid; border-top: gray 1px solid; 
      border-left: gray 1px solid; border-bottom: gray 1px solid;
    }
    #UpdatePanel1, #UpdatePanel2 { 
      width:200px; height:200px; position: relative;
      float: left; margin-left: 10px; margin-top: 10px;
     }
     #UpdateProgress1 {
      width: 400px; background-color: #FFC080; 
      bottom: 0%; left: 0px; position: absolute;
     }
    </style>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <asp:ScriptManager ID="ScriptManager1" runat="server" />
    <asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button1" runat="server" Text="Refresh Panel" OnClick="Button_Click" />    
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdatePanel ID="UpdatePanel2" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button2" runat="server" Text="Refresh Panel" OnClick="Button_Click"/>    
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdateProgress ID="UpdateProgress1" runat="server">
    <ProgressTemplate>
      Update in progress...
    </ProgressTemplate>
    </asp:UpdateProgress>
    </div>
    </form>
</body>
</html>

The following example shows two UpdateProgress controls. Each shows update status for an associated UpdatePanel control.

<%@ Page Language="VB" %>

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

<script runat="server">
    Protected Sub Button_Click(ByVal sender As Object, ByVal e As System.EventArgs)
        System.Threading.Thread.Sleep(3000)
    End Sub
</script>

<html xmlns="https://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>UpdateProgress Example</title>
    <style type="text/css">
    #UpdatePanel1, #UpdatePanel2 { 
      width:200px; height:200px; position: relative;
      float: left; margin-left: 10px; margin-top: 10px;
      border-right: gray 1px solid; border-top: gray 1px solid; 
      border-left: gray 1px solid; border-bottom: gray 1px solid;
     }
     #UpdateProgress1, #UpdateProgress2 {
      width: 200px; background-color: #FFC080;
      position: absolute; bottom: 0px; left: 0px;
     }
    </style>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <asp:ScriptManager ID="ScriptManager1" runat="server" />
    <asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button1" runat="server" Text="Refresh Panel" OnClick="Button_Click" />    
    <asp:UpdateProgress ID="UpdateProgress1" AssociatedUpdatePanelID="UpdatePanel1" runat="server">
    <ProgressTemplate>
      UpdatePanel1 updating...
    </ProgressTemplate>
    </asp:UpdateProgress>
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdatePanel ID="UpdatePanel2" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button2" runat="server" Text="Refresh Panel" OnClick="Button_Click"/>    
    <asp:UpdateProgress ID="UpdateProgress2" AssociatedUpdatePanelID="UpdatePanel2" runat="server">
    <ProgressTemplate>
      UpdatePanel2 updating...
    </ProgressTemplate>
    </asp:UpdateProgress>
    </ContentTemplate>
    </asp:UpdatePanel>
    </div>
    </form>
</body>
</html>

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

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

<script runat="server">
    protected void Button_Click(object sender, EventArgs e)
    {
        System.Threading.Thread.Sleep(3000);
    }
</script>

<html xmlns="https://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>UpdateProgress Example</title>
    <style type="text/css">
    #UpdatePanel1, #UpdatePanel2 { 
      width:200px; height:200px; position: relative;
      float: left; margin-left: 10px; margin-top: 10px;
      border-right: gray 1px solid; border-top: gray 1px solid; 
      border-left: gray 1px solid; border-bottom: gray 1px solid;
     }
     #UpdateProgress1, #UpdateProgress2 {
      width: 200px; background-color: #FFC080;
      position: absolute; bottom: 0px; left: 0px;
     }
    </style>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <asp:ScriptManager ID="ScriptManager1" runat="server" />
    <asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button1" runat="server" Text="Refresh Panel" OnClick="Button_Click" />    
    <asp:UpdateProgress ID="UpdateProgress1" AssociatedUpdatePanelID="UpdatePanel1" runat="server">
    <ProgressTemplate>
      UpdatePanel1 updating...
    </ProgressTemplate>
    </asp:UpdateProgress>
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdatePanel ID="UpdatePanel2" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button2" runat="server" Text="Refresh Panel" OnClick="Button_Click"/>    
    <asp:UpdateProgress ID="UpdateProgress2" AssociatedUpdatePanelID="UpdatePanel2" runat="server">
    <ProgressTemplate>
      UpdatePanel2 updating...
    </ProgressTemplate>
    </asp:UpdateProgress>
    </ContentTemplate>
    </asp:UpdatePanel>
    </div>
    </form>
</body>
</html>

The following example shows how to add a button to the <ProgressTemplate> element that the user can click to stop the asynchronous postback. Any new postbacks that are initiated while another postback is executing are canceled.

<%@ Page Language="VB" %>

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

<script runat="server">
    Protected Sub Button_Click(ByVal sender As Object, ByVal e As System.EventArgs)
        System.Threading.Thread.Sleep(3000)
    End Sub
</script>

<html xmlns="https://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>UpdateProgress Example</title>
    <style type="text/css">
    #UpdatePanel1, #UpdatePanel2, #UpdateProgress1 {
      border-right: gray 1px solid; border-top: gray 1px solid; 
      border-left: gray 1px solid; border-bottom: gray 1px solid;    
    }
    #UpdatePanel1, #UpdatePanel2 { 
      width:200px; height:200px; position: relative;
      float: left; margin-left: 10px; margin-top: 10px;
     }
     #UpdateProgress1 {
      width: 400px; background-color: #FFC080; 
      bottom: 0%; left: 0px; position: absolute;
     }
    </style>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <asp:ScriptManager ID="ScriptManager1" runat="server" />
    <script type="text/javascript">
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    prm.add_initializeRequest(InitializeRequest);
    prm.add_endRequest(EndRequest);
    var postBackElement;
    function InitializeRequest(sender, args) {
       if (prm.get_isInAsyncPostBack())
       {
          args.set_cancel(true);
       }
       postBackElement = args.get_postBackElement();
       if (postBackElement.id == 'ButtonTrigger')
       {
         $get('UpdateProgress1').style.display = "block";
       }
    }
    function EndRequest (sender, args) {
       if (postBackElement.id == 'ButtonTrigger')
       {
         $get('UpdateProgress1').style.display = "none";    
       }
    }
    function AbortPostBack() {
      if (prm.get_isInAsyncPostBack()) {
           prm.abortPostBack();
      }        
    }
    </script>
    <asp:Button ID="ButtonTrigger" runat="server" Text="Refresh Panel 1" OnClick="Button_Click" />    
    <asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    The trigger for this panel 
    causes the UpdateProgress to be displayed
    even though the UpdateProgress is associated
    with panel 2.     
    <br />
    </ContentTemplate>
    <Triggers>
      <asp:AsyncPostBackTrigger ControlID="ButtonTrigger" />
    </Triggers>
    </asp:UpdatePanel>
    <asp:UpdatePanel ID="UpdatePanel2" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button2" runat="server" Text="Refresh Panel" OnClick="Button_Click"/>    
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdateProgress ID="UpdateProgress1" runat="server" AssociatedUpdatePanelID="UpdatePanel2" >
    <ProgressTemplate>
      Update in progress...
      <input type="button" value="stop" onclick="AbortPostBack()" />
    </ProgressTemplate>
    </asp:UpdateProgress>
    </div>
    </form>
</body>
</html>

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

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

<script runat="server">
    protected void Button_Click(object sender, EventArgs e)
    {
        System.Threading.Thread.Sleep(3000);
    }
</script>

<html xmlns="https://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>UpdateProgress Example</title>
    <style type="text/css">
    #UpdatePanel1, #UpdatePanel2, #UpdateProgress1 {
      border-right: gray 1px solid; border-top: gray 1px solid; 
      border-left: gray 1px solid; border-bottom: gray 1px solid;    
    }
    #UpdatePanel1, #UpdatePanel2 { 
      width:200px; height:200px; position: relative;
      float: left; margin-left: 10px; margin-top: 10px;
     }
     #UpdateProgress1 {
      width: 400px; background-color: #FFC080; 
      bottom: 0%; left: 0px; position: absolute;
     }
    </style>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <asp:ScriptManager ID="ScriptManager1" runat="server" />
    <script type="text/javascript">
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    prm.add_initializeRequest(InitializeRequest);
    prm.add_endRequest(EndRequest);
    var postBackElement;
    function InitializeRequest(sender, args) {
       if (prm.get_isInAsyncPostBack())
       {
          args.set_cancel(true);
       }
       postBackElement = args.get_postBackElement();
       if (postBackElement.id == 'ButtonTrigger')
       {
         $get('UpdateProgress1').style.display = "block";
       }
    }
    function EndRequest (sender, args) {
       if (postBackElement.id == 'ButtonTrigger')
       {
         $get('UpdateProgress1').style.display = "none";    
       }
    }
    function AbortPostBack() {
      if (prm.get_isInAsyncPostBack()) {
           prm.abortPostBack();
      }        
    }
    </script>
    <asp:Button ID="ButtonTrigger" runat="server" Text="Refresh Panel 1" OnClick="Button_Click" />    
    <asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    The trigger for this panel 
    causes the UpdateProgress to be displayed
    even though the UpdateProgress is associated
    with panel 2.     
    <br />
    </ContentTemplate>
    <Triggers>
      <asp:AsyncPostBackTrigger ControlID="ButtonTrigger" />
    </Triggers>
    </asp:UpdatePanel>
    <asp:UpdatePanel ID="UpdatePanel2" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
    <%=DateTime.Now.ToString() %> <br />
    <asp:Button ID="Button2" runat="server" Text="Refresh Panel" OnClick="Button_Click"/>    
    </ContentTemplate>
    </asp:UpdatePanel>
    <asp:UpdateProgress ID="UpdateProgress1" runat="server" AssociatedUpdatePanelID="UpdatePanel2" >
    <ProgressTemplate>
      Update in progress...
      <input type="button" value="stop" onclick="AbortPostBack()" />
    </ProgressTemplate>
    </asp:UpdateProgress>
    </div>
    </form>
</body>
</html>

In the previous example, the onClick attribute of an HtmlButton control in the <ProgressTemplate> element calls the JavaScript AbortPostBack function. For more information, see the abortPostBack method and the isInAsyncPostBack property of the PageRequestManager class.

Specifying Content Layout

When the DynamicLayout property is true, the UpdateProgress control initially occupies no space in the page display. Instead, the page dynamically changes to display the UpdateProgress control contents when needed. To support dynamic display, the control is rendered as a <div> element that has its display style property initially set to none.

When the DynamicLayout property is false, the UpdateProgress control occupies space in the page display, even if the control is not visible. In that case, the <div> element for the control has its display style property set to block and its visibility initially set to hidden.

Putting UpdateProgress Controls on the Page

You can put UpdateProgress controls inside or outside UpdatePanel controls. A UpdateProgress control is displayed whenever the UpdatePanel control it is associated with is updated as a result of an asynchronous postback. This is true even if the UpdateProgress control is inside another UpdatePanel control.

If an UpdatePanel control is inside another update panel, a postback that originates inside the child panel causes any UpdateProgress controls associated with the child panel to be displayed. It also displays any UpdateProgress controls associated with the parent panel. If a postback originates from an immediate child control of the parent panel, only the UpdateProgress controls associated with the parent panel are displayed. This follows the logic for how postbacks are triggered.

Specifying When UpdateProgress Controls Are Displayed

You can programmatically control when an UpdateProgress control is displayed by using the JavaScript beginRequest and endRequest events of the PageRequestManager class. In the beginRequest event handler, display the DOM element that represents the UpdateProgress control. In the endRequest event handler, hide the element.

You must provide client script to show and hide an UpdateProgress control in the following circumstances:

  • During a postback from a control that is registered as an asynchronous postback trigger for the update panel, but that the UpdateProgress control is not associated with.

  • During postbacks from controls that are registered programmatically as asynchronous postback controls by using the RegisterAsyncPostBackControl method of the ScriptManager control. In that case, the UpdateProgress control cannot determine automatically that an asynchronous postback has been triggered.

Code Examples

The following sections include code examples for creating and using [T:System.Web.UI.]UpdateProgress controls.

Tutorials

Class Reference

The following table lists the key classes for working with the [T:System.Web.UI.]UpdateProgress class.

Class

Description

UpdateProgress

Provides visual feedback in the browser when the content of UpdatePanel controls is updated.

UpdatePanel

Specifies parts of a Web page that can participate in partial-page updates.

ScriptManager

Manages partial-page rendering. The ScriptManager control registers script components to send to the browser and overrides page rendering so that only specified regions of the page are rendered.

PageRequestManager

Coordinates partial-page rendering in the browser. The PageRequestManager class asynchronously exchanges information with the server and exposes events and methods for custom client scripting.

Additional Topics

ASP.NET Page Life Cycle Overview

See Also

Tasks

Introduction to the UpdatePanel Control

Introduction to the UpdateProgress Control

Programming UpdateProgress Controls in Client Script

Concepts

UpdatePanel Control Overview