You can add script blocks to an ASP.NET page just as you would for any HTML page. You can use client script to write event handlers for client events such as the page's onload event. When an ASP.NET page is running in the browser, the markup elements on the page are addressable in client script. They raise all the client events that they do in an HTML page.

Note:
You can reference ASP.NET server controls in client script. For more information, see Referencing Server Controls in Client Script later in this topic.

An ASP.NET Web page can also access a script file by referring to it in the src attribute of a <script> tag, as in the following example:

<script type="text/javascript" src="MyScript.js"></script>

Keeping client script in external .js files rather than in the pages themselves can help organize your client scripts. It can also make them easier to manage for version control and easier to share between pages.

External .js files are cached by the browser, similar to the way Web pages and images are cached. After the script has been loaded by the browser as an external file, it is available in the cache to any other Web page that requires it. This can help increase the performance of the Web application.

In many cases, you can create the client script for your page declaratively, usually as a script block. However, you can also create client script dynamically. This is useful if the script depends on information that is available only at run time. For example, you might insert client script into a page that addresses a server control whose name (ID) is not known until the application runs, or you might create script that depends on values that you get from a user.

You can create and insert client script dynamically into a rendered page by calling methods of the ClientScriptManager class, such as the following:

• RegisterClientScriptBlock, which inserts a script block at the top of the rendered page.

• RegisterStartupScript, which inserts a script block at the end of the rendered page.

The following example shows how to add dynamically generated client script to the page. The code checks whether a check box named checkDisplayCount is selected. If so, the code performs the following tasks:

• It creates a client script function that uses a span element to display the character count in a TextBox control named TextBox1.

• It adds a client event to the TextBox control.

• It generates the span element.

The code assumes that the page contains a check box named checkDisplayCount whose AutoPostBack property is set to true and a PlaceHolder control named PlaceHolder1.

Protected Sub Page_Load(ByVal sender As Object, _
        ByVal e As System.EventArgs)
    If checkDisplayCount.Checked Then
        Dim scriptText As String = ""
        scriptText &= "function DisplayCharCount(){"
        scriptText &= "   getElementByID("spanCounter").innerText = " & _
            "document.forms[0].TextBox1.value.length"
        scriptText &= "}"
        ClientScriptManager.RegisterClientScriptBlock(Me.GetType(), _
            "CounterScript", scriptText, True)
        TextBox1.Attributes.Add("onkeyup", "DisplayCharCount()")
        Dim spanLiteral As New LiteralControl()
        spanLiteral.Text = "<span id=""spanCounter""></span>"
        PlaceHolder1.Controls.Add(spanLiteral)
    End If
End Sub

void Page_Load(object sender, EventArgs e)
{
    if(checkDisplayCount.Checked)
    {
        String scriptText = "";
        scriptText += "function DisplayCharCount(){";
        scriptText += "   spanCounter.innerText = " + 
            " document.forms[0].TextBox1.value.length";
        scriptText += "}";
        ClientScriptManager.RegisterClientScriptBlock(this.GetType(), 
           "CounterScript", scriptText, true);
        TextBox1.Attributes.Add("onkeyup", "DisplayCharCount()");
        LiteralControl spanLiteral = new 
            LiteralControl("<span id=\"spanCounter\"></span>");
        PlaceHolder1.Controls.Add(spanLiteral);
    }
}

For more information, see How to: Add Client Script Dynamically to ASP.NET Web Pages.

For ClientScriptManager class methods, you provide a type that the script block is associated with and you give the script block a key. Providing a type helps avoid collisions if both a page and controls (custom controls or user controls) add script blocks into the same page. Using a key helps avoid duplication. If you call one of the methods to add script, and a script with the same key and the same type already exists, the script is not added again.

The type and key that you provide help avoid unnecessary duplication. Therefore, you generally do not have to determine explicitly whether a script block already exists. However, if it is useful in your application to check for an existing script block, you can call the following methods:

• IsClientScriptBlockRegistered

