Skip to content

Commit c36e9ec

Browse files
qideqianqideqian
committed
调整文件夹大小写2-新增
1 parent 8c91d47 commit c36e9ec

30 files changed

+1983
-0
lines changed

‎docs/zh/guide/mp/advanced-interface.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# 高级接口
2+
3+
完成 `Program.cs` 文件中的常规注册后，即可在程序的任意地方使用高级接口。
4+
5+
> 注意：
6+
> 1、高级接口的配置和 `MessageHandler` 没有关联，两者可以独立或配合使用。
7+
> 2、SDK 内几乎所有高级接口的第一个参数同时支持传入 AppId 或 AccessToken，通常名称为 `appIdOrAccessToken`，SDK 会根据参数特征自动识别输入的是 AppId 还是 AccessToken，并做区分处理。
8+
9+
## 使用 AppId 调用接口（推荐）
10+
11+
例如，我们可以在任意一个方法中调用一个高级接口：
12+
13+
```cs
14+
var appId = Senparc.Weixin.Config.SenparcWeixinSetting.AppId;
15+
var result = await Senparc.Weixin.MP.AdvancedAPIs.UserApi.GetAsync(appId);//获取关注者 OpenId 信息
16+
```
17+
18+
> appId 参数，必须是已经经过注册的，这样即使 AccessToken 过期，SDK 也会全自动处理。如果是未经过注册的 appId，则需要先获取 AccessToken，然后调用接口。
19+
20+
## 使用 AccessToken 调用接口（不推荐）
21+
22+
```cs
23+
var accessToken = Senparc.Weixin.MP.CommonApi.GetTokenAsync(appId, appSecret);//获取 AccessToken
24+
var result = await Senparc.Weixin.MP.AdvancedAPIs.UserApi.GetAsync(accessToken);//获取关注者 OpenId 信息
25+
```
26+
27+
> 注意：使用 AccessToken 方式调用接口，无法保证当前 AccessToken 的有效性，因此建议使用前进行有效性校验，并使用 `try-catch` 方式捕获 AccessToken 不可用的异常，然后进行重试。因此直接使用 AccessToken 调用接口的方式并不推荐在常规情况下使用。

