Esta documentación está archivada y no tiene mantenimiento.

ScriptManager (Clase)

Actualización: noviembre 2007

Administra las bibliotecas de scripts y los archivos de script AJAX de ASP.NET, la representación parcial de página y la generación de la clase de proxy de cliente para los servicios web y de aplicación.

Espacio de nombres:  System.Web.UI
Ensamblado:  System.Web.Extensions (en System.Web.Extensions.dll)

[AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal)]
public class ScriptManager : Control, 
	IPostBackDataHandler, IScriptManager
/** @attribute AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal) */
/** @attribute AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal) */
public class ScriptManager extends Control implements IPostBackDataHandler, 
	IScriptManager
public class ScriptManager extends Control implements IPostBackDataHandler, IScriptManager
<asp:ScriptManager />

El control ScriptManager es fundamental para la funcionalidad de AJAX en ASP.NET. El control administra todos los recursos AJAX de ASP.NET en una página. Esto incluye la descarga de scripts de Microsoft AJAX Library en el explorador y la coordinación de las actualizaciones parciales de página que se habilitan mediante el uso de controles UpdatePanel. Además, el control ScriptManager permite hacer lo siguiente:

  • Registrar scripts compatibles con las actualizaciones parciales de página. Para administrar las dependencias entre su script y la biblioteca principal, cualquier script que registre se cargará después del script de Microsoft AJAX Library.

  • Especificar si se envían al explorador scripts de lanzamiento o de depuración.

  • Proporcionar acceso a métodos de servicio web desde el script mediante el registro de los servicios web con el control ScriptManager.

  • Proporcionar acceso a los servicios de autenticación, funciones y perfiles de ASP.NET desde el script de cliente mediante el registro de estos servicios con el control ScriptManager.

  • Habilitar la presentación específica de la referencia cultural en el explorador de las funciones ECMAScript (JavaScript) Date, Number y String.

  • Tener acceso a recursos de localización para los archivos de script incrustados o para los archivos de script independientes por medio de la propiedad ResourceUICultures del control ScriptReference.

  • Registrar controles de servidor que implementen la interfaz IExtenderControl o IScriptControl con el control ScriptManager para que se represente el script que requieren los comportamientos y componentes del cliente.

Representación parcial de página

Los factores siguientes controlan si una página ASP.NET tiene capacidad de admitir la representación parcial de página:

Puede invalidar el valor de la propiedad EnablePartialRendering en tiempo de ejecución durante el evento Init de la página o antes del mismo. Si intenta cambiar esta propiedad después de que se ha producido el evento Init de la página, se iniciará una excepción InvalidOperationException.

Cuando se admite la representación parcial de página, el control ScriptManager representa el script para habilitar las devoluciones de datos asincrónicas y las actualizaciones parciales de página. Las regiones de la página que se van a actualizar se designan mediante los controles UpdatePanel. El control ScriptManager administra las devoluciones de datos asincrónicas y actualiza sólo las regiones de la página que tienen que actualizarse. Para obtener más información acerca de la representación parcial de página, vea Información general sobre la representación parcial de páginas. Para obtener más información sobre las condiciones que provocan una actualización, vea Información general sobre el control UpdatePanel.

Utilizar el control ScriptManager con páginas maestras, controles de usuario y otros componentes secundarios

Una página sólo puede contener un control ScriptManager en su jerarquía. Para registrar servicios y scripts para páginas anidadas, controles de usuario o componentes cuando la página primaria ya tiene un control ScriptManager, utilice el control ScriptManagerProxy. Para obtener más información, vea Usar el control UpdatePanel de ASP.NET con páginas maestras

Información general acerca de la administración y el registro de scripts

El control ScriptManager permite registrar script que después se representa como parte de la página. Los métodos de registro del control ScriptManager se pueden clasificar en las tres categorías siguientes:

  • Métodos de registro que garantizan que se mantienen las dependencias de script en Microsoft AJAX Library.

  • Métodos de registro que no dependen de Microsoft AJAX Library pero son compatibles con controles UpdatePanel.

  • Métodos de registro que permiten trabajar con controles UpdatePanel.

