如何在Windows Server生产环境调试Blazor WASM客户端代码及解决独有异常

一、生产环境启用Alt+Shift+D调试完整流程 #

• 第一步：修改Blazor WASM客户端项目的.csproj配置文件，在<PropertyGroup>节点下添加以下配置：

  <BlazorEnableDebugging>true</BlazorEnableDebugging>
  <DebugType>portable</DebugType>
  <DebugSymbols>true</DebugSymbols>
  

• 第二步：修改ASP.NET Core托管服务端的Program.cs文件，临时在生产环境启用WebAssembly调试中间件：

  // 调试完成后务必删除该行，避免生产环境安全和性能问题
  app.UseWebAssemblyDebugging();
  

• 第三步：发布项目时选择Debug配置，不要使用Release配置，发布前清空所有历史发布产物，避免缓存文件干扰
• 第四步：部署到Windows Server后重启站点，客户端使用Chromium内核浏览器（Chrome、Edge）访问站点，按Alt+Shift+D按照提示开启浏览器远程调试参数后重启浏览器，即可进入调试界面

注意：调试完成后必须回滚所有调试相关配置，改用Release配置重新发布上线 #

二、JSON反序列化异常解决方案 #

该错误是System.Text.Json反序列化Tuple<T1,T2>类型时，无法匹配构造函数参数导致的，仅在生产环境触发通常是因为Release模式下的序列化裁剪、大小写匹配规则和Debug/Staging环境不一致，或是生产环境接口返回字段与预期不符。

• 方案1：替换Tuple类型为自定义实体类，添加无参构造函数并显式指定JSON字段映射：

  public class FilterResultDto
  {
      // 无参构造函数解决绑定失败问题
      public FilterResultDto(){}
      
      [JsonPropertyName("item1")]
      public List<Tuple<FilterType, string>> Filters { get; set; }
      
      [JsonPropertyName("item2")]
      public PaginatedResultDto<ProductCardDto> PaginatedData { get; set; }
  }
  

• 方案2：如果需要保留Tuple类型，调整Json序列化配置：

  var jsonOptions = new JsonSerializerOptions
  {
      // 启用不区分大小写匹配
      PropertyNameCaseInsensitive = true,
      IncludeFields = true
  };
  

• 方案3：.NET 5存在Tuple反序列化的已知兼容性问题，升级项目到.NET 6及以上版本可直接修复该问题
• 临时排查方法：在反序列化前先打印接口返回的原始JSON字符串，对比生产环境和本地/Staging环境的返回字段差异，确认是否存在字段缺失问题

内容的提问来源于stack exchange，提问作者ParsaGachkar