‎docs/zh/guide/mp/advanced.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# 进阶
2+
3+
当前示例展示了最基本和常用的功能，如果您需要了解更多高级玩法，并且有扎实的编程功底，请参考完整示例。
4+
5+
> 完整示例解决方案文件：
6+
>
7+
> Senparc.Weixin SDK 源文件根目录[/Samples/All/net7-mvc/Senparc.Weixin.Sample.Net7.sln](https://github.com/JeffreySu/WeiXinMPSDK/tree/master/Samples/All/net7-mvc)
8+
9+
> 务必阅读 readme 文件：
10+
>
11+
> Senparc.Weixin SDK 源文件根目录[/Samples/All/net7-mvc/readme.md](https://github.com/JeffreySu/WeiXinMPSDK/blob/master/Samples/All/net7-mvc/readme.md)

‎docs/zh/guide/mp/install.md

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# 如何安装？
2+
3+
您可以直接引用 Senparc.Weixin 的源码进行开发，也可以引用已经打包完成的 dll（通过 Nuget 包，推荐），以方便随时获取官方的更新。注意：直接引用源码和引用 Nuget 包只能二选一。
4+
5+
## 引用源码
6+
7+
您可以在当前解决方案中，**Libraries** 目录下，将所需要引用的程序集引用（复制）到您开发环境的解决方案中，请注意需要同时引用被依赖的项目，如 `Senparc.Weixin` 项目是所有项目都需要依赖的。
8+
9+
当前示例项目默认就使用了直接引用源码的方式，可从 .csproj 文件中看到引用方式：
10+
11+
```cs
12+
<ItemGroup>
13+
<ProjectReference Include="..\..\..\src\Senparc.Weixin.MP.Middleware\Senparc.Weixin.MP.Middleware.net6.csproj" />
14+
<ProjectReference Include="..\..\..\src\Senparc.Weixin.MP.MvcExtension\Senparc.Weixin.MP.MvcExtension\Senparc.Weixin.MP.MvcExtension.net6.csproj" />
15+
<ProjectReference Include="..\..\..\src\Senparc.Weixin.MP\Senparc.Weixin.MP\Senparc.Weixin.MP.net6.csproj" />
16+
</ItemGroup>
17+
```
18+
19+
## 引用程序集（推荐）
20+
21+
您可以通过 `Visual Studio`、`Visual Studio Code`、`dotnet 命令行` 等多种方式自动安装 Nuget 包。
22+
23+
### Visual Studio
24+
25+
在开发项目【解决方案资源管理器】中，对需要添加 Senparc.Weixin.MP 的模块点击右键，点击【管理 Nuget 程序包】，在【浏览】标签中输入 **Senparc.Weixin.MP**，点击右侧【安装】按钮。如下图所示：
26+
27+
![通过 Visual Studio 安装](https://sdk.weixin.senparc.com/Docs/MP/images/home-install-01.png)
28+
29+
### Visual Studio Code
30+
31+
首先，确认已经安装好 [VS Code](https://code.visualstudio.com/) 以及 dotnet 命令行（安装 [.NET SDK](https://dotnet.microsoft.com/en-us/download) 后会自动安装）。
32+
33+
然后，打开解决方案或项目所在目录，按 Ctrl+~，打开终端面板：
34+
35+
![通过 VS Code 安装](https://sdk.weixin.senparc.com/Docs/MP/images/home-install-03.png)
36+
37+
进入需要添加 Senparc.Weixin.MP 的模块的项目的目录，输入：
38+
39+
> ```cs
40+
> dotnet add package Senparc.Weixin.MP
41+
> ```
42+
43+
安装 Senparc.Weixin.MP 模块
44+
45+
![通过 VS Code 安装](https://sdk.weixin.senparc.com/Docs/MP/images/home-install-04.png)
46+
47+
安装完成后，可查看对应 .csproj 文件，被添加引用，如：
48+
49+
```cs
50+
<ItemGroup>
51+
<PackageReference Include="Senparc.Weixin.MP" Version="16.17.7" />
52+
</ItemGroup>
53+
```
54+
55+
### dotnet 命令行
56+
57+
首先，确认已经安装好 dotnet 命令行（安装 [.NET SDK](https://dotnet.microsoft.com/en-us/download) 后会自动安装）。
58+
59+
进入需要添加 Senparc.Weixin.MP 的模块的项目的目录，输入：
60+
61+
> ```cs
62+
> dotnet add package Senparc.Weixin.MP
63+
> ```
64+
65+
![通过 dotnet CLI 安装](https://sdk.weixin.senparc.com/Docs/MP/images/home-install-02.png)
66+
67+
安装完成后，可查看对应 .csproj 文件，被添加引用，如：
68+
69+
```cs
70+
<ItemGroup>
71+
<PackageReference Include="Senparc.Weixin.MP" Version="16.17.7" />
72+
</ItemGroup>
73+
```

‎docs/zh/guide/mp/jssdk.md

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# JSSDK
2+
3+
JSSDK 用于提供微信内置浏览器接口的能力，例如转发控制、调用摄像头权限（拍照、视频）、文件上传、关闭窗口、唤起扫码窗口，等等。
4+
5+
要在内置浏览器中只用 JSSDK，分为“服务端获取签名信息”和“网页端配置 JSSDK”两步。
6+
7+
## 服务端获取签名信息
8+
9+
后端通过 `JSSDKHelper.GetJsSdkUiPackageAsync()` 方法即可自动获取前端所需的所有 JSSDK 运行所需参数：
10+
11+
```cs
12+
public async Task Index()
13+
{
14+
var jssdkUiPackage = await JSSDKHelper.GetJsSdkUiPackageAsync(appId, appSecret, Request.AbsoluteUri());
15+
return View(jssdkUiPackage);
16+
}
17+
```
18+
19+
> 本项目参考文件：
20+
>
21+
> /Controllers/**_WeixiJSSDKnController.cs_**
22+
23+
## 网页端配置 JSSDK
24+
25+
后端配置完成的参数，直接在前端 JS 中使用 `wx.config` 进行设置，例如以下代码将完成在转发网页时自定义转发消息的标题和图片：
26+
27+
```js
28+
wx.config({
29+
debug: false, // 开启调试模式
30+
appId: "@Model.AppId", // 必填，公众号的唯一标识
31+
timestamp: "@Model.Timestamp", // 必填，生成签名的时间戳
32+
nonceStr: "@Model.NonceStr", // 必填，生成签名的随机串
33+
signature: "@Model.Signature", // 必填，签名
34+
jsApiList: ["checkJsApi", "onMenuShareTimeline", "onMenuShareAppMessage"],
35+
});
36+
37+
wx.error(function (res) {
38+
console.log(res);
39+
alert("验证失败");
40+
});
41+
42+
wx.ready(function () {
43+
var url = "https://sdk.weixin.senparc.com";
44+
var link = url + "";
45+
var imgUrl = url + "/images/v2/ewm_01.png";
46+
47+
//转发到朋友圈
48+
wx.onMenuShareTimeline({
49+
title: "JSSDK朋友圈转发测试",
50+
link: link,
51+
imgUrl: imgUrl,
52+
success: function () {
53+
alert("转发成功！");
54+
},
55+
cancel: function () {
56+
alert("转发失败！");
57+
},
58+
});
59+
//转发给朋友
60+
wx.onMenuShareAppMessage({
61+
title: "JSSDK朋友圈转发测试",
62+
desc: "转发给朋友",
63+
link: link,
64+
imgUrl: imgUrl,
65+
type: "link",
66+
dataUrl: "",
67+
success: function () {
68+
alert("转发成功！");
69+
},
70+
cancel: function () {
71+
alert("转发失败！");
72+
},
73+
});
74+
});
75+
```
76+
77+
> 提示：在 MVC 中传递 ViewModel 需要在 .cshtml 文件顶部定义：
78+
>
79+
> ```cs
80+
> @model Senparc.Weixin.MP.Helpers.JsSdkUiPackage
81+
> ```
82+
83+
> 本项目参考文件：
84+
>
85+
> /Views/WeixinJSSDK/**_Index.cshtml_**
86+
87+
更多设置详情请参考：[JS-SDK 说明文档](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html)。

‎docs/zh/guide/mp/menu.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# 菜单设置
2+
3+
公众号菜单是公众号界面的重要元素，菜单的使用分为 **设置** 和 **使用** 两个环节。
4+
5+
## 设置
6+
7+
方法一：使用微信公众号后台界面设置（不使用开发模式），此处略。
8+
9+
方法二（推荐）：使用可视化编辑器（No Code）：[点击查看介绍](https://sdk.weixin.senparc.com/Menu)。
10+
11+
方法三：使用代码进行设置（只需要执行一次，建议放在管理员后台，手动运行），如：
12+
13+
```cs
14+
public async Task CreateMenuAsync()
15+
{
16+
ButtonGroup bg = new ButtonGroup();
17+
18+
//定义一级菜单
19+
var subButton = new SubButton()
20+
{
21+
name = "一级菜单"
22+
};
23+
bg.button.Add(subButton);
24+
25+
//下属二级菜单
26+
subButton.sub_button.Add(new SingleViewButton()
27+
{
28+
url = "https://book.weixin.senparc.com/book/link?code=SenparcRobotMenu",
29+
name = "《微信开发深度解析》"
30+
});
31+
subButton.sub_button.Add(new SingleClickButton()
32+
{
33+
key = "OneClick",
34+
name = "单击测试"
35+
});
36+
subButton.sub_button.Add(new SingleViewButton()
37+
{
38+
url = "https://weixin.senparc.com/",
39+
name = "Url跳转"
40+
});
41+
42+
//最多可添加 3 个一级自定义菜单，每个菜单下最多 5 个子菜单
43+
44+
var result = await CommonApi.CreateMenuAsync(appId, bg);
45+
}
46+
```
47+
48+
## 使用
49+
50+
设置完菜单后，当客户端点击菜单时，微信服务器会自动推送响应的回调信息到消息 URL（即已经设置好的 MessageHandler 内），只需在 CustomMessageHandler 中重写（`override`）对应的方法即可。如针对上述 **方法三** 已经设定生效的菜单，当用户点击【单击测试】按钮时，我们可以在 CustomMessageHandler 中进行接收和处理：
51+
52+
```cs
53+
public override async Task OnEvent_ClickRequestAsync(RequestMessageEvent_Click requestMessage)
54+
{
55+
var reponseMessage = CreateResponseMessage();
56+
57+
if (requestMessage.EventKey == "OneClick")
58+
{
59+
reponseMessage.Content = "您点击了【单击测试】按钮";
60+
}
61+
else
62+
{
63+
reponseMessage.Content = "您点击了其他事件按钮";
64+
}
65+
66+
return reponseMessage;
67+
}
68+
```
69+
70+
> 本项目参考文件：
71+
>
72+
> /MessageHandlers/**_CustomMessageHandler_Events.cs_**

‎docs/zh/guide/mp/messagehandler.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# MessageHandler
2+
3+
`MessageHandler` 用于处理微信公众号对话窗口的消息。
4+
5+
SDK 已经为开发者准备好了所有需要的基础功能，开发者只需要创建一个自定义的子类，补充需要自定义的业务逻辑。
6+
7+
## 自定义 MessageHandler
8+
9+
当前示例中，我们给自定义的 MessageHandler 取名 `CustomMessageHandler`。
10+
11+
> **CustomMessageHandler.cs 本项目参考文件：**
12+
>
13+
> /MessageHandlers/ 目录
14+
> **_CustomMessageHandler.cs_** MessageHandler 主文件 + 普通消息处理
15+
> **_CustomMessageHandler_Events.cs_** MessageHandler 事件消息处理
16+
> **_CustomMessageContext.cs_** 自定义重写 DefaultMpMessageContext 上下文（可选）
17+
18+
`CustomMessageHandler*.cs` 中所有演示的重写（`override`）方法中，只有 `DefaultResponseMessage()` 方法是必须重写的，其他所有 `OnXxxRequest()` 方法都为可选，当用户发送的消息，找不到对应重写方法时，则调用 `DefaultResponseMessage()` 方法。
19+
20+
MessageHandler 有两种承载方式，使其可以被外部（微信服务器）通过 URL 访问到。分别是**中间件方式**（推荐）和 **Controller 方式**。两种方式所使用的 `CustomMessageHandler` 是通用的，因此可以随时切换和共存。
21+
22+
## 中间件方式承载 MessageHandler
23+
24+
中间件方式是推荐的方式，也是最简化的方式，无需创建任何新文件，只需在 `Program.cs` 文件所有 Senparc.Weixin 注册代码执行后的下方，引入中间件：
25+
26+
```cs
27+
app.UseMessageHandlerForMp("/WeixinAsync", CustomMessageHandler.GenerateMessageHandler, options =>
28+
{
29+
options.AccountSettingFunc = context => Senparc.Weixin.Config.SenparcWeixinSetting;
30+
});
31+
32+
```
33+
34+
完成后，即可通过 Url **`域名/WeixinAsync`** 访问 MessageHandler，设置为公众号后台的消息 URL。
35+
36+
[测试 /WeixinAsync](https://sdk.weixin.senparc.com/WeixinAsync)
37+
38+
> 本项目参考文件：
39+
>
40+
> /**_Program.cs_**
41+
42+
更多中间件方式请参考：[《在 .NET Core 2.0/3.0 中使用 MessageHandler 中间件》](https://www.cnblogs.com/szw/p/Wechat-MessageHandler-Middleware.html)（同样适用于 .NET 6.0 及以上）。
43+
44+
## Controller 方式承载 MessageHandler
45+
46+
当中间件的方式满足不了需求时，可以使用 Controller 将执行过程“展开”，对每一步执行进行更加精确的控制或干预。
47+
48+
使用 Controller 方式，需要创建 2 个 Action，分别对应微信后台验证（Get 请求），以及真实消息推送（Post 请求）。本项目示例位于 `WeixinController.cs`中。
49+
50+
> WeixinController.cs 本项目参考文件：
51+
>
52+
> /**_Controllers/WeixinController.cs_**
53+
54+
完成后，即可通过 Url **`域名/Weixin`** 访问 MessageHandler，设置为公众号后台的消息 URL。
55+
56+
[测试 /Weixin](https://sdk.weixin.senparc.com/Weixin)
57+
58+
更多 Controller 方式请参考：[《了解 MessageHandler》](https://www.cnblogs.com/szw/p/3414862.html)（推荐使用全套异步方法）

0 commit comments

Comments
 (0)