diff --git a/handbook/docs/jsonrpc.mdx b/handbook/docs/jsonrpc.mdx index 6bc47c8f2..049d421a3 100644 --- a/handbook/docs/jsonrpc.mdx +++ b/handbook/docs/jsonrpc.mdx @@ -4,6 +4,8 @@ title: 产品及架构介绍 --- import Tag from "@site/src/components/Tag.js"; +import CardLink from "@site/src/components/CardLink.js"; + ### 定义 @@ -14,7 +16,7 @@ import Tag from "@site/src/components/Tag.js"; JsonRpc是**通用**的Rpc规范,与**编程语言无关、操作系统无关**。详细说明请参阅[JsonRpc 2.0 官方文档](https://www.jsonrpc.org/specification),在TouchSocket中封装了**前后端**,使其使用更加方便、高效。 -目前支持Tcp、Http、Websocket三种协议调用。 +目前支持`Tcp`、`Http`、`WebSocket`三种协议调用。 ## 二、特点: @@ -29,7 +31,7 @@ JsonRpc是**通用**的Rpc规范,与**编程语言无关、操作系统无关* ## 三、定义服务 -在**服务器**端中新建一个类,继承于**RpcServer**类(或实现IRpcServer),然后在该类中写**公共方法**,并用**JsonRpc**属性标签标记。 +在**服务器**端中新建一个类,继承于`RpcServer`类(或实现`IRpcServer`),然后在该类中写**公共方法**,并用**JsonRpc**特性标签标记。 ```csharp showLineNumbers @@ -205,13 +207,13 @@ await service.StartAsync(); ## 五、通用调用 -因为JsonRpc是通用调用协议,所以只要**适配基础协议**,即可直接使用Json字符串调用。 +因为`JsonRpc`是通用调用协议,所以只要**适配基础协议**,即可直接使用`Json`字符串调用。 以下字符串只是示例,具体的method参数,应当遵循当前路由。 ### 5.1 Tcp协议直接调用 -在Tcp协议时,按照适配器,选择性的是否以\r\n结尾。 +在`Tcp`协议时,按照适配器,选择性的是否以`\r\n`结尾。 ```csharp showLineNumbers {"jsonrpc": "2.0", "method": "testjsonrpc", "params":["RRQM"], "id": 1} @@ -219,7 +221,7 @@ await service.StartAsync(); ### 5.2 Http协议直接调用 -在Http协议时,以`Url+Post`方式即可 +在`Http`协议时,以`Url+Post`方式即可 ```csharp showLineNumbers {"jsonrpc": "2.0", "method": "testjsonrpc", "params":["RRQM"], "id": 1} @@ -227,7 +229,7 @@ await service.StartAsync(); ### 5.3 Websocket协议直接调用 -在Websocket协议时,以`文本类型`,直接发送到服务器即可。 +在`Websocket`协议时,以`文本类型`,直接发送到服务器即可。 ```csharp showLineNumbers {"jsonrpc": "2.0", "method": "testjsonrpc", "params":["RRQM"], "id": 1} @@ -236,7 +238,7 @@ await service.StartAsync(); ## 六、客户端直接调用 -框架内部提供了JsonRpc的专属客户端,可以直接调用,也可以生成代理调用。下列将详细介绍。 +框架内部提供了`JsonRpc`的专属客户端,可以直接调用,也可以生成代理调用。下列将详细介绍。 ### 6.1 Tcp协议 @@ -287,7 +289,7 @@ a.AddRpcStore(store => }); ``` -然后把生成的.cs文件复制(或链接)到客户端项目。然后客户端直接使用同名`扩展方法`即可调用。 +然后把生成的`.cs`文件复制(或链接)到客户端项目。然后客户端直接使用同名`扩展方法`即可调用。 ```csharp showLineNumbers var sum3 = client.TestJsonRpc("RRQM"); @@ -295,7 +297,7 @@ var sum3 = client.TestJsonRpc("RRQM"); ### 6.5 使用DispatchProxy代理调用 -使用DispatchProxy代理调用,可以实现动态代理,详情请看[DispatchProxy代理生成](./rpcgenerateproxy.mdx) +使用`DispatchProxy`代理调用,可以实现动态代理,详情请看[DispatchProxy代理生成](./rpcgenerateproxy.mdx) 首先,需要声明一个基类,用于通讯基础。 @@ -332,7 +334,7 @@ internal class MyJsonRpcDispatchProxy : JsonRpcDispatchProxy :::tip 提示 -此处其他协议的JsonRpc也是完全支持的。 +此处其他协议的`JsonRpc`也是完全支持的。 ::: @@ -361,11 +363,15 @@ while (true) ## 七、反向Rpc(服务器主动调用客户端) -框架提供了反向Rpc,即服务器主动调用客户端。该功可以用于web等多端。具体使用如下: +框架提供了反向`Rpc`,即**服务器主动调用客户端**。该功可以用于`Web`等多端。 -首先需要像常规Rpc一样声明一个Rpc服务。然后需要使用`JsonRpc`特性表示。 +反向Rpc必须在全双工协议下使用,如`WebSocket`、`Tcp`等。 -```csharp showLineNumbers +具体使用如下: + +首先,需要在*客户端*像常规`Rpc`一样声明一个`Rpc`服务。然后需要使用`JsonRpc`特性表示。 + +```csharp {3} showLineNumbers public partial class ReverseJsonRpcServer : RpcServer { [JsonRpc(MethodInvoke = true)] @@ -376,39 +382,38 @@ public partial class ReverseJsonRpcServer : RpcServer } ``` -然后在插件注册全局`RpcStore`。并注册服务。 +然后注册服务。 -```csharp showLineNumbers -var client = new WebSocketJsonRpcClient(); -await client.SetupAsync(new TouchSocketConfig() - .ConfigurePlugins(a => - { - a.UseGlobalRpcStore() - .ConfigureRpcStore(store => - { - store.RegisterServer(); - }); - }) - .SetRemoteIPHost("ws://127.0.0.1:7707/ws"));//此url就是能连接到websocket的路径。 -await client.ConnectAsync(); +```csharp {5-8} showLineNumbers +var jsonRpcClient = new WebSocketJsonRpcClient(); +await jsonRpcClient.SetupAsync(new TouchSocketConfig() + .ConfigureContainer(a => + { + a.AddRpcStore(store => + { + store.RegisterServer(); + }); + }) + .SetRemoteIPHost("ws://127.0.0.1:7707/ws"));//此url就是能连接到websocket的路径。 +await jsonRpcClient.ConnectAsync(); ``` -在服务器端中,拿到IHttpSessionClient对象。然后调用GetJsonRpcActionClient扩展方法获取到jsonRpcClient。然后调用Invoke等。 +在服务器端中,拿到`IHttpSessionClient`对象。然后调用`GetJsonRpcActionClient`扩展方法获取到`IJsonRpcClient`。然后调用`Invoke`等。 -下列示例演示的是,当WebSocket连接上时,服务器主动调用客户端。 +下列示例演示的是,当`WebSocket`连接上时,服务器主动调用客户端。 -```csharp showLineNumbers -class MyPluginClass : PluginBase, IWebSocketHandshakedPlugin +```csharp {8,10} showLineNumbers +class MyPluginClass : PluginBase, IWebSocketHandshakedPlugin { public async Task OnWebSocketHandshaked(IHttpSessionClient client, HttpContextEventArgs e) { try { //获取JsonRpcActionClient,用于执行反向Rpc - var client = client.GetJsonRpcActionClient(); + var jsonRpcClient = client.GetJsonRpcActionClient(); - var result = await client.InvokeTAsync("Add", InvokeOption.WaitInvoke, 10, 20); - Console.WriteLine(result); + var result = await jsonRpcClient.InvokeTAsync("Add", InvokeOption.WaitInvoke, 10, 20); + Console.WriteLine($"反向调用成功,结果={result}"); } catch (Exception ex) { @@ -425,4 +430,6 @@ class MyPluginClass : PluginBase, IWebSocketHandshakedPlugin ::: -[本文示例Demo](https://gitee.com/RRQM_Home/TouchSocket/tree/master/examples/JsonRpc) \ No newline at end of file +## 八、本文示例Demo + +