JeffreySu/WeiXinMPSDK · error · MessageHandlerException

DefaultMessageHandlerAsyncEvent 类型未作处理：

Error message

DefaultMessageHandlerAsyncEvent 类型未作处理：{base.DefaultMessageHandlerAsyncEvent.ToString()}

What it means

In the async message-handling pipeline, DefaultAsyncMethod switches on base.DefaultMessageHandlerAsyncEvent to decide how to produce a default response (DefaultResponseMessageAsync or running the sync syncMethod). Any value outside the defined enum members throws MessageHandlerException, which can only happen if the enum was assigned an invalid/unknown value — an internal invariant violation.

Solutions

Leave DefaultMessageHandlerAsyncEvent at its default or set it explicitly to DefaultMessageHandlerAsyncEvent.DefaultResponseMessageAsync or SelfSynicMethod before executing the handler.
Search code/config for assignments to DefaultMessageHandlerAsyncEvent and remove invalid values.
Upgrade the SDK to ensure application and library enum versions match.
If you must intercept, catch MessageHandlerException around the Execute/DefaultAsyncMethod call and fall back to syncMethod.

Example fix

// before
handler.DefaultMessageHandlerAsyncEvent = (DefaultMessageHandlerAsyncEvent)99;
await handler.ExecuteAsync();
// after
handler.DefaultMessageHandlerAsyncEvent = DefaultMessageHandlerAsyncEvent.DefaultResponseMessageAsync;
await handler.ExecuteAsync();

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(DefaultMessageHandlerAsyncEvent), handler.DefaultMessageHandlerAsyncEvent))
{
    handler.DefaultMessageHandlerAsyncEvent = DefaultMessageHandlerAsyncEvent.DefaultResponseMessageAsync;
}

Type guard

bool isValidAsyncEvent(DefaultMessageHandlerAsyncEvent e) =>
    e == DefaultMessageHandlerAsyncEvent.DefaultResponseMessageAsync ||
    e == DefaultMessageHandlerAsyncEvent.SelfSynicMethod;

Try / catch

try
{
    await handler.ExecuteAsync();
}
catch (MessageHandlerException ex)
{
    log.Error("Invalid DefaultMessageHandlerAsyncEvent", ex);
    handler.DefaultMessageHandlerAsyncEvent = DefaultMessageHandlerAsyncEvent.DefaultResponseMessageAsync;
    await handler.ExecuteAsync();
}

Prevention

Never cast ints to DefaultMessageHandlerAsyncEvent without Enum.IsDefined validation.
Do not persist handler enum state in cache/config; set it explicitly in code each time.
Keep SDK versions aligned across projects sharing this enum.
Set the property explicitly right after constructing the MessageHandler.

When it happens

Trigger: DefaultMessageHandlerAsyncEvent property set to a value not in {DefaultResponseMessageAsync, SelfSynicMethod} — typically via reflection, serialization restoring an out-of-range int, or a custom build/modified enum; direct invocation of DefaultAsyncMethod after tampering with the property.

Common situations: Deserializing handler config/state from cache or config that maps an obsolete enum numeric value; custom DI constructing the handler and setting DefaultMessageHandlerAsyncEvent incorrectly; upgrading SDK versions where enum members were renamed/removed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of JeffreySu/WeiXinMPSDK@be573f6f94 (2026-09-12). Data as JSON: /api/errors/d07473cf646a244f. Report an issue: GitHub.

Appendix: source

Thrown at src/Senparc.Weixin.MP/Senparc.Weixin.MP/MessageHandlers/Async/MessageHandlerAsync.cs:78

    {
        /// <summary>
        /// 自动判断默认异步方法调用（在没有override的情况下调用的默认方法）
        /// </summary>
        /// <param name="requestMessage">requestMessage</param>
        /// <param name="syncMethod">同名的同步方法(DefaultMessageHandlerAsyncEvent值为SelfSynicMethod时调用)</param>
        /// <returns></returns>
        private async Task<IResponseMessageBase> DefaultAsyncMethod(IRequestMessageBase requestMessage, Func<IResponseMessageBase> syncMethod)
        {
            switch (base.DefaultMessageHandlerAsyncEvent)
            {
                case DefaultMessageHandlerAsyncEvent.DefaultResponseMessageAsync:
                    //返回默认信息
                    return await DefaultResponseMessageAsync(requestMessage).ConfigureAwait(false);
                case DefaultMessageHandlerAsyncEvent.SelfSynicMethod:
                    //返回同步信息
                    return await Task.Run(syncMethod).ConfigureAwait(false);
                default:
                    throw new MessageHandlerException($"DefaultMessageHandlerAsyncEvent 类型未作处理：{base.DefaultMessageHandlerAsyncEvent.ToString()}");
            }
        }

        /// <summary>
        /// 【异步方法】执行微信请求
        /// </summary>
        public override async Task BuildResponseMessageAsync(CancellationToken cancellationToken)
        {
            #region NeuChar 执行过程

            var weixinAppId = this._postModel == null ? "" : this._postModel.AppId;

            switch (RequestMessage.MsgType)
            {
                case RequestMsgType.Text:
                    {
                        try
                        {

View on GitHub (pinned to be573f6f94)