Exposing Web Services to Client Script
The AJAX functionality of ASP.NET enables you to call ASP.NET Web services (.asmx files) from the browser by using client script. This enhances the user experience for the Web application. The page can call server-based methods without a postback and without refreshing the whole page, because only data is transferred between the browser and the Web server.
This topic describes how to make a Web service available to JavaScript running in the browser.
ASP.NET automatically creates JavaScript proxy classes for Web services. Proxy classes are derived from the Sys.Net.WebServiceProxy class. You can call a Web service method by calling the corresponding method of the JavaScript proxy class. For more information, see Calling Web Services from Client Script.
Making Web Services Accessible from Script
In order for a Web service to be accessed from script, it must be an .asmx Web service whose Web service class is qualified with the ScriptServiceAttribute attribute. Individual methods to be called from script must be qualified with the WebMethodAttribute attribute.
The following example shows these attributes in Web service code.
[ScriptService]
public class SimpleWebService : System.Web.Services.WebService
{
[WebMethod]
public string EchoInput(String input)
{
// Method code goes here.
}
}
<ScriptService> _
Public Class SimpleWebService
Inherits System.Web.Services.WebService
<WebMethod> _
Public Function EchoInput(ByVal input As String) As String
' Method code goes here.
End Function
End Class
To enable Web service calls from script, you must register the ScriptHandlerFactory HTTP handler in the application's Web.config file. The handler processes calls made from script to .asmx Web services. The following example shows the Web.config element for adding the handler.
Note
These configuration settings are already part of the Web.config file template for any new AJAX-enabled Web sites that you create in Microsoft Visual Studio 2005.
<system.web>
<httpHandlers>
<remove verb="*" path="*.asmx"/>
<add verb="*" path="*.asmx"
type="System.Web.Script.Services.ScriptHandlerFactory"
validate="false"/>
</httpHandlers>
<system.web>
For Web service calls that are not issued from ASP.NET AJAX script, the ScriptHandlerFactory handler delegates the call to the default handler, which uses SOAP instead of JSON format. The delegation is performed automatically and you do not have to take any action unless you want to disable the use of the SOAP protocol for the Web services. In that case, you must enter the following configuration setting in the Web.config file.
<system.web>
<webServices>
<protocols>
<clear/>
</protocols>
</webServices>
</system.web>
Exposing Web Services to Client Script in an ASP.NET Web Page
To enable an .asmx Web service to be called from client script in an ASP.NET Web page, you must add a ScriptManager control to the page. You reference the Web service by adding an asp:ServiceReference child element to the ScriptManager control and then setting the server reference path attribute to the URL of the Web service. The ServiceReference object instructs ASP.NET to generate a JavaScript proxy class for calling the specified Web service from client script.
The following example shows how to enable a Web service named SimpleWebService.asmx to be called from script in an ASP.NET Web page.
<asp:ScriptManager runat="server" ID="scriptManager">
<Services>
<asp:ServiceReference
path="~/WebServices/SimpleWebService.asmx" />
</Services>
</asp:ScriptManager>
The ServiceReference object can reference a Web service only in the same domain as the page. The Web service path can be relative, application relative, domain relative, or absolute. For absolute paths, you must make sure that the path is in the same domain.
When a page that contains this ScriptManager control is rendered, the page creates a JavaScript proxy class for the SimpleWebService.asmx Web service. The proxy class has methods that correspond to the Web methods in the SimpleWebService.asmx service. The page also contains JavaScript proxy classes that correspond to server data types that are used as input parameters or return values for the Web service methods. This enables you to write client script that initializes these parameters, and to pass them to the method call.
The InlineScript property of the ServiceReference object specifies how the JavaScript proxy class is included in the page. If InlineScript is set to false (the default), the proxy script is obtained by making a separate request. This option is better when multiple pages reference the same service and when browser caching is enabled.
If InlineScript is set to true, the proxy class script is included as an inline script block in the page. This can improve performance by reducing the number of network requests. This is especially true if there are many service references in the page and other pages do not reference the same service. If InlineScript is set to true, you must use a relative path. If the path is domain-relative, it must refer to the same Web application.
The following examples show a simple Web service that is called from script that displays the user's input and returns the current server time. The following example shows the page that makes service calls through client script.
<%@ Page Language="VB" %>
<!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 id="Head1" runat="server">
<style type="text/css">
body { font: 11pt Trebuchet MS;
font-color: #000000;
padding-top: 72px;
text-align: center }
.text { font: 8pt Trebuchet MS }
</style>
<title>Simple Web Service</title>
<script type="text/javascript">
// This function calls the Web Service method.
function EchoUserInput()
{
var echoElem = document.getElementById("EnteredValue");
Samples.AspNet.SimpleWebService.EchoInput(echoElem.value,
SucceededCallback);
}
// This is the callback function that
// processes the Web Service return value.
function SucceededCallback(result)
{
var RsltElem = document.getElementById("Results");
RsltElem.innerHTML = result;
}
</script>
</head>
<body>
<form id="Form1" runat="server">
<asp:ScriptManager runat="server" ID="scriptManager">
<Services>
<asp:ServiceReference path="SimpleWebService_VB.asmx" />
</Services>
</asp:ScriptManager>
<div>
<h2>Simple Web Service</h2>
<p>Calling a simple service that echoes the user's input and
returns the current server time.</p>
<input id="EnteredValue" type="text" />
<input id="EchoButton" type="button"
value="Echo" onclick="EchoUserInput()" />
</div>
</form>
<hr/>
<div>
<span id="Results"></span>
</div>
</body>
</html>
<%@ Page Language="C#" %>
<!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 id="Head1" runat="server">
<style type="text/css">
body { font: 11pt Trebuchet MS;
font-color: #000000;
padding-top: 72px;
text-align: center }
.text { font: 8pt Trebuchet MS }
</style>
<title>Simple Web Service</title>
<script type="text/javascript">
// This function calls the Web Service method.
function EchoUserInput()
{
var echoElem = document.getElementById("EnteredValue");
Samples.AspNet.SimpleWebService.EchoInput(echoElem.value,
SucceededCallback);
}
// This is the callback function that
// processes the Web Service return value.
function SucceededCallback(result)
{
var RsltElem = document.getElementById("Results");
RsltElem.innerHTML = result;
}
</script>
</head>
<body>
<form id="Form1" runat="server">
<asp:ScriptManager runat="server" ID="scriptManager">
<Services>
<asp:ServiceReference path="SimpleWebService.asmx" />
</Services>
</asp:ScriptManager>
<div>
<h2>Simple Web Service</h2>
<p>Calling a simple service that echoes the user's input and
returns the current server time.</p>
<input id="EnteredValue" type="text" />
<input id="EchoButton" type="button"
value="Echo" onclick="EchoUserInput()" />
</div>
</form>
<hr/>
<div>
<span id="Results"></span>
</div>
</body>
</html>
The following example shows the service that is called through the client script.
<%@ WebService Language="VB" Class="Samples.AspNet.SimpleWebService" %>
Imports System.Web
Imports System.Web.Services
Imports System.Xml
Imports System.Web.Services.Protocols
Imports System.Web.Script.Services
Namespace Samples.AspNet
<WebService(Namespace:="http://tempuri.org/")> _
<WebServiceBinding(ConformsTo:=WsiProfiles.BasicProfile1_1)> _
<ScriptService()> _
Public Class SimpleWebService
Inherits System.Web.Services.WebService
<WebMethod()> _
Public Function EchoInput(ByVal input As String) As String
Dim inputString As String = Server.HtmlEncode(input)
If Not String.IsNullOrEmpty(inputString) Then
Return String.Format("You entered {0}. The " + _
"current time is {1}.", inputString, DateTime.Now)
Else
Return "The input string was null or empty."
End If
End Function 'EchoInput
End Class 'SimpleWebService
End Namespace
<%@ WebService Language="C#" Class="Samples.AspNet.SimpleWebService" %>
using System;
using System.Web;
using System.Web.Services;
using System.Xml;
using System.Web.Services.Protocols;
using System.Web.Script.Services;
namespace Samples.AspNet
{
[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[ScriptService]
public class SimpleWebService : System.Web.Services.WebService
{
[WebMethod]
public string EchoInput(String input)
{
string inputString = Server.HtmlEncode(input);
if (!String.IsNullOrEmpty(inputString))
{
return String.Format("You entered {0}. The "
+ "current time is {1}.", inputString, DateTime.Now);
}
else
{
return "The input string was null or empty.";
}
}
}
}
Calling Static Methods in an ASP.NET Web Page
You can add static page methods to an ASP.NET page and qualify them as Web methods. You can then call these methods from script in that page as if they were part of a Web service, but without creating a separate .asmx file. To create Web methods in a page, import the System.Web.Services namespace and add a WebMethodAttribute attribute to each static method that you want to expose. The page methods must be defined in the page that is performing the page-method call.
To be able to call static page methods as Web methods, you must set the EnablePageMethods attribute of the ScriptManager control to true.
The following examples show how to call static page methods from client script to write and read session-state values. The following example shows page methods.
<%@ Page Language="VB" %>
<%@ Import Namespace="System.Web.Services" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
<WebMethod()> _
Public Shared Function GetSessionValue(ByVal key As String) As String
' Get session state value.
Return CStr(HttpContext.Current.Session(key))
End Function 'GetSessionValue
<WebMethod()> _
Public Shared Function SetSessionValue(ByVal key As String, _
ByVal value As String) As String
' Set session state value.
HttpContext.Current.Session(key) = value
Return CStr(HttpContext.Current.Session(key))
End Function 'SetSessionValue
</script>
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
<title>Using Page Methods with Session State</title>
<style type="text/css">
body { font: 11pt Trebuchet MS;
font-color: #000000;
padding-top: 72px;
text-align: center }
.text { font: 8pt Trebuchet MS }
</style>
</head>
<body>
<h2>Using Page Methods with Session State</h2>
<form id="form1" runat="server">
<asp:ScriptManager ID="ScriptManager1"
runat="server" EnablePageMethods="true">
<Scripts>
<asp:ScriptReference Path="PageMethod.js"/>
</Scripts>
</asp:ScriptManager>
</form>
<center>
<table>
<tr align="left">
<td>Write current date and time in session state:</td>
<td>
<input type="button"
onclick="SetSessionValue('SessionValue', Date())"
value="Write" />
</td>
</tr>
<tr align="left">
<td>Read current date and time from session state:</td>
<td>
<input type="button"
onclick="GetSessionValue('SessionValue')"
value="Read" />
</td>
</tr>
</table>
</center>
<hr/>
<span style="background-color:Aqua" id="ResultId"></span>
</body>
</html>
<%@ Page Language="C#" %>
<%@ Import Namespace="System.Web.Services" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
[WebMethod]
// Get session state value.
public static string GetSessionValue(string key)
{
return (string)HttpContext.Current.Session[key];
}
[WebMethod]
// Set session state value.
public static string SetSessionValue(string key, string value)
{
HttpContext.Current.Session[key] = value;
return (string)HttpContext.Current.Session[key];
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
<title>Using Page Methods with Session State</title>
<style type="text/css">
body { font: 11pt Trebuchet MS;
font-color: #000000;
padding-top: 72px;
text-align: center }
.text { font: 8pt Trebuchet MS }
</style>
</head>
<body>
<h2>Using Page Methods with Session State</h2>
<form id="form1" runat="server">
<asp:ScriptManager ID="ScriptManager1"
runat="server" EnablePageMethods="true">
<Scripts>
<asp:ScriptReference Path="PageMethod.js"/>
</Scripts>
</asp:ScriptManager>
</form>
<center>
<table>
<tr align="left">
<td>Write current date and time in session state:</td>
<td>
<input type="button"
onclick="SetSessionValue('SessionValue', Date())"
value="Write" />
</td>
</tr>
<tr align="left">
<td>Read current date and time from session state:</td>
<td>
<input type="button"
onclick="GetSessionValue('SessionValue')"
value="Read" />
</td>
</tr>
</table>
</center>
<hr/>
<span style="background-color:Aqua" id="ResultId"></span>
</body>
</html>
The following example shows script is used to make page methods calls.
// PageMethods.js
var displayElement;
// Initializes global variables and session state.
function pageLoad()
{
displayElement = $get("ResultId");
PageMethods.SetSessionValue("SessionValue", Date(),
OnSucceeded, OnFailed);
}
// Gets the session state value.
function GetSessionValue(key)
{
PageMethods.GetSessionValue(key,
OnSucceeded, OnFailed);
}
//Sets the session state value.
function SetSessionValue(key, value)
{
PageMethods.SetSessionValue(key, value,
OnSucceeded, OnFailed);
}
// Callback function invoked on successful
// completion of the page method.
function OnSucceeded(result, userContext, methodName)
{
if (methodName == "GetSessionValue")
{
displayElement.innerHTML = "Current session state value: " +
result;
}
}
// Callback function invoked on failure
// of the page method.
function OnFailed(error, userContext, methodName)
{
if(error !== null)
{
displayElement.innerHTML = "An error occurred: " +
error.get_message();
}
}
if (typeof(Sys) !== "undefined") Sys.Application.notifyScriptLoaded();
For more information about session state, see ASP.NET Session State Overview.
See Also
Tasks
Using the UpdatePanel Control with a Web Service
Concepts
Using Web Services in ASP.NET AJAX
Using Web Services in ASP.NET AJAX
Exposing WCF Services to Client Script
Calling Web Services from Client Script