WCF Web.config配置详解 .NET WCF服务XML配置指南

wcf web.config 的 必须手动写全，缺任一子节（如 、）都会导致服务启动失败，错误提示模糊；contract 必须为完整命名空间类型名，address 为空时需配置

WCF web.config 中的 <system.servicemodel></system.servicemodel> 必须手动写全

WCF 不会自动补全或推断服务模型配置，哪怕只缺一个子节（比如漏掉 <behaviors></behaviors> 或 <bindings></bindings>），服务就起不来，且错误提示常指向 ServiceHost 初始化失败，而非具体哪行 xml 错了。

• 常见错误现象：The service 'xxx' could not be activated 或 Configuration binding extension not found，实际只是 <extensions></extensions> 没注册或 <bindingextensions></bindingextensions> 缺失
• 使用场景：自定义绑定（如 .netTcpBinding）、启用元数据交换（mexhttpBinding）、加行为（serviceMetadata、serviceDebug）都依赖该节显式声明
• 参数差异：<basichttpbinding></basichttpbinding> 默认兼容老客户端，但不支持事务；<wshttpbinding></wshttpbinding> 默认启用安全和可靠会话，若没配证书或没开 https，直接报 500 错误
• 示例中易错点：<endpoint address="" binding="wsHttpBinding" contract="IMyService"></endpoint> 的 address 为空时，必须确保 <host><baseaddresses></baseaddresses></host> 已设，否则地址解析失败

endpoint 的 contract 必须是完整类型名，且程序集已加载

写 contract="MyService" 而不是 contract="MyNamespace.IMyService" 是最常导致“找不到契约”的原因——WCF 不做命名空间推导，也不查 using。

• 常见错误现象：Contract name 'xxx' does not match with the provided contract name，尤其在 iis 托管时，可能因程序集未被 <compilation></compilation> 引入而静默失败
• 使用场景：接口定义在单独类库时，contract 值必须带命名空间；若实现类与接口同名（如 MyService 实现 IMyService），别误填成实现类名
• 性能影响：每次请求都会反射匹配 contract 字符串到类型，拼错或大小写不对（如 imyservice）会导致 TypeLoadException，比运行时异常更早抛出
• 检查方法：用 typeof(IMyService).AssemblyQualifiedName 输出真实字符串，直接粘贴进 contract 属性

IIS 托管下 <servicehostingenvironment></servicehostingenvironment> 的 multipleSiteBindingsEnabled 很关键

默认值是 false，意味着一个 <service></service> 只能响应一个绑定（比如只认 HTTP，不认 HTTPS），哪怕你配了两个 <endpoint></endpoint>。

• 常见错误现象：HTTPS 端点始终 404，HTTP 正常；或启用 mexHttpsBinding 后元数据地址返回 404
• 使用场景：生产环境通常需同时暴露 HTTP（内网调用）和 HTTPS（外网），此时必须设 multipleSiteBindingsEnabled="true"
• 兼容性注意：.NET Framework 4.0+ 支持该属性，旧版本只能靠 <service></service> 拆分成多个，或改用自托管
• 顺带一提：aspNetCompatibilityEnabled="true" 若开启，要求服务类加 [AspNetCompatibilityRequirements] 特性，否则启动即崩

web.config 里 <system.webserver></system.webserver> 的 handlers 和 modules 不能少

IIS 7+ 默认用集成管道，WCF 的 .svc 文件要靠 ServiceModel-4.0 handler 处理，漏配就会返回源码或 404。

• 常见错误现象：访问 http://host/MyService.svc 直接下载 .svc 文件，或提示 Handler "svc-Integrated-4.0" has a bad module "ManagedPipelineHandler"
• 使用场景：IIS 托管必加，尤其部署到 Server 2012+ 或 windows 10 IIS 10 时，<handlers></handlers> 里必须有 svc-Integrated-4.0（Framework 4.0+）或 svc-Integrated（3.5）
• 容易被忽略的点：<modules runallmanagedmodulesforallrequests="true"></modules> 不是可选——它让所有请求（包括静态资源）过 .NET 管道，否则 mex 元数据请求可能被静态文件模块截胡
• 验证方式：在 IIS 管理器 → 站点 → “处理程序映射”，确认 *.svc 绑定到了 ServiceModel 对应版本

事情说清了就结束。WCF 配置真正麻烦的从来不是语法，而是每个节点都强耦合、缺一不可，而且错误反馈往往隔了一层才冒出来。