Para obtener más información sobre cómo crear y usar script AJAX en ASP.NET, vea Crear script de cliente personalizado mediante el uso de Microsoft AJAX Library.

Registrar script que depende de Microsoft AJAX Library

Puede utilizar los métodos siguientes para registrar archivos de script de forma que se garantice que se mantiene cualquier dependencia de Microsoft AJAX Library.

Método

Definición

RegisterScriptControl<TScriptControl>

Registra un control de servidor que implementa la interfaz IScriptControl que se utiliza para definir un objeto de cliente Sys.Component. El control ScriptManager representa script que admite el objeto de cliente.

RegisterExtenderControl<TExtenderControl>

Registra un control de servidor que implementa la interfaz IExtenderControl que se utiliza para definir un objeto de cliente Sys.UI.Behavior. El control ScriptManager representa script que admite el objeto de cliente.

Registrar scripts compatibles con las actualizaciones parciales de página

Puede utilizar los métodos siguientes para registrar archivos de script que no dependen de Microsoft AJAX Library pero son compatibles con controles UpdatePanel. Estos métodos se corresponden con métodos similares del control ClientScriptManager. Si va a representar un script para usarlo dentro de un control UpdatePanel, asegúrese de que llama a los métodos del control ScriptManager.

Método

Definición

RegisterArrayDeclaration

Agrega un valor a una matriz JavaScript. Si la matriz no existe, se creará.

RegisterClientScriptBlock

Representa un elemento script después de la etiqueta de apertura <form> de la página. El script se especifica como un parámetro de cadena.

RegisterClientScriptInclude

Representa un elemento script después de la etiqueta de apertura <form> de la página. El contenido del script se especifica estableciendo el atributo src en una dirección URL que señala a un archivo de script.

RegisterClientScriptResource

Representa un elemento script después de la etiqueta de apertura <form> de la página. El contenido del script se especifica con un nombre de recurso en un ensamblado. El atributo src se rellena automáticamente con una dirección URL mediante una llamada a un controlador HTTP que recupera el script con nombre del ensamblado.

RegisterExpandoAttribute

Representa un par de nombre y valor como atributo personalizado (expando) en el marcado para un control especificado.

RegisterHiddenField

Representa un campo oculto.

RegisterOnSubmitStatement

Registra un script que se ejecuta en respuesta al evento submit del elemento form. El atributo onSubmit hace referencia al script especificado.

RegisterStartupScript

Representa un bloque de script de inicio justo delante de la etiqueta de cierre </form> de la página. El script que se va a representar se especifica como parámetro de cadena.

Al registrar los métodos, se especifica un par de tipo y clave para ese script. Si ya se ha registrado un script con el mismo par de tipo y clave, no se registra un nuevo script. De igual forma, si se registra un script con un par de tipo y nombre de recurso que ya existe, no se vuelve a agregar el elemento script que hace referencia al recurso. Al registrar un atributo expando de un atributo previamente registrado, se inicia una excepción. Se permite el registro duplicado de valores de matriz.

Al llamar al método RegisterClientScriptInclude o RegisterClientScriptResource, evite registrar script que ejecute funciones inline. En su lugar, registre script que contenga definiciones de función como controladores de eventos o definiciones de clase personalizadas para su aplicación.

Métodos de registro para los controles UpdatePanel

Puede utilizar los métodos siguientes para personalizar las actualizaciones parciales de página al utilizar controles UpdatePanel.

Método

Definición

RegisterAsyncPostBackControl

Registra un control como desencadenador de devoluciones de datos asincrónicas.

RegisterDataItem

Envía datos personalizados a los controles durante la representación parcial de la página.

RegisterDispose

