Ext.Net 1.x_Ext.Net.DirectMethods

DirectMethod 提供了一种可以从客户端 JavaScript 代码调用服务器端 .NET 方法的功能。

用 [DirectMethod] 属性修饰服务器端的 public 或 public static 方法，会向客户端 JavaScript 代码公开服务器端方法。

注意：服务器端的方法必须是 public 或 public static。

DirectMethod 基础

下面代码演示 DirectMethod 一个简单的例子，更新<ext:Label> 控件。

<script runat="server">
[DirectMethod]
public void SetTimeStamp()
{
this.Label1.Text = DateTime.Now.ToLongTimeString();
this.Label1.Element.Highlight();
}
</script>

<ext:Button ID="Button1" runat="server" Text="Click Me" Icon="Lightning">
<Listeners>
<Click Handler="Ext.net.DirectMethods.SetTimeStamp();" />
</Listeners>
</ext:Button>
<br />
<ext:Label ID="Label1" runat="server" Format="Server Time: {0}" Text='<%# DateTime.Now.ToLongTimeString() %>' />

.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }

说明

1，在 Button1 客户端事件里，调用服务器端方法 SetTimeStamp 来更新 Label1 控件，并高亮显示。

2，另外，在 Ext.Net，当第一次请求页面时（此时为回发），IsAjaxRequest 为 false，之后为 true，因为之后的请求是 Ajax 请求。

从 DirectMethod 返回一个字符串

DirectMethod 会返回任何类型的对象。这个对象被序列化成 JSON。被系列化的这个对象作为 result 参数发送给在 DirectMethod 中配置的回调函数 success。

<script runat="server">
[DirectMethod]
public string GetTimeStamp()
{
return DateTime.Now.ToLongTimeString();
}
</script>

<ext:Button runat="server" Text="Click Me" Icon="Lightning">
<Listeners>
<Click Handler="
Ext.net.DirectMethods.GetTimeStamp({
success: function (result) {
Ext.Msg.alert('Server Time', result);
}
});" />
</Listeners>
</ext:Button>

.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }

说明

在 Button1 客户端事件中，Ext.net.DirectMethods.GetTimeStamp(…) 是在客户端调用服务器端的方法 GetTimeStamp，success 是 Ext.net.DirectMethods 配置的回调函数，也就是说，当服务器端方法成功返回时，客户端需要根据返回的值执行的操作。在本例中，如果服务器端方法 GetTimeStamp() 成功返回服务器端当前时间，则客户端弹出这个时间警告。

给 DirectMethod 传递多个参数

如果服务器端 [DirectMethod] 方法要求参数，那么也要客户端 DirectMethod 传递两个参数给它。

本例中，如果服务器端要求两个参数：sting 和 int，那么在客户端也要传递两个可靠的参数给服务器端的 [DirectMethod] 方法。

<script runat="server">
[DirectMethod]
public void LogCompanyInfo(string name, int count)
{
string template = string.Concat("{0} has approximately {1} employees.");
string[] employees = new string[4] { "1-5", "6-25", "26-100", "100+" };

this.Label3.Text = string.Format(template, name, employees[count]);
}
</script>

<ext:Button runat="server" Text="Submit">
<Listeners>
<Click Handler="Ext.net.DirectMethods.LogCompanyInfo('Ext.NET, Inc.', 0);" />
</Listeners>
</ext:Button>

.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }

调用 DirectMethod 静态方法，并返回一个字符串（Super Fast + Best Performance）

当调用一个 public 服务端方法，默认情况下，在执行整个页面生命期时，这个方法可以访问页面上所有 Web 控件。

而带 static 的 [DirectMethod] 方法，不会执行页面生存期，并且不能访问页面 Web 控件。这减少了处理开销，优化了性能。

<script runat="server">
[DirectMethod]
public static string GetTimeStamp4()
{
return DateTime.Now.ToLongTimeString();
}
</script>

<ext:Button xrunat="server" Text="Click Me" Icon="Lightning">
<Listeners>
<Click Handler="
Ext.net.DirectMethods.GetTimeStamp4({
success: function (result) {
Ext.Msg.alert('Server Time', result);
}
});" />
</Listeners>
</ext:Button>

.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }

说明

Button1 客户端事件调用服务器端静态方法 GetTimeStamp()，获得服务器端当前时间。

注意：服务器端静态方法 GetTimeStamp() 中不能访问页面中的 Web 控件。

从静态 DirectMethod 返回一个自定义对象

DirectMethod 可以返回任何类型的对象。下面例子创建并返回一个 Customer 对象。

Customer 对象被序列化成 JSON，返回给客户端。在 DirectMethod 配置中，result 参数就是从服务器端返回的 Customer 对象。

<script runat="server">
// Define Customer Class
public class Customer
{
public int ID { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public string Company { get; set; }
public Country Country { get; set; }
public bool Premium { get; set; }
}

// Define Country Class
public class Country
{
public string Name { get; set; }
}

[DirectMethod]
public static Customer GetCustomer()
{
// Get your Customer data from somewhere...

return new Customer() {
ID = 99,
FirstName = "Peter",
LastName = "Smith",
Company = "CompanyX, LLC.",
Premium = true,
Country = new Country { Name = "Canada" }
};
}
</script>

<ext:Button runat="server" Text="Click Me" Icon="Lightning">
<Listeners>
<Click Handler="
Ext.net.DirectMethods.GetCustomer({
success : function (customer) {
var template = 'ID : {0}{6} Name : {1} {2}{6} Company : {3}{6} Country : {4}{6} Premium Member : {5}',
msg = String.format(template,
customer.ID,
customer.FirstName,
customer.LastName,
customer.Company,
customer.Country.Name,
customer.Premium,
'<br /><br />');

Ext.Msg.alert('Customer', msg);
}
});" />
</Listeners>
</ext:Button>

.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }

