mirror of
https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat.git
synced 2025-12-29 18:04:42 +08:00
docs: 完善文档
This commit is contained in:
Fu Diwei
19
docs/WechatWork/Advanced_EventDataDeserialization.md
Normal file
19
docs/WechatWork/Advanced_EventDataDeserialization.md
Normal file
@@ -0,0 +1,19 @@
|
||||
### 如何解析回调通知事件？
|
||||
|
||||
---
|
||||
|
||||
你可根据官方文档的规则利用本库提供的 `WxBizMsgCryptor` 工具类自行解密回调通知事件的敏感信息。
|
||||
|
||||
对于解密后得到的原始数据，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例：
|
||||
|
||||
```csharp
|
||||
/* 如果是 JSON 格式的通知内容 */
|
||||
string callbackJson = "{ ... }";
|
||||
var callbackModel = client.DeserializeEventFromJson<Events.AddScheduleEvent>(callbackJson);
|
||||
|
||||
/* 如果是 XML 格式的通知内容 */
|
||||
string callbackXml = "<xml> ... </xml>";
|
||||
var callbackModel = client.DeserializeEventFromXml<Events.TextMessageEvent>(callbackXml);
|
||||
```
|
||||
|
||||
完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Work/Events_ 目录。
|
||||
68
docs/WechatWork/Advanced_IHttpClientFactory.md
Normal file
68
docs/WechatWork/Advanced_IHttpClientFactory.md
Normal file
@@ -0,0 +1,68 @@
|
||||
### 如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？
|
||||
|
||||
---
|
||||
|
||||
> 请参阅：
|
||||
>
|
||||
> [《Microsoft Docs - 使用 IHttpClientFactory 实现复原 HTTP 请求》](https://docs.microsoft.com/zh-cn/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests)
|
||||
>
|
||||
> [《Microsoft Docs - 在 ASP.NET Core 中使用 IHttpClientFactory 发出 HTTP 请求》](https://docs.microsoft.com/zh-cn/aspnet/core/fundamentals/http-requests#httpclient-and-lifetime-management)
|
||||
>
|
||||
> [《Microsoft Docs - .NET Core 2.1 的新增功能：套接字改进》](https://docs.microsoft.com/zh-CN/dotnet/core/whats-new/dotnet-core-2-1#sockets-improvements)
|
||||
|
||||
当你的项目是运行在 ASP.NET Core 2.1 或更高版本的平台时，CLR 已经提供了全新的底层套接字实现，无需你手动干预 `HttpClient` 的生命周期。
|
||||
|
||||
如果你想手动管理 `HttpClient`，那么可以参考下面基于 DI/IoC 的代码实现：
|
||||
|
||||
```csharp
|
||||
using Flurl.Http;
|
||||
using Flurl.Http.Configuration;
|
||||
using Microsoft.Extensions.Options;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work.Models;
|
||||
|
||||
public class WechatApiClientFactory
|
||||
{
|
||||
internal class DelegatingFlurlClientFactory : IFlurlClientFactory
|
||||
{
|
||||
private readonly System.Net.Http.IHttpClientFactory _httpClientFactory;
|
||||
|
||||
public DelegatingFlurlClientFactory(System.Net.Http.IHttpClientFactory httpClientFactory)
|
||||
{
|
||||
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
|
||||
}
|
||||
|
||||
public Flurl.Http.IFlurlClient Get(Flurl.Url url)
|
||||
{
|
||||
return new FlurlClient(_httpClientFactory.CreateClient(url.ToUri()));
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
// Do Nothing
|
||||
}
|
||||
}
|
||||
|
||||
private readonly System.Net.Http.IHttpClientFactory _httpClientFactory;
|
||||
private readonly IOptions<WechatApiClientOptions> _wechatApiClientOptions;
|
||||
|
||||
public WechatApiClientFactory(
|
||||
System.Net.Http.IHttpClientFactory httpClientFactory,
|
||||
IOptions<WechatApiClientOptions> wechatApiClientOptions)
|
||||
{
|
||||
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
|
||||
_wechatApiClientOptions = wechatApiClientOptions ?? throw new ArgumentNullException(nameof(wechatApiClientOptions));
|
||||
|
||||
Flurl.Http.FlurlHttp.GlobalSettings.FlurlClientFactory = new DelegatingFlurlClientFactory(_httpClientFactory);
|
||||
}
|
||||
|
||||
public WechatApiClient CreateClient()
|
||||
{
|
||||
return new WechatApiClient(_wechatApiClientOptions.Value);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
需要强调的是，虽然 `WechatApiClient` 实现了 `System.IDisposable` 接口，但你不应该在 DI/IoC 中手动释放它，而是应该交给 IoC 容器自动管理它。
|
||||
|
||||
此外你应注意，`System.Net.Http.IHttpClientFactory` 与 `Flurl.Http.Configuration.IHttpClientFactory` 是两个不同的类型，[使用时请加以区分](https://flurl.dev/docs/configuration/#httpclientfactory)。
|
||||
22
docs/WechatWork/Advanced_JSSDK.md
Normal file
22
docs/WechatWork/Advanced_JSSDK.md
Normal file
@@ -0,0 +1,22 @@
|
||||
### 如何生成 JS-SDK 初始化时所需的参数及签名？
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [企业微信 API - 客户端 API：JS-SDK 使用权限签名算法》](https://open.work.weixin.qq.com/api/doc/90000/90136/90506)
|
||||
|
||||
你可根据官方文档的规则利用本库提供的 `SHA1Utility` 工具类自行进行签名生成。
|
||||
|
||||
此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例：
|
||||
|
||||
```csharp
|
||||
var request = new Models.CgibinGetJsapiTicketRequest()
|
||||
{
|
||||
AccessToken = "企业微信应用的 AccessToken"
|
||||
};
|
||||
var response = await client.ExecuteCgibinGetJsapiTicketAsync(request);
|
||||
var paramMap = client.GenerateParametersForJssdkConfigRequest(response.Ticket, "https://example.com");
|
||||
```
|
||||
|
||||
需要注意的是，企业微信 JS-SDK 存在两种初始化方式，生成签名时所需要的 Ticket 获取方式并不相同，请开发者根据需要自行选择。
|
||||
46
docs/WechatWork/Advanced_JsonSerializer.md
Normal file
46
docs/WechatWork/Advanced_JsonSerializer.md
Normal file
@@ -0,0 +1,46 @@
|
||||
### 如何指定 JSON 序列化器？
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [《Microsoft Docs - .NET 中的 JSON 序列化和反序列化（封送和拆收）》](https://docs.microsoft.com/zh-cn/dotnet/standard/serialization/system-text-json-overview)
|
||||
|
||||
默认情况下，本库使用 `System.Text.Json` 作为 JSON 序列化器。
|
||||
|
||||
如果你更习惯于 `Newtonsoft.Json`，那么你可以在构造得到 `WechatTenpayClient` 对象后：
|
||||
|
||||
```csharp
|
||||
client.Configure(settings =>
|
||||
{
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer();
|
||||
});
|
||||
```
|
||||
|
||||
此外，如果你希望调整一些序列化器的配置项，那么可以：
|
||||
|
||||
```csharp
|
||||
using System.Text.Json;
|
||||
using SKIT.FlurlHttpClient.Wechat;
|
||||
|
||||
client.Configure(settings =>
|
||||
{
|
||||
var jsonOptions = FlurlSystemTextJsonSerializer.GetDefaultSerializerOptions();
|
||||
jsonOptions.WriteIndented = true;
|
||||
settings.JsonSerializer = new FlurlSystemTextJsonSerializer(jsonOptions);
|
||||
});
|
||||
```
|
||||
|
||||
使用 `Newtonsoft.Json` 时也是同样的：
|
||||
|
||||
```csharp
|
||||
using Newtonsoft.Json;
|
||||
using SKIT.FlurlHttpClient.Wechat;
|
||||
|
||||
client.Configure(settings =>
|
||||
{
|
||||
var jsonSettings = FlurlNewtonsoftJsonSerializer.GetDefaultSerializerSettings();
|
||||
jsonSettings.Formatting = Formatting.Indented;
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer(jsonSettings);
|
||||
});
|
||||
```
|
||||
11
docs/WechatWork/Advanced_ModelDefinition.md
Normal file
11
docs/WechatWork/Advanced_ModelDefinition.md
Normal file
@@ -0,0 +1,11 @@
|
||||
### 如何快速找到需要调用的 API 模型类名 / 方法名？
|
||||
|
||||
---
|
||||
|
||||
本库提供的请求模型、响应模型和接口方法，三者均保持同名。
|
||||
|
||||
例如，发送应用消息的请求是 `CgibinMessageSendRequest`，响应是 `CgibinMessageSendResponse`，接口是 `ExecuteCgibinMessageSendAsync()`。知道其中一个，其余两个就可以快速地推断出了。
|
||||
|
||||
再有，每个对象的命名与官方文档的接口地址大体保持一致。例如刚刚提到的发送应用消息，它的接口地址是 `[POST] /cgi-bin/message/send`，将其中的反斜杠去掉、并以大驼峰命名法的方式调整它，就可以得到前文提到的几个对象了。
|
||||
|
||||
完整的模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Work/Models_ 目录。
|
||||
144
docs/WechatWork/README.md
Normal file
144
docs/WechatWork/README.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# SKIT.FlurlHttpClient.Wechat.Work
|
||||
|
||||
[](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work)
|
||||
[](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work)
|
||||
[](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE)
|
||||
|
||||
基于 `Flurl.Http` 的企业微信 API 客户端。
|
||||
|
||||
---
|
||||
|
||||
## 功能
|
||||
|
||||
- 基于企业微信 API 封装。
|
||||
|
||||
- 支持企业内部开发、第三方应用开发（即服务商）两种模式。
|
||||
|
||||
- 提供了企业微信 API 所需的 SHA-1、AES 等算法工具类。
|
||||
|
||||
- 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。
|
||||
|
||||
- 完整企业微信 API 一览：
|
||||
|
||||
| | 微信 API | 开发模式 | 备注 |
|
||||
| :-: | :----------------------------: | :-------------: | :------------------------------: |
|
||||
| √ | 基础功能 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：成员管理 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：部门管理 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：标签管理 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：异步批量接口 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：互联企业 | 企业 | |
|
||||
| √ | 通讯录管理：通讯录搜索 | 服务商 | |
|
||||
| √ | 通讯录管理：通讯录 ID 转译 | 服务商 | |
|
||||
| √ | 客户联系：企业服务人员管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户标签管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：在职继承 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：离职继承 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户群管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户朋友圈 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：消息推送 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：统计管理 | 企业 & 服务商 | |
|
||||
| √ | 身份验证：网页授权登录 | 企业 & 服务商 | |
|
||||
| √ | 身份验证：扫码授权登录 | 企业 & 服务商 | |
|
||||
| √ | 应用管理：获取或设置应用 | 企业 & 服务商 | |
|
||||
| √ | 应用管理：自定义菜单 | 企业 | |
|
||||
| √ | 应用管理：自定义工作台 | 企业 | |
|
||||
| √ | 消息推送：发送应用消息 | 企业 & 服务商 | |
|
||||
| √ | 消息推送：更新任务卡片消息状态 | 企业 & 服务商 | |
|
||||
| √ | 消息推送：发送消息到群聊会话 | 企业 | |
|
||||
| √ | 消息推送：互联企业消息推送 | 企业 | |
|
||||
| √ | 消息推送：家校消息推送 | 企业 | |
|
||||
| √ | 消息推送：查询应用消息发送统计 | 企业 & 服务商 | |
|
||||
| √ | 素材管理 | 企业 & 服务商 | |
|
||||
| √ | OA：打卡 | 企业 & 服务商 | |
|
||||
| √ | OA：审批 | 企业 & 服务商 | |
|
||||
| √ | OA：汇报 | 企业 & 服务商 | |
|
||||
| √ | OA：自建应用 | 企业 & 服务商 | |
|
||||
| √ | OA：会议室 | 企业 | |
|
||||
| √ | OA：紧急通知 | 企业 | |
|
||||
| √ | 效率工具：日程 | 企业 & 服务商 | |
|
||||
| √ | 效率工具：会议 | 企业 & 服务商 | |
|
||||
| √ | 效率工具：直播 | 企业 & 服务商 | |
|
||||
| √ | 效率工具：微盘 | 企业 | |
|
||||
| √ | 效率工具：公费电话 | 企业 | |
|
||||
| × | <del>企业支付：企业红包</del> | <del>企业</del> | 与其他协议不一致，需提供单独模块 |
|
||||
| × | <del>企业支付：员工付款</del> | <del>企业</del> | 与其他协议不一致，需提供单独模块 |
|
||||
| √ | 企业支付：员工收款 | 企业 | |
|
||||
| √ | 企业支付：对外收款 | 企业 & 服务商 | |
|
||||
| √ | 企业互联 | 企业 & 服务商 | |
|
||||
| √ | 会话内容存档 | 企业 | |
|
||||
| √ | 电子发票 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：基础接口 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：网页授权登录 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：学生与家长管理 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：部门管理 | 企业 & 服务商 | |
|
||||
| √ | 家校应用：健康上报 | 企业 | |
|
||||
| √ | 家校应用：复学码 | 企业 | |
|
||||
| √ | 家校应用：上课直播 | 企业 & 服务商 | |
|
||||
| √ | 政民沟通：配置服务网格 | 企业 | |
|
||||
| √ | 政民沟通：配置事件类别 | 企业 | |
|
||||
| √ | 政民沟通：巡查上报 | 企业 | |
|
||||
| √ | 政民沟通：居民上报 | 企业 | |
|
||||
| √ | 应用授权 | 服务商 | |
|
||||
| √ | 推广二维码 | 服务商 | |
|
||||
|
||||
---
|
||||
|
||||
## 基础用法
|
||||
|
||||
### 安装：
|
||||
|
||||
提示：如果你使用 Visual Studio NuGet 管理器图形化界面，请在搜索结果中勾选“**包括预发行版**”。
|
||||
|
||||
```shell
|
||||
# 通过 NuGet 安装
|
||||
> Install-Package SKIT.FlurlHttpClient.Wechat.Work
|
||||
|
||||
# 通过 dotnet-tools 安装
|
||||
> dotnet add package SKIT.FlurlHttpClient.Wechat.Work
|
||||
```
|
||||
|
||||
### 初始化：
|
||||
|
||||
```csharp
|
||||
using SKIT.FlurlHttpClient.Wechat;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work;
|
||||
|
||||
var options = new WechatWorkClientOptions()
|
||||
{
|
||||
CorpId = "企业微信 CorpId",
|
||||
AgentId = "企业微信应用的 AgentId",
|
||||
AgentSecret = "企业微信应用的 AgentId"
|
||||
};
|
||||
var client = new WechatWorkClient(options);
|
||||
```
|
||||
|
||||
### 请求 & 响应：
|
||||
|
||||
```csharp
|
||||
using SKIT.FlurlHttpClient.Wechat.Work;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work.Models;
|
||||
|
||||
/* 示例：获取用户信息 */
|
||||
var request = new CgibinUserGetRequest()
|
||||
{
|
||||
AccessToken = "企业微信应用的 AccessToken",
|
||||
UserId = "企业成员账号"
|
||||
};
|
||||
var response = await client.ExecuteCgibinUserGetAsync(request);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 高级技巧
|
||||
|
||||
- [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md)
|
||||
|
||||
- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md)
|
||||
|
||||
- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)
|
||||
|
||||
- [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md)
|
||||
|
||||
- [如何生成 JS-SDK 初始化时所需的参数及签名？](./Advanced_JSSDK.md)
|
||||
Reference in New Issue
Block a user