Registra un script de eliminación para un control que está dentro de un control UpdatePanel. Se ejecuta el script cuando el control UpdatePanel se actualiza o elimina. El método de eliminación se utiliza para los componentes de cliente que forman parte de Microsoft AJAX Library y que tienen que liberar recursos cuando ya no se utiliza un componente.

RegisterPostBackControl

Registra un control como desencadenador de una devolución de datos completa. Este método se utiliza para los controles que están dentro de un control UpdatePanel que, de lo contrario, realizarían devoluciones de datos asincrónicas.

Referencias a servicios web

Puede registrar un servicio web que se va a llamar desde script de cliente creando un objeto ServiceReference y agregándolo a la colección Services del control ScriptManager. ASP.NET genera un objeto proxy de cliente para cada objeto ServiceReference de la colección Services. Puede agregar mediante programación objetos ServiceReference a la colección Services para registrar servicios web en tiempo de ejecución.

Para obtener más información sobre cómo tener acceso a los servicios web en script, vea Exponer servicios web a script de cliente y Llamar a servicios web desde script de cliente.

Localización

El control ScriptManager genera referencias en la página representada que señalan a los archivos de script localizados correspondientes, que son archivos de script incrustados en ensamblados o archivos de script independientes.

Cuando la propiedad EnableScriptLocalization se establece en true, el control ScriptManager recupera los recursos localizados (por ejemplo, cadenas localizadas) para la referencia cultural actual, si existen. El control ScriptManager proporciona la funcionalidad siguiente para utilizar recursos localizados:

  • Archivos de script incrustados en un ensamblado. El control ScriptManager determina qué archivo de script específico de la referencia cultural o de referencia cultural de reserva se enviará al explorador. Para ello, utiliza el atributo de ensamblado NeutralResourcesLanguageAttribute específico de la referencia cultural, los recursos empaquetados con el ensamblado y la referencia cultural de la interfaz de usuario del explorador (si lo hubiera).

  • Archivos de script independientes. El control ScriptManager define la lista de referencias culturales de interfaz de usuario que se admiten mediante la propiedad ResourceUICultures del objeto ScriptReference.

  • En modo de depuración. El control ScriptManager intenta representar un archivo de script específico de la referencia cultural que contiene información de depuración. Por ejemplo, si la página está en modo de depuración y la referencia cultural actual está definida como en-MX, el control representa un archivo de script que tendría un nombre parecido a scriptname.en-MX .debug .js, si el archivo existe. Si el archivo no existe, se representa el archivo de depuración de la referencia cultural de reserva correspondiente.

Para obtener más información sobre cómo localizar recursos, vea Información general sobre la localización de recursos para bibliotecas de componentes.

Control de errores

Cuando se produce un error de página durante las devoluciones de datos asincrónicas, se provoca el evento AsyncPostBackError. La forma en la que los errores del servidor se envían al cliente depende de la propiedad AllowCustomErrorsRedirect, la propiedad AsyncPostBackErrorMessage y la sección de errores personalizados (customErrors) del archivo Web.config. Para obtener más información, vea Personalizar el control de errores para los controles UpdatePanel de ASP.NET.

TopicLocation
Información general sobre el control UpdatePanelGenerar aplicaciones Web ASP .NET en Visual Studio
Información general sobre el control ScriptManagerGenerar aplicaciones Web ASP .NET en Visual Studio
Información general sobre el control UpdatePanelGenerar aplicaciones Web ASP .NET en Visual Studio
Información general sobre el control ScriptManagerGenerar aplicaciones Web ASP .NET en Visual Studio

En los ejemplos siguientes se muestran distintos escenarios de uso del control ScriptManager.

Habilitar actualizaciones parciales de página

En el ejemplo siguiente se muestra cómo utilizar el control ScriptManager para habilitar las actualizaciones parciales de página. En este ejemplo, los controles Calendar y DropDownList están dentro de un control UpdatePanel. De manera predeterminada, el valor de la propiedad UpdateMode es Always y el valor de la propiedad ChildrenAsTriggers es true. Por consiguiente, los controles secundarios del panel provocan una devolución de datos asincrónica.