说明

1， 定义两个类 Customer 和 Country，Country 聚合在 Customer；

2， 服务器端静态方法 GetCustomer() 创建 Customer 对象返回给客户端。

注意：客户端如何访问对象 Customer。

禁用 DirectMethod ClientProxy 的创建

当服务器端方法添加 [DirectMethod] 属性，默认情况下，将会在客户端的 Ext.net.DirectMethods 创建一个相同名字、接受相同参数的 JavaScript 函数。

例如，如果创建一个名为 GetTimeStamp 服务器端方法，那么在客户端，也会创建一个相应的 Ext.net.DirectMethods.GetTimeStamp 的 JavaScript 函数。

有种情况，当开发者创建了一个 [DirectMethod]，但是想隐藏相应的客户端 JavaScript 函数。此时，你可以在某个 [DirectMethod] 属性里设置它的 ClientProxy.Ignore 属性，从而忽略创建相应的客户端 JavaScript 函数。

如果 [DirectMethod] 设置为 ClientProxy.Ignore，将不会创建相应的客户端代理函数（client-side proxy function），但是 [DirectMethod] 仍然可以被调用。[DirectMethod] 代理函数是围绕底层 Ext.net.DirectMethod.request() 函数的封装。

通过配置 Ext.net.DirectMethod.request() 函数，即便没有客户端代理函数，任何服务器端 [DirectMethod] 都可以被直接调用。

request ( string methodName , [Object options] ) : void

Calls the server-side [DirectMethod] as specified in the methodName parameter.

Parameters:

methodName : String

The server-side Method name to call.

options : Object

(optional) An object containing configuration properties. This options object may contain any of the following properties, or options as defined in Ext.Ajax.request.

success : Function

The JavaScript function to invoke on successful response from the DirectMethod.

The "result" parameter is passed to the success function.

failure : Function

The JavaScript function to invoke if a failure response is returned from the DirectMethod.

The "errorMessage" parameter is passed to the success function.

specifier : String

The server-side Method access specifier, options inlcude ("public", "static").

The specifier of "public" is the default value and does not need to be explicitly set.

If the server-side Method is a static Method, the specifier options must be set to "static".

method : String

The type of http request to make, options include ("POST", "GET").

The method of "POST" is the default value.

url : String

A custom url to call the DirectMethod from. The DirectMethod does not need to be configured on the "Parent Page".

If no url is provided, the request options will use the <form>'s action attribute. If the action attribute is empty, the request options will use the window.location.href value. If the window.location.href value ends with a forward-slash ("/"), the IIS web server may not be able to process the "POST" request. Under this scenario, you must set the "method" options property to "GET".

control : String

The ID of the UserControl which contains the DirectMethod. An DirectMethod can be configured within a .ascx file and called from a Parent .aspx Page.

timeout : Number

The timeout in milliseconds to be used for requests. (defaults to 30000)

eventMask : Object

(optional) An EventMask options object. This options object may contain any of the following properties:

showMask : Boolean

true to show mask (defaults to false).

msg : String

The text to display in a centered loading message box (defaults to 'Working...').

msgCls : String

The CSS class to apply to the loading message element (defaults to "x-mask-loading")

target : String

The target element to apply the mask to, options include ("page", "customtarget").

If "customtarget", the customTarget configuration option should be set.

customTarget : String

The id of the target element, or a instance of the target element.

minDelay : Number

The minimum amount of time to display the mask (defaults to 0).

Setting the minDelay provides and minimum amount of time to display a message to the user before removing mask and executing success, failure and/or callback functions.

Returns:

void

.csharpcode,.csharpcode pre { font-size: small; color: black; font-family: consolas, "Courier New", courier, monospace; background-color: #ffffff }
.csharpcode pre { margin: 0em }
.csharpcode .rem { color: #008000 }
.csharpcode .kwrd { color: #0000ff }
.csharpcode .str { color: #006080 }
.csharpcode .op { color: #0000c0 }
.csharpcode .preproc { color: #cc6633 }
.csharpcode .asp { background-color: #ffff00 }
.csharpcode .html { color: #800000 }
.csharpcode .attr { color: #ff0000 }
.csharpcode .alt { background-color: #f4f4f4; width: 100%; margin: 0em }
.csharpcode .lnum { color: #606060 }

<script runat="server">
[DirectMethod(ClientProxy = ClientProxy.Ignore)]
public string GetTimeStamp6()
{
return DateTime.Now.ToLongTimeString();
}
</script>

<ext:Button runat="server" Text="Click Me" Icon="Lightning">
<Listeners>
<Click Handler="Ext.net.DirectMethod.request(
'GetTimeStamp3',
{
success: function (result) {
Ext.Msg.alert('Message', result);
}
});" />
</Listeners>
</ext:Button>

向代理函数传递 DirectMethod 配置

DirectMethod 配置对象可以被作为最后一个参数传递给任何 DirectMethod 代理函数。

<script runat="server">
[DirectMethod]
public string LogMessage(string msg)
{
// Log the message somewhere...
return msg;
}
</script>

<ext:Button ID="Button4" runat="server" Text="Click Me" Icon="Lightning">
<Listeners>
<Click Handler="Ext.net.DirectMethods.LogMessage('Hello World', {
success: function (result) {
Ext.Msg.alert('Message', result);
},
eventMask: {
showMask: true,
minDelay: 500
}
});" />
</Listeners>
</ext:Button>