feat(wxapi): 新增序列化回调通知事件实体类的扩展方法

src/SKIT.FlurlHttpClient.Wechat.Api/Exceptions/WechatApiEventSerializationException.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace SKIT.FlurlHttpClient.Wechat.Api.Exceptions
+{
+    public class WechatApiEventSerializationException : WechatApiException
+    {
+        /// <inheritdoc/>
+        internal WechatApiEventSerializationException()
+        {
+        }
+
+        /// <inheritdoc/>
+        internal WechatApiEventSerializationException(string message) 
+            : base(message)
+        {
+        }
+
+        /// <inheritdoc/>
+        internal WechatApiEventSerializationException(string message, Exception innerException) 
+            : base(message, innerException)
+        {
+        }
+    }
+}

src/SKIT.FlurlHttpClient.Wechat.Api/Extensions/WechatApiClientEventExtensions.cs

@@ -1,5 +1,9 @@
 using System;
+using System.Collections.Generic;
 using System.IO;
+using System.Reflection;
+using System.Text;
+using System.Text.RegularExpressions;
 using System.Xml.Serialization;
 
 namespace SKIT.FlurlHttpClient.Wechat.Api
@@ -21,7 +25,14 @@ namespace SKIT.FlurlHttpClient.Wechat.Api
             if (client == null) throw new ArgumentNullException(nameof(client));
             if (string.IsNullOrEmpty(callbackJson)) throw new ArgumentNullException(callbackJson);
 
-            return client.JsonSerializer.Deserialize<TEvent>(callbackJson);
+            try
+            {
+                return client.JsonSerializer.Deserialize<TEvent>(callbackJson);
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatApiEventSerializationException("Deserialize event failed. Please see the `InnerException` for more details.", ex);
+            }
         }
 
         /// <summary>
@@ -36,9 +47,138 @@ namespace SKIT.FlurlHttpClient.Wechat.Api
             if (client == null) throw new ArgumentNullException(nameof(client));
             if (string.IsNullOrEmpty(callbackXml)) throw new ArgumentNullException(callbackXml);
 
-            using StringReader reader = new StringReader(callbackXml);
-            XmlSerializer xmlSerializer = new XmlSerializer(typeof(TEvent), new XmlRootAttribute("xml"));
-            return (TEvent)xmlSerializer.Deserialize(reader);
+            try
+            {
+                using var reader = new StringReader(callbackXml);
+
+                XmlSerializer xmlSerializer = new XmlSerializer(typeof(TEvent), new XmlRootAttribute("xml"));
+                return (TEvent)xmlSerializer.Deserialize(reader);
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatApiEventSerializationException("Deserialize event failed. Please see the `InnerException` for more details.", ex);
+            }
+        }
+
+        /// <summary>
+        /// 将 <see cref="WechatApiEvent"/> 对象序列化成 JSON。
+        /// </summary>
+        /// <typeparam name="TEvent"></typeparam>
+        /// <param name="client"></param>
+        /// <param name="callbackModel"></param>
+        /// <param name="safety">是否是安全模式。</param>
+        /// <returns></returns>
+        public static string SerializeEventToJson<TEvent>(this WechatApiClient client, TEvent callbackModel, bool safety = false)
+            where TEvent : WechatApiEvent, WechatApiEvent.Types.IJsonSerializable, new()
+        {
+            string json;
+
+            try
+            {
+                json = client.JsonSerializer.Serialize(callbackModel);
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatApiEventSerializationException("Serialize event failed. Please see the `InnerException` for more details.", ex);
+            }
+
+            if (safety)
+            {
+                if (string.IsNullOrEmpty(client.Credentials.PushEncodingAESKey))
+                    throw new Exceptions.WechatApiEventSerializationException ("Encrypt event failed, because of there is no encoding AES key.");
+                if (string.IsNullOrEmpty(client.Credentials.PushToken))
+                    throw new Exceptions.WechatApiEventSerializationException("Encrypt event failed, because of there is no token.");
+
+                try
+                {
+                    string timestamp = DateTimeOffset.Now.ToLocalTime().ToUnixTimeSeconds().ToString();
+                    string nonce = DateTimeOffset.Now.Ticks.ToString("x");
+                    string cipher = Utilities.WxBizMsgCryptor.AESEncrypt(
+                        plainText: json,
+                        encodingAESKey: client.Credentials.PushEncodingAESKey!,
+                        appId: client.Credentials.AppId
+                    );
+                    string sign = Utilities.WxBizMsgCryptor.GenerateSignature(
+                        sToken: client.Credentials.PushToken!,
+                        sTimestamp: timestamp,
+                        sNonce: nonce,
+                        sMsgEncrypt: cipher
+                    );
+
+                    json = client.JsonSerializer.Serialize(new Dictionary<string, string>()
+                    {
+                        { "Encrypt", cipher },
+                        { "TimeStamp", timestamp },
+                        { "Nonce", nonce },
+                        { "MsgSignature", sign }
+                    });
+                }
+                catch (Exception ex)
+                {
+                    throw new Exceptions.WechatApiEventSerializationException("Encrypt event failed. Please see the `InnerException` for more details.", ex);
+                }
+            }
+
+            return json;
+        }
+
+        /// <summary>
+        /// 将 <see cref="WechatApiEvent"/> 对象序列化成 XML。
+        /// </summary>
+        /// <typeparam name="TEvent"></typeparam>
+        /// <param name="client"></param>
+        /// <param name="callbackModel"></param>
+        /// <param name="safety">是否是安全模式。</param>
+        /// <returns></returns>
+        public static string SerializeEventToXml<TEvent>(this WechatApiClient client, TEvent callbackModel, bool safety = false)
+            where TEvent : WechatApiEvent, WechatApiEvent.Types.IXmlSerializable, new()
+        {
+            string xml;
+
+            try
+            {
+                using var stream = new MemoryStream();
+                using var writer = new System.Xml.XmlTextWriter(stream, Encoding.UTF8);
+                writer.Formatting = System.Xml.Formatting.None;
+
+                XmlSerializer xmlSerializer = new XmlSerializer(typeof(TEvent), new XmlRootAttribute("xml"));
+                XmlSerializerNamespaces xmlNamespace = new XmlSerializerNamespaces();
+                xmlNamespace.Add(string.Empty, string.Empty);
+                xmlSerializer.Serialize(writer, callbackModel, xmlNamespace);
+                writer.Flush();
+                xml = Encoding.UTF8.GetString(stream.ToArray());
+                xml = Regex.Replace(xml, "\\s+<\\w+ (xsi|d2p1):nil=\"true\"[^>]*/>", string.Empty, RegexOptions.IgnoreCase);
+                xml = Regex.Replace(xml, "<\\?xml[^>]*\\?>", string.Empty, RegexOptions.IgnoreCase);
+            }
+            catch (System.Xml.XmlException ex)
+            {
+                throw new Exceptions.WechatApiEventSerializationException("Serialize event failed. Please see the `InnerException` for more details.", ex);
+            }
+
+            if (safety)
+            {
+                if (string.IsNullOrEmpty(client.Credentials.PushEncodingAESKey))
+                    throw new Exceptions.WechatApiEventSerializationException("Encrypt event failed, because of there is no encoding AES key.");
+                if (string.IsNullOrEmpty(client.Credentials.PushToken))
+                    throw new Exceptions.WechatApiEventSerializationException("Encrypt event failed, because of there is no token.");
+
+                try
+                {
+                    string cipher = Utilities.WxBizMsgCryptor.AESEncrypt(
+                        plainText: xml,
+                        encodingAESKey: client.Credentials.PushEncodingAESKey!,
+                        appId: client.Credentials.AppId
+                    );
+
+                    xml = Utilities.WxBizMsgCryptor.WrapXml(sToken: client.Credentials.PushToken!, sMsgEncrypt: cipher);
+                }
+                catch (Exception ex)
+                {
+                    throw new Exceptions.WechatApiEventSerializationException("Encrypt event failed. Please see the `InnerException` for more details.", ex);
+                }
+            }
+
+            return xml;
         }
     }
 }

src/SKIT.FlurlHttpClient.Wechat.Api/Settings/Credentials.cs

@@ -18,6 +18,16 @@ namespace SKIT.FlurlHttpClient.Wechat.Api.Settings
         /// </summary>
         public string AppSecret { get; }
 
+        /// <summary>
+        /// 初始化客户端时 <see cref="WechatApiClientOptions.PushEncodingAESKey"/> 的副本。
+        /// </summary>
+        public string? PushEncodingAESKey { get; }
+
+        /// <summary>
+        /// 初始化客户端时 <see cref="WechatApiClientOptions.PushToken"/> 的副本。
+        /// </summary>
+        public string? PushToken { get; }
+
         /// <summary>
         /// 初始化客户端时 <see cref="WechatApiClientOptions.ImmeDeliveryAppKey"/> 的副本。
         /// </summary>
@@ -39,6 +49,8 @@ namespace SKIT.FlurlHttpClient.Wechat.Api.Settings
 
             AppId = options.AppId;
             AppSecret = options.AppSecret;
+            PushEncodingAESKey = options.PushEncodingAESKey;
+            PushToken = options.PushToken;
             ImmeDeliveryAppKey = options.ImmeDeliveryAppKey;
             ImmeDeliveryAppSecret = options.ImmeDeliveryAppSecret;
             MidasAppKey = options.MidasAppKey;

src/SKIT.FlurlHttpClient.Wechat.Api/WechatApiClientOptions.cs

@@ -29,6 +29,16 @@ namespace SKIT.FlurlHttpClient.Wechat.Api
         /// </summary>
         public string AppSecret { get; set; } = default!;
 
+        /// <summary>
+        /// 获取或设置微信服务器推送的 EncodingAESKey。
+        /// </summary>
+        public string? PushEncodingAESKey { get; set; }
+
+        /// <summary>
+        /// 获取或设置微信服务器推送的 Token。
+        /// </summary>
+        public string? PushToken { get; set; }
+
         /// <summary>
         /// 获取或设置即时配送公司帐号 AppKey。
         /// </summary>