<%@ 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">
    void DropDownSelection_Change(Object sender, EventArgs e)
    {
        Calendar1.DayStyle.BackColor =
            System.Drawing.Color.FromName(ColorList.SelectedItem.Value);
    }

    protected void Calendar1_SelectionChanged(object sender, EventArgs e)
    {
        SelectedDate.Text = 
            Calendar1.SelectedDate.ToString();
    }

</script>

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title>UpdatePanel Example</title>
</head>
<body>
    <form id="form1" runat="server">
        <div>
            <asp:ScriptManager ID="ScriptManager1" 
                               runat="server" />
            <asp:UpdatePanel ID="UpdatePanel1"
                             runat="server">
                <ContentTemplate>
                    <asp:Calendar ID="Calendar1" 
                                  ShowTitle="True"
                                  OnSelectionChanged="Calendar1_SelectionChanged"
                                  runat="server" />
                    <div>
                        Background:
                        <br />
                        <asp:DropDownList ID="ColorList" 
                                          AutoPostBack="True" 
                                          OnSelectedIndexChanged="DropDownSelection_Change"
                                          runat="server">
                            <asp:ListItem Selected="True" Value="White"> 
                            White </asp:ListItem>
                            <asp:ListItem Value="Silver"> 
                            Silver </asp:ListItem>
                            <asp:ListItem Value="DarkGray"> 
                            Dark Gray </asp:ListItem>
                            <asp:ListItem Value="Khaki"> 
                            Khaki </asp:ListItem>
                            <asp:ListItem Value="DarkKhaki"> D
                            ark Khaki </asp:ListItem>
                        </asp:DropDownList>
                    </div>
                    <br />
                    Selected date:
                    <asp:Label ID="SelectedDate" 
                               runat="server">None.</asp:Label>
                </ContentTemplate>
            </asp:UpdatePanel>
            <br />
        </div>
    </form>
</body>
</html>


Controlar los errores de actualización parcial de página y registrar el script

En el ejemplo siguiente se muestra cómo proporcionar el control de errores personalizado durante las actualizaciones parciales de página. De forma predeterminada, cuando se produce un error durante las actualizaciones parciales de página, se muestra un cuadro de mensaje de JavaScript. Este ejemplo muestra cómo utilizar el control de errores personalizado proporcionando un controlador para el evento AsyncPostBackError y estableciendo la propiedad AsyncPostBackErrorMessage en el controlador de eventos. También se puede establecer la propiedad AllowCustomErrorsRedirect para especificar cómo se utiliza la sección de errores personalizados (customErrors) del archivo Web.config cuando se produce un error durante las actualizaciones parciales de página. En este ejemplo, se usa el valor predeterminado de la propiedad AllowCustomErrorsRedirect. Esto significa que si el archivo Web.config contiene un elemento customErrors, ese elemento determina cómo se muestran los errores. Para obtener más información, vea Elemento customErrors (Esquema de configuración de ASP.NET).

<%@ 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 Button1_Click(object sender, EventArgs e)
    {
        try
        {
            int a = Int32.Parse(TextBox1.Text);
            int b = Int32.Parse(TextBox2.Text);
            int res = a / b;
            Label1.Text = res.ToString();
        }
        catch (Exception ex)
        {
            if (TextBox1.Text.Length > 0 && TextBox2.Text.Length > 0)
            {
                ex.Data["ExtraInfo"] = " You can't divide " +
                    TextBox1.Text + " by " + TextBox2.Text + ".";
            }
            throw ex;
        }
    }

    protected void ScriptManager1_AsyncPostBackError(object sender, AsyncPostBackErrorEventArgs e)
    {
        if (e.Exception.Data["ExtraInfo"] != null)
        {
            ScriptManager1.AsyncPostBackErrorMessage =
                e.Exception.Message +
                e.Exception.Data["ExtraInfo"].ToString();
        }
        else
        {
            ScriptManager1.AsyncPostBackErrorMessage =
                "An unspecified error occurred.";
        }
    }