• IsClientScriptIncludeRegistered

• IsOnSubmitStatementRegistered

• IsStartupScriptRegistered

If you are using ASP.NET AJAX features, the ScriptManager control provides a way for you to add script files in a page. This includes static script files (.js files) on disk and script files that are embedded as resources in an assembly. You can specify script files declaratively in the control. Alternatively, you can use registration methods of the ScriptManager control that let you manage existing client script files programmatically and that let you work with scripts for partial-page update support.

For an overview of the ScriptManager control, see ScriptManager Control Overview. For information about how to embed a JavaScript file as a resource in an assembly and how to consume it in a Web page, see Walkthrough: Embedding a JavaScript File as a Resource in an Assembly.

Note:

If you are using client AJAX features of ASP.NET but not server-based features, use methods of the ClientScriptManager class to insert scripts in an ASP.NET Web page. For example, if you are not using the UpdatePanel control or localization features for scripts, you do not need the ScriptManager control. Therefore, you cannot call its methods to insert client script into the page. Using methods of the ClientScriptManager class is usually more efficient than using ScriptManager control methods. This is because ClientScriptManager class methods do not require the extra processing for server-based features that are supported by the ScriptManager control. If you must create script dynamically (instead of simply managing existing script), use the ClientScriptManager class to insert client script into a page. For example, use the ClientScriptManager class if you want to create client script programmatically based on information that a preexisting script file cannot reference.

A browser compatibility layer in the Microsoft AJAX Library provides AJAX scripting compatibility for the most frequently used browsers (including Microsoft Internet Explorer, Mozilla Firefox, and Apple Safari). This enables you to write the same script regardless of which supported browser you are targeting. For more information, see ASP.NET AJAX Overview.

In the markup for ASP.NET server controls, you set property values by using attributes. For example, to set the Text property of a TextBox control, you can create markup like the following:

<asp:textbox id="TextBox1" runat="server" text="Sample Text" />

Security Note:
A TextBox 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.

If you include an attribute that does not map to a property of the control, ASP.NET ignores the attribute during server processing. It passes it as-is as part of the markup that is generated by the control to the browser. For example, the TextBox control has no property named onkeyup. Therefore, if you include an onkeyup attribute in the markup for a TextBox control, the attribute is passed through to the browser. This behavior enables you to add event bindings to server controls by declaring them in the markup. For example, the following markup for a TextBox control causes the text box to display the current text length in a span element named spanCounter any time the user presses a key in the text box:

<asp:textbox id="TextBox1" runat="server" text="Sample Text" 
  onkeyup="spanCounter.innerText=this.value.length;" />

Alternatively, the event could call a method that is defined in client script elsewhere in the page:

<asp:textbox id="TextBox1" runat="server" text="Sample Text" 
  onkeyup="DisplayCount(this);" />

Note that the language that you use for server code (Visual Basic or C#) does not affect client script, which is always written in ECMAScript (JavaScript or JScript).

For more information, see How to: Add Client Script Events to ASP.NET Web Server Controls.

In addition to adding pass-through attributes to a control declaratively, you can add attributes programmatically by using server code. This is useful if the value of the attribute to add is known only at run time. For details, see How to: Set HTML Attributes for Controls in ASP.NET Web Pages.

Some controls render child controls into the page. This includes data list controls such as the ListView, GridView, DetailsView, FormView, DataList, and Repeater controls, user controls, and Web Parts controls.

In these cases, the child controls might not have unique IDs. This can be because the child controls are defined in a template that generates new control instances for every data row (data list controls). Or it might be because the parent control can be added to the page from an external source (user controls and Web Parts controls). These parent controls are therefore naming containers (they implement INamingContainer). A naming container guarantees that its child controls have unique IDs on the page.

For example, you might create an ItemTemplate property in the DataList control. In the template, you might add a CheckBox control whose ID you set to checkEnabled. When the DataList control is rendered, a new checkEnabled control is rendered for each data item. The rendered page must not contain multiple instances of an element named checkEnabled. Therefore, the DataList control creates a unique identity for each of its child controls.

Unique identities for child controls of a naming container are generated by rendering two properties. For each child control:

• The control's UniqueID property is rendered as the name attribute.

• The control's ClientID property is rendered as the id attribute.

Both the ClientID and UniqueID properties are based on the original ID property, amended with enough information to guarantee that the result is unique in the page. The value of ClientID (the id attribute in the rendered element) can be referenced in client script.

If you display a page that contains a naming container in the browser, you can view the page's source to see the unique IDs generated as the name and id attributes for the naming container's child controls. However, we recommend that you do not rely on directly referencing the IDs as you see them in the browser. The formula used to generate unique IDs for child controls can change. Instead, get the value of the child control's ClientID property in server code and use that value to reference the child control. For example, you might create client script dynamically in your page. If the client script references a child control, get the child control's ClientID property and build it into your dynamic script.

Client script can call server code directly by implementing a client callback. In a common sequence for ASP.NET Web pages, each user action that runs server code requires a postback. However, you can also invoke server processing from the browser without a full postback. In this scenario, the browser does not send the whole page to the server and then reload it when the server responds. Instead, the browser sends a small amount of data to the server. When the server sends a response, client script in the browser processes the returned data without reloading the page. During the server processing, all client state such as local variables is retained. This process is known as an asynchronous postback and is key to partial-page rendering.

You can call server methods from client script without a postback in these ways:

• Use the ASP.NET UpdatePanel server control. This control is part of the AJAX functionality of ASP.NET. It enables you to define a region of a page that will be refreshed with a partial-page update. When you use the UpdatePanel control, you do not have to write any client script yourself to invoke asynchronous partial-page updates. For more information, see Partial-Page Rendering Overview and UpdatePanel Control Overview.

• Use ASP.NET AJAX support for Web service communication to write client script that invokes a Web server method. This approach is conceptually similar to writing your own client script callback to call a Web server method. However, the Microsoft AJAX Library handles the details of invoking the server method and provides a more robust client-script library for making and processing the call. For more information, see Web Services in ASP.NET AJAX.

• Implement a client callback. In this scenario, you write the client code that sends the request and that processes the result. The most common approach is to create a calling function in client script and a callback function that is invoked when the server returns the results. For more information, see Implementing Client Callbacks Programmatically Without Postbacks in ASP.NET Web Pages

Each approach has advantages. Creating your own client callback often gives you the lowest overhead and smallest page size. Using the UpdatePanel server control lets you implement partial-page updates without writing any client script yourself. Using AJAX to call Web services also eliminates most of the client script you would write for making asynchronous Web service calls.

You can share information between client script and server code by adding a HiddenField control to the page. You can reference the hidden field in client script by its ID. You can also reference the hidden field in server code. This enables you to store values in either code block and read them in the other. To pass information from server code to client script, you can create a hidden field programmatically by using the RegisterHiddenField method. This method lets you specify an ID and value for the field. You can use the field to store dynamic values in the page in a way that client script can read them.

You can also share values between server code and client code by using cookies. For details about how to write and read cookies in server code, see How to: Write a Cookie and How to: Read a Cookie. For details about how to use JavaScript to read and write cookies, see JavaScript and cookies on the MSDN Web site.

If you are using AJAX features of ASP.NET, you can send custom data as a string from the server to the client during asynchronous postbacks (partial page rendering) by using the RegisterDataItem method. The RegisterDataItem method enables you to use server code to register a field that is attached to a control. You can access the field's value in client script in the browser through the ASP.NET AJAX Sys.WebForms.PageLoadingEventArgs, Sys.WebForms.PageLoadedEventArgs, and Sys.WebForms.PageLoadedEventArgs objects. The RegisterDataItem method can be called only during an asynchronous postback.

For information about how to use the RegisterDataItem method to share data between the server and the client, see the following topics:

• RegisterDataItem

• Working with PageRequestManager Events