简介这是一份面向使用C#语言的程序员的示例项目完整演示了将前端框架Blazor WebAssembly与后端远程过程调用框架gRPC进行集成的开发流程。项目通过.proto文件统一约定客户端与服务端的通信数据结构借助代码生成工具自动创建请求与响应对象从而让前后端代码保持同步大幅减少重复手工编写模型的工作量。包内共59个文件以C#源代码文件、Razor界面组件、项目工程文件、Dockerfile容器配置以及proto接口定义为主还包含docker-compose编排脚本、环境变量示例、证书和许可证文件及README说明等整体压缩包仅235KB目录结构清楚适合按模块阅读理解。目前已有307人学习下载比较适合想快速上手gRPC-Web通信、需要参考前后端分层设计的中级.NET开发者。通过学习可以掌握从proto契约设计、gRPC服务实现、API网关挂载到Docker容器部署的完整链路项目分为Protos、WeatherService、Api、Web.Client、Web.Server等工程每层职责明确可直接运行进行验证是一份体积小、实践性强的轻量级参考代码。1. 用 gRPC 撑起 Blazor WebAssembly 的前后端通信为什么这个示例值得动手跑一遍很多 C# 开发者第一次把 Blazor WebAssembly 和后端连起来时第一反应是拉一个 HttpClient 调 REST 接口能跑通就不想再折腾。但等你开始接触复杂业务——强类型契约、多服务调用、二进制传输、长连接推送——REST 那种靠人肉对齐的 Json 字符串就会变成负担。BlazorGrpc 这个示例解决的是另一个更棘手的问题在浏览器这个只能用 HTTP/1.1 的环境里怎么把 gRPC 的强类型、高性能通信链路完整地架起来。它适合已经写过几个 Blazor 页面、想升级通信层的人也适合刚接触 gRPC 但想知道 WebAssembly 这边怎么对接的 C# 后端程序员。看完这篇笔记你应该能独立搭建一条从 .proto 文件到前端调用的完整链路并且知道哪些地方会翻车。2. 为什么选 gRPC-Web 而不是 HTTP REST协议选型与四个现实约束2.1 HTTP/2 与浏览器 API 之间的断层gRPC 原生协议绑定 HTTP/2这是它高效复用连接、承载二进制帧的基础。服务器之间通信时gRPC 可以直接跑在 HTTP/2 上没有任何障碍。但浏览器端的 Blazor WebAssembly 环境不是这样——现代浏览器虽然支持 HTTP/2暴露给前端的是 Fetch API 和 XMLHttpRequest它们只能构造 HTTP/1.1 语义的请求不能直接发送 gRPC 的 HTTP/2 帧。这就出现了断层你没法像在桌面客户端里那样直接 new 一个 Channel 然后 Invoke 远程方法。第一次踩这个坑的人很容易怀疑是自己代码写错了反复检查 Address 和证书配置最后发现是浏览器层根本不给你发 HTTP/2 帧的机会。这个示例的核心价值就在这里它用 gRPC-Web 协议把 HTTP/1.1 的请求转换为 gRPC 能识别的格式让浏览器里的 Blazor 代码可以像普通 gRPC 客户端一样发起调用。2.2 gRPC-Web 的代理模式与传输格式gRPC-Web 不是让浏览器直接发 HTTP/2 帧而是让客户端用 HTTP/1.1 发送一个特殊格式的请求由代理层或者服务端中间件把它转成标准 gRPC 请求。请求的 Content-Type 是application/grpc-webproto响应使用 Base64 编码将二进制 protobuf 载荷包起来。这套机制意味着两条可行的接入路径服务端中间件直接转换或者通过 Envoy 这类代理转发。在 .NET 生态里官方给出的方案是Grpc.AspNetCore.Web中间件。它挂在 ASP.NET Core 管道里识别到application/grpc-web开头的请求就自动转换不需要额外部署独立的代理进程。这个示例就是走这条路径——服务端代码加两行配置客户端把GrpcWebHandler塞进 Channel 的 HttpHandler 链路两边就通了。我在本地跑这个示例时第一反应是这也太简单了仔细看它背后的原理才明白简单是因为中间件把最复杂的帧转换和 trailer 处理都封装好了。2.3 方案对比JSON REST、SignalR、gRPC-Web对比维度JSON RESTSignalRgRPC-Web契约强类型弱靠手写 DTO 对齐中Hub 方法签名是强类型强.proto 自动生成双端代码数据格式JSON 文本JSON / MessagePackProtobuf 二进制浏览器兼容全支持全支持需要 gRPC-Web 中间件或代理流式支持不支持支持完整双向流标准 gRPC 流式在 gRPC-Web 支持有限性能中中高高调试工具浏览器 DevTools 直接看需要专门工具需要 grpcurl 或拦截器这个对比不是说 JSON REST 不能用而是当你面临一个多服务、多团队协作的中大型项目时.proto 文件就是唯一的契约来源。双端代码从同一个 proto 生成字段名、类型、服务方法永远不会出现“前端字段拼错了”这种低级问题。SignalR 也不错但它更像是一个实时通信框架不是通用 RPC如果只是要个函数调用式的接口gRPC-Web 的语义更直接。2.4 示例项目里用到的工具链与版本边界跑通这个示例需要关注几个工具的版本协同。服务端用Grpc.AspNetCore提供 gRPC 服务加上Grpc.AspNetCore.Web启用 gRPC-Web 转换客户端 Blazor WebAssembly 里需要Grpc.Net.Client、Grpc.Net.Client.Web和Google.Protobuf。这些包的版本最好对齐我用的是 .NET 8 环境下各包的最新稳定版直接通过 NuGet 引用即可。需要特别留意的是Grpc.Net.Client在浏览器环境里不能直接使用默认的 HTTP 通道必须显式指定GrpcWebHandler。而且 Blazor WebAssembly 运行在浏览器沙箱里底层不能用完整的 .NET HttpClient 实现Grpc.Net.Client.Web包就是专门为这种场景准备的——它实现了一个基于浏览器 Fetch API 的传输层配合GrpcWebHandler完成协议升级。这些边界在普通控制台程序里不会遇到只有到了 WebAssembly 环境才显现。提示如果你在控制台或桌面程序里跑了 gRPC 示例然后在 Blazor WebAssembly 里原样复制代码多半会在运行时抛异常。先确认两件事Channel 的 HttpHandler 是不是 GrpcWebHandler服务端有没有启用 gRPC-Web 中间件。3. 先把 proto 写对服务定义与消息契约的落地细节3.1 proto3 语法要点包名、服务、消息gRPC 的双端代码生成全部依赖 .proto 文件所以第一步是把服务契约定义清楚。用 proto3 语法文件开头声明syntax proto3;然后定义package——这个包名会直接影响 C# 生成的命名空间。我在实际项目里习惯用package声明为反向域名加项目名比如package demo.blazorgrpc;生成的 C# 命名空间默认是Demo.BlazorGrpc可以用option csharp_namespace BlazorGrpc.Shared;覆盖成更直观的名字。服务定义用service关键字里面写rpc方法。最常见的定义模式是请求一个消息、返回一个消息比如syntax proto3; package demo.blazorgrpc; option csharp_namespace BlazorGrpc.Shared; service UserService { rpc GetUserById (UserRequest) returns (UserReply); } message UserRequest { int32 id 1; } message UserReply { int32 id 1; string name 2; string email 3; }这段定义里的UserService是服务名GetUserById是方法名UserRequest和UserReply是出入参消息。写完后用工具生成 C# 代码服务端得到一个UserServiceBase抽象类和UserService.UserServiceClient客户端直接 new 这个 Client 就能调用。3.2 生成 C# 代码的两种方式我平时生成 proto 的 C# 代码最常用两种方式。第一种是在 Visual Studio 里通过 Connected Service 功能右键项目选择添加 gRPC 服务引用指定 proto 文件路径它会自动配置 Grpc.Tools 并生成代码。第二种是手动在 .csproj 里加 ItemGroupItemGroup Protobuf IncludeProtos\user.proto GrpcServicesBoth / /ItemGroupGrpcServices的参数有三个可选值Server只生成服务端基类Client只生成客户端Both两边都生成。如果 proto 文件是放在一个单独的共享类库里两个端都引用这个类库那用Both最省事。这里有个细节要注意GrpcServicesBoth生成的服务端基类要求项目引用Grpc.AspNetCore而客户端代码要求引用Grpc.Net.Client类库自身不能同时引用这两个大包否则会把依赖项拖进 Blazor WebAssembly 的发布产物里。我一般会建三个项目共享契约类库、服务端项目、Blazor WebAssembly 客户端项目共享类库只引用Google.Protobuf和Grpc.Core.Api两侧各自引用自己的运行时。3.3 这个示例里的核心服务定义解读回到 BlazorGrpc 这个示例它的关键不在业务有多复杂而在把一套麻雀虽小五脏俱全的服务定义跑通。默认演示的 Greeter 服务是基础模板只返回一句欢迎语并不能体现 gRPC 的强类型优势。我建议看完示例后自己加一个稍微复杂的服务比如上面UserService这样的多几个字段再配合嵌套消息试一遍。嵌套消息是 proto 里很常用的能力比如一个GetUserDetailReply里面包含一个UserProfile消息字段。代码生成后你会看到 C# 侧对应一个UserProfile类嵌套在GetUserDetailReply.Types下面。这个嵌套关系在 proto 里是层级明确的代码生成后也不会丢失信息。我遇到过有人把嵌套消息在外层又重新定义一遍导致类型重复无法编译其实只要在 proto 里定义一次生成代码会自动处理。message GetUserDetailReply { UserProfile profile 1; repeated string tags 2; } message UserProfile { string name 1; string email 2; int32 age 3; }注意repeated string tags 2;生成到 C# 是Google.Protobuf.Collections.RepeatedFieldstring它是一个集合类型用起来和 List 差不多但不能直接new赋值。我见过有人尝试Reply.Tags new Liststring()编译直接报错正确做法是Reply.Tags.Add(xxx)。这个细节在示例代码里应该能看到但对新手来说是个很容易卡住的类型问题。4. 服务端与客户端双向打通注册、映射与调用链4.1 服务端启用 gRPC-Web 的注册代码服务端要做的第一步是在Program.cs里注册 gRPC 服务和 CORS 策略。浏览器环境下跨源请求是常态Blazor WebAssembly 应用和后端 API 往往部署在不同源上不配 CORS 一定会被浏览器拦截。完整配置如下var builder WebApplication.CreateBuilder(args); builder.Services.AddGrpc(); builder.Services.AddCors(o o.AddPolicy(AllowBlazor, b b.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader())); var app builder.Build(); app.UseCors(); app.UseGrpcWeb(); app.MapGrpcServiceUserServiceImpl().EnableGrpcWeb(); app.Run();这段代码里三个关键点。AddGrpc()是注册 gRPC 核心服务UseGrpcWeb()是启用 gRPC-Web 中间件EnableGrpcWeb()是让具体服务支持 gRPC-Web 协议。第三个方法很容易漏——如果你只加了UseGrpcWeb()但服务映射时没调用EnableGrpcWeb()中间件会把请求识别为 gRPC-Web 但找不到对应处理入口行为表现是客户端调用失败且服务端日志无输出。我刚用这个示例时就在这里卡过半天后来逐个排查才发现是服务映射那行没加方法。4.2 客户端注入 gRPC Channel 与客户端Blazor WebAssembly 客户端这边的配置在Program.cs里核心是为GrpcChannel指定GrpcWebHandler。示例的典型写法如下var httpHandler new GrpcWebHandler(GrpcWebMode.GrpcWeb, new HttpClientHandler()); var channel GrpcChannel.ForAddress(https://localhost:7111, new GrpcChannelOptions { HttpHandler httpHandler }); var client new UserService.UserServiceClient(channel); builder.Services.AddSingleton(client);GrpcWebMode.GrpcWeb是默认模式它要求服务端支持 gRPC-Web 中间件另一个可选值是GrpcWebMode.GrpcWebText区别在于响应的编码方式Text 模式对浏览器兼容性更好但也更慢。如果服务端是 Envoy 代理通常用 Text 模式如果是 ASP.NET Core 的中间件方案两个模式都能跑通。HttpClientHandler在 Blazor WebAssembly 环境下会自动被浏览器请求适配器接管不需要额外配置证书或代理。这里要特别注意Channel 的地址必须指向服务端能被外部访问的地址不能是localhost以外的内部地址也不能是只监听了 IPv6 的地址。如果服务端在开发环境监听的是https://localhost:7111客户端就填这个发布到服务器后要改成部署域的 HTTPS 地址。4.3 从按钮点击到 gRPC 返回一次完整调用链在 Razor 组件里调用 gRPC 客户端整个流程可以从一个按钮点击事件完整拆解来看inject UserService.UserServiceClient UserClient button onclickLoadUser查询用户/button divuserName/div code { private string userName; private async Task LoadUser() { var request new UserRequest { Id 1 }; var response await UserClient.GetUserByIdAsync(request); userName response.Name; } }按钮点击后触发LoadUser()构造出强类型的UserRequest对象客户端内部把对象序列化成 protobuf 二进制通过GrpcWebHandler包装成 HTTP/1.1 请求发出服务端收到后UseGrpcWeb()中间件把请求帧转换成标准 gRPC 请求路由到UserServiceImpl.GetUserById方法方法返回的UserReply对象被序列化后沿原路返回客户端反序列化成强类型对象。这条链路里最容易出错的地方在两处客户端构造请求时的字段赋值和服务端返回对象的字段索引。protobuf 序列化按字段序号标记数据不是按字段名。比如UserRequest的id字段序号是 1如果服务端和客户端版本不一致比如一端的 proto 把id调到了序号 2另一端还是按序号 1 发送就会静默地得到错误数据——不会报异常但字段值对不上。所以当出现“数据好像对但是不对”的玄学问题时优检查两个端 proto 字段序号是否一致。提示gRPC 调用默认是异步的Blazor 组件里直接await就行但要注意组件生命周期。如果用户连续点击按钮同一个GetUserByIdAsync可能并发触发多次需要在业务层自行加节流或取消令牌这不在框架自动处理范围内。5. 避坑Blazor WebAssembly gRPC 最常见的五个翻车点5.1 调用直接失败服务端没开 CORS现象客户端代码完全正确Channel 配置也没问题但浏览器控制台报跨域错误请求根本没有到达服务端。原因Blazor WebAssembly 运行在浏览器沙箱里所有请求都遵守浏览器同源策略。服务端没有配置 CORS 策略浏览器直接拦截响应客户端拿不到任何数据。解决在服务端Program.cs中注册 CORS 服务并用app.UseCors()启用具体代码见 4.1 节。需要注意的是.AllowAnyOrigin()在生产环境不可取应该替换为.WithOrigins(https://你的前端域名)否则任何网站都能调用你的后端接口。5.2 返回数据是空对象proto 字段序号被改动现象调用成功没有异常但返回的UserReply对象所有字段都是默认值或者字段值张冠李戴。原因proto 文件被修改过字段序号发生了变动。由于 protobuf 按字段序号编码序号前移后旧数据会被解析到错误的字段上且不会报错。这是 protobuf 的静默错误排查起来最隐蔽。解决严格按照 proto 向后兼容规则修改文件——新增字段用新的序号永不修改已有字段的序号永不复用已删除字段的序号。前一端改动 proto 后立刻批量重新生成两端代码避免生成时间错位。5.3 响应永远超时App 地址与后端地址跨源且未走 HTTPS现象本地调试时调用偶尔成功发布后线上几乎必现超时或者本地直接用http://地址时也超时。原因现代浏览器环境要求 gRPC-Web 的服务端必须是 HTTPS。如果你是 http 站点调用 https 的 gRPC-Web或者反过来浏览器会直接屏蔽混合内容同时如果服务端地址是http://localhost而前端是https://xxx也会触发安全策略。解决保证前端页面和后端 gRPC-Web 服务都走 HTTPS。本地开发用 IIS Express 或 Kestrel 自带的开发证书发布后用反向代理终结 TLS。如果非要本地 http 调试可以在浏览器安全例外里放开但这不是能交付给用户的方案。5.4 编译报错重复类型proto 生成代码与手写代码冲突现象编译时提示某个类重复定义比如UserProfile出现两次。原因proto 文件放在共享项目里同时服务端项目和客户端项目都引用了它并自己生成了代码两边生成时间不同步或者某个项目把GrpcServices和手动引用的生成结果都加了进来。解决把 proto 文件和生成代码收敛到一个共享类库项目服务端和客户端只引用这个类库的外部 NuGet 包不在自己项目里重复生成如果必须各自生成在.csproj里只用Protobuf的 ItemGroup 生成一次项目中绝不手写同名 partial 类。养成这个习惯后这类问题基本杜绝。5.5 发布后连不上开发环境代理与生产环境地址分离现象本地跑得好好的一发布到服务器前端白屏或者调用报错。原因示例默认把服务端地址写死在客户端代码里比如https://localhost:7111。本地能跑是因为前后端在同一台开发机发布后这个地址指向的就不对了。解决把服务端地址提到配置文件中客户端启动时从环境配置读取var serverAddress builder.Configuration[GrpcServerAddress] ?? https://localhost:7111;发布时在 Web.config 或静态配置里指定为生产地址。示例代码里如果没给你留出配置入口你也要自己加这个壳这是从 demo 走向生产的第一步。静态配置没有动态更新的能力前端重新发布才生效但只要部署流程里把这一步固化下来不会出大问题。6. 几个能直接用的小技巧拦截器、错误码与流式响应降级6.1 用拦截器统一携带身份令牌实际项目里不可能允许匿名调用业务接口。客户端侧可以写一个自定义拦截器把 JWT 令牌附加到每个请求的 metadata 上public class AuthInterceptor : Interceptor { private readonly string _token; public AuthInterceptor(string token) _token token; public override AsyncUnaryCallTResponse AsyncUnaryCallTRequest, TResponse( TRequest request, ClientInterceptorContextTRequest, TResponse context) { context.Options.Headers.Add(Authorization, $Bearer {_token}); return base.AsyncUnaryCall(request, context); } }服务端直接在方法里检查ServerCallContext的请求头即可。这比在每次调用前手动给CallOptions塞 Header 干净得多。注意拦截器是客户端侧的服务端要做的是校验不要依赖客户端的构造方式。6.2 把 gRPC 状态码映射成前端可读错误gRPC 原生状态码只有几个整数浏览器端拿到后如果不翻译根本看不懂。我会把 StatusCode 统一处理为一个可读的对象public static class GrpcErrorMapper { public static string GetMessage(Status status) { return status.StatusCode switch { StatusCode.NotFound 请求的数据不存在, StatusCode.Unauthenticated 登录状态已失效, StatusCode.PermissionDenied 没有操作权限, StatusCode.Unavailable 服务暂不可用, _ $请求失败状态码 {status.StatusCode} }; } }在使用时尽量用服务端返回的业务错误码来扩展状态码信息比如在 Response 消息里加一个int code和一个string message不依赖 gRPC 的 trailer 传递明细这样两端都容易处理。6.3 流式服务端推送的降级方案gRPC-Web 对流式支持有限双向流基本不可用。如果业务需要推送示例里一般不会展开讲但你应该知道降级路径。最简单的方式是客户端轮询定时调用一个普通 RPC 方法获取增量。另一个是服务端把消息发到消息队列Blazor 前端用 SignalR 接收再触发界面更新。设计上不要把流式依赖当作默认方案先跑通普通调用再评估推送需求。这套示例的价值不只是运行起来的那一刻而是让你把浏览器、gRPC、protobuf、CORS、HTTPS 这几个环节从黑匣子变成手里有数的零件。我从那次漏掉EnableGrpcWeb()的排查开始以后每次搭建 gRPC-Web 链路都强制走一遍这个检查顺序服务端是否启用 gRPC-Web、服务映射是否开启、两端 proto 是否同步、CORS 是否正确、地址是否跨源 HTTPS。把这个顺序固化进你的部署清单能少掉许多“本地能跑线上挂”的尴尬。希望帮到你。本文还有配套的精品资源点击获取