</script>

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title>UpdatePanel Error Handling Example</title>
    <style type="text/css">
    #UpdatePanel1 {
      width: 200px; height: 50px;
      border: solid 1px gray;
    }
    #AlertDiv{
    left: 40%; top: 40%;
    position: absolute; width: 200px;
    padding: 12px; 
    border: #000000 1px solid;
    background-color: white; 
    text-align: left;
    visibility: hidden;
    z-index: 99;
    }
    #AlertButtons{
    position: absolute; right: 5%; bottom: 5%;
    }
    </style>
</head>
<body id="bodytag">
    <form id="form1" runat="server">
        <div>
            <asp:ScriptManager ID="ScriptManager1" 
            OnAsyncPostBackError="ScriptManager1_AsyncPostBackError" runat="server" >
            <Scripts>
            <asp:ScriptReference Path="ErrorHandling.js" />
            </Scripts>
            </asp:ScriptManager>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server">
                <ContentTemplate>
                    <asp:TextBox ID="TextBox1" runat="server" Width="39px"></asp:TextBox>
                    /
                    <asp:TextBox ID="TextBox2" runat="server" Width="39px"></asp:TextBox>
                    =
                    <asp:Label ID="Label1" runat="server"></asp:Label><br />
                    <asp:Button ID="Button1" runat="server" OnClick="Button1_Click" Text="calculate" />
                </ContentTemplate>
            </asp:UpdatePanel>
            <div id="AlertDiv">
                <div id="AlertMessage">
                </div>
                <br />
                <div id="AlertButtons">
                    <input id="OKButton" type="button" value="OK" runat="server" onclick="ClearErrorState()" />
                </div>
            </div>
        </div>
    </form>
</body>
</html>


Globalizar la fecha y hora que se muestran en el explorador

El ejemplo siguiente muestra cómo establecer la propiedad EnableScriptGlobalization para que el script de cliente pueda mostrar una fecha y hora específica de la referencia cultural en el explorador. En el ejemplo se establece el atributo Culture de la directiva @ Page en auto. Como resultado, el primer idioma que se especifica en la configuración actual del explorador determina la referencia cultural y la referencia cultural de la interfaz de usuario para la página. Para obtener más información, vea Cómo: Establecer la referencia cultural y la referencia cultural de la interfaz de usuario para la globalización de páginas Web ASP.NET.

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title>Globalization Example</title>
</head>
<body>
    <form id="form1" runat="server">
        <asp:ScriptManager ID="ScriptManager1" EnableScriptGlobalization="true" runat="server">
        </asp:ScriptManager>
        <script type="text/javascript">
        function pageLoad() {
          Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        }
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
        </script>
        <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" UpdateMode="Conditional">
        <ContentTemplate>
        <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
        <asp:Button ID="Button1" runat="server" Text="Display Date" />

        <br />

        <asp:Label ID="Label1" runat="server"></asp:Label>
        </asp:Panel>
        </ContentTemplate>
        </asp:UpdatePanel>
    </form>
</body>
</html>


System.Object
  System.Web.UI.Control
    System.Web.UI.ScriptManager

Todos los miembros static (Shared en Visual Basic) públicos de este tipo son seguros para la ejecución de subprocesos. No se garantiza que los miembros de instancias sean seguros para la ejecución de subprocesos.

Windows Vista, Windows XP SP2, Windows Server 2003

.NET Framework y .NET Compact Framework no admiten todas las versiones de cada plataforma. Para obtener una lista de las versiones compatibles, vea Requisitos de sistema de .NET Framework.

.NET Framework

Compatible con: 3.5
Mostrar: