企业官网建设流程全解析

1. 老接口新任务：先想清楚用什么技术栈

前阵子被拉去对接一个运行了七八年的业务系统，对方技术负责人甩过来一个以.asmx结尾的地址，外加一句“接口就这个，你调一下”。打开浏览器访问，页面上赫然列着五六个方法，点进去还能看到 SOAP 1.1、SOAP 1.2、HTTP POST 三套请求示例。这套东西就是典型的 C#/.NET WebService，用.NET Framework里的 ASMX 技术栈写出来的。它不属于“新技术”，但在大量存量系统、跨语言对接、以及对标准化要求较高的行业软件里，你依然会隔三差五撞上它，所以把C#/.NET WebService 的一步步创建使用及访问验证这套流程走通，是很实用的一项手艺。

这篇内容面向几类人：一是手头有个老接口要维护或者要照着做一个同款的人；二是需要给外部提供一套跨语言、跨平台都能调的接口，考虑过 WebService 但没落地过的人；三是学过 WCF 或 WebAPI，但看到 WSDL、SOAPAction 这些词就发懵的人。我会从“为什么还选它”讲起，把服务端怎么建、契约怎么写、配置怎么调、客户端三种调用姿势、访问验证怎么做、踩了什么坑，一步步摊开讲。代码都是能直接跑的，配置也是我实际用过的，不玩虚的。

1.1 需求长什么样，决定了你该选哪条路

先别急着开 Visual Studio。WebService 这个东西，选型选错，后面全是返工。我见过太多人一上来就建一个 ASMX 项目，做完发现目标服务器只装了.NET 6运行环境，根本跑不起来，白干。所以第一步是把需求里的三个变量抠清楚：运行环境是什么、调用方是什么、要不要长期演进。

运行环境这一条最关键。ASMX 只能跑在 Windows + IIS +.NET Framework（典型是 4.6.2 到 4.8）这套组合上，如果你的服务端是 Linux 容器，那就直接排除它，去看 CoreWCF 或者干脆用 REST。调用方是第二个变量，如果对面是 Java、Python、PHP，或者是一些工业软件、财务软件，它们对 SOAP 的支持往往比对 REST 更成熟，这就是 WebService 的主场。第三个变量是演进预期，如果这套接口两三年内就要被新平台替掉，只是过渡用，那就没必要上重型框架，ASMX 反而是成本最低的。

我这次的需求很典型：内网环境，Windows Server，调用方是一个用 Java 写的中间件和一个第三方报表工具，两边都要求提供 WSDL，并且希望有强类型契约。这种情况下 ASMX 是最省事的，一天就能把骨架搭起来，联调成本也低。反过来说，如果调用方全是自家前端，或者要做高频短连接、大文件上传，那这套东西就不合适了，SOAP 的 XML 信封开销在那种场景下就是纯浪费。

注意：不要因为“技术老旧”就否定它，也不要因为“公司规定”就硬上。判断标准只有一个——调用方能不能稳定消费，运维侧能不能稳定托管。

1.2 ASMX、WCF、CoreWCF 三条路的能力对照

同样是“WebService”，在 .NET 生态里至少有三条实现路径，能力差别不小，选错了迁移成本会很高。我整理了一张对照表，是我自己在几个项目里踩完坑之后总结的，比官方文档更贴实际使用场景。

这张表里最容易被忽略的是最后一行。ASMX 的定位就是“简单、够用、互操作好”，它没打算做成一个全能通信框架，所以不要指望它去做双向回调、消息队列、事务传播这些事。WCF 当年是想解决这些问题的，但配置复杂度劝退了很多人，一个basicHttpBinding和wsHttpBinding的区别就能卡住新人半天。CoreWCF 是官方社区方案，路线是对的，但目前对某些扩展点的支持还不如老 WCF 完整，上之前最好先做一个小 Demo 验证关键特性。

1.3 开发环境与工具清单

环境这块没什么花活，但版本对不上会浪费很多时间。我这次用的是 Visual Studio 2022 社区版，安装了“.NET Framework 4.8 开发工具”和“ASP.NET 和 Web 开发”两个工作负载。如果你机器上只装了 .NET SDK 而没装 .NET Framework 的目标包，新建项目列表里是看不到“ASP.NET Web 应用程序(.NET Framework)”这个模板的，这是最常见的“模板找不到”原因。

工具方面我准备了四样。第一是浏览器，用来直接看.asmx的测试页和 WSDL，最原始的调试手段往往最好用。第二是 SoapUI 或者 Postman，Postman 现在对 SOAP 的支持也够用，手工改报文很方便。第三是wsdl.exe和dotnet-svcutil，分别在 .NET Framework 和 .NET Core 侧生成代理类。第四是 Windows PowerShell 5.1，它的New-WebServiceProxy命令在快速验证时简直是神器，一行命令就能把整个服务代理出来。

提示：PowerShell 7（pwsh）不包含New-WebServiceProxy，做快速验证时请开 Windows PowerShell 5.1，这个差异会让人怀疑人生。

还需要留意的是端口。IIS Express 默认会随机分配端口，项目一多很容易记混。我习惯在项目属性的“Web”页里把项目 URL 固定成一个段位，比如http://localhost:52110/，后面所有客户端配置、脚本里的地址都用这一个，减少变量。

2. 服务端从零创建：一个能跑起来的 WebService

环境齐了就可以动手。这一节我按真实操作顺序走一遍，从建项目到能拉到 WSDL，中间每个决策点都会说清楚为什么这么做。别小看这一步，很多后续的诡异问题，根源都在创建阶段的一两个配置上。

2.1 建项目、定命名空间，别留 tempuri.org

新建项目，选“ASP.NET Web 应用程序(.NET Framework)”，框架选 4.8，模板选“空”就行，别选 MVC 或 Web Forms，那些会带一堆用不上的引用，反而干扰排查。项目建好后，右键项目 → 添加 → 新建项 → 找到“Web 服务(ASMX)”，命名为OrderService.asmx。VS 会自动生成一个.asmx文件和一个同名的.cs后台文件，里面已经有一个HelloWorld示例方法。

生成的代码第一行通常是[WebService(Namespace = "http://tempuri.org/")]，这个命名空间必须改，没有例外。tempuri.org是微软给临时演示用的占位符，如果你不改，所有用这套模板做出来的服务命名空间都一样，一旦同一个客户端引用了两个不同厂商的服务，代理类里的类型就会撞名，编译报“类型已存在”的错。我一般用公司内部约定的反向域名风格，比如http://services.example.org/order，这里的 example 是保留域名，实际项目里换成自己的域名规则即可。

using System; using System.Web.Services; using System.Web.Services.Protocols; namespace Demo.OrderApi { [WebService(Namespace = "http://services.example.org/order", Description = "订单查询与状态同步服务")] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] [System.ComponentModel.ToolboxItem(false)] public class OrderService : System.Web.Services.WebService { [WebMethod(Description = "返回服务健康状态，用于探活")] public string Ping() { return "OK"; } } }

[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]这一行是模板自带的，作用是声明服务符合 WS-I Basic Profile 1.1，说白了就是告诉外界“我遵守 SOAP 的基本互操作约定”。留着它是好事，能提升和 Java、Python 客户端的兼容性，但如果你的方法里用了一些它不支持的写法（比如某些 RPC 编码风格），可能会报一致性校验失败，那时候再考虑去掉。

2.2 用实体类和特性把契约写清楚

契约就是“对外承诺的形状”，包括方法名、参数名、参数类型、返回值类型。ASMX 靠公开的[WebMethod]方法和公开的实体类来自动生成 WSDL，所以你写的每一个public成员，最终都会变成对方看到的接口文档。这里的原则是：方法要少而清晰，参数和返回值一律用强类型实体，不要用object、DataTable这类模糊类型。

[Serializable] public class OrderQuery { public string OrderNo { get; set; } public string CustomerCode { get; set; } } [Serializable] public class OrderResult { public bool Success { get; set; } public string Message { get; set; } public string OrderNo { get; set; } public decimal Amount { get; set; } public DateTime CreatedAt { get; set; } public OrderItem[] Items { get; set; } } [Serializable] public class OrderItem { public string Sku { get; set; } public int Qty { get; set; } public decimal Price { get; set; } }

为什么强调强类型？因为 SOAP 的互操作本质是 XML Schema 的互操作。你返回一个DataTable，WSDL 里会出现一个结构复杂、命名晦涩的schema段，Java 那边生成出来的对象往往是一堆嵌套的anyType，对方开发同学会当场崩溃。而强类型实体生成的 XSD 是干净的元素序列，任何语言都能映射成本地对象。

方法定义也一样，参数能用实体包起来就包起来，别一个方法挂七八个基础类型参数。因为一旦后续要加一个可选参数，你就得改方法签名，所有客户端都得重新生成代理，这是很痛的事。用一个查询实体作为入参，以后加字段就是新增属性，老客户端不传该字段就是默认值，兼容性好得多。

[WebMethod(Description = "按订单号查询订单详情", CacheDuration = 0)] public OrderResult GetOrder(OrderQuery query) { if (query == null || string.IsNullOrWhiteSpace(query.OrderNo)) { throw new ArgumentException("订单号不能为空"); } // 这里接实际的数据访问层，示例里直接构造 return new OrderResult { Success = true, Message = "OK", OrderNo = query.OrderNo, Amount = 128.50m, CreatedAt = DateTime.Now, Items = new[] { new OrderItem { Sku = "SKU-001", Qty = 2, Price = 64.25m } } }; }

CacheDuration这个属性值得单独提一句。默认是 0，表示不缓存。如果你设置成 60，同一个参数在 60 秒内的重复调用会直接返回缓存结果，不再执行方法体。听起来很美好，但在涉及实时数据的查询接口上千万别开，我见过有人为了“优化性能”随手设了个 300，结果运营那边改了数据五分钟不生效，排查了半天才想起来是缓存。只在明确的静态字典类接口上用它是安全的。

2.3 web.config 里必须改的几处配置

代码写完了不代表能跑，web.config才是真正决定行为的地方。默认模板生成的配置基本是空壳，下面这几处是我每次都会调整的。

<configuration> <system.web> <compilation debug="true" targetFramework="4.8" /> <httpRuntime targetFramework="4.8" maxRequestLength="10240" executionTimeout="120" /> <webServices> <protocols> <add name="HttpSoap" /> <add name="Documentation" /> </protocols> </webServices> </system.web> <system.webServer> <security> <requestFiltering> <requestLimits maxAllowedContentLength="10485760" /> </requestFiltering> </security> </system.webServer> </configuration>

先解释maxRequestLength和executionTimeout这两个参数怎么算。maxRequestLength的单位是千字节，10240 就是 10MB，这是 ASP.NET 层面的请求体上限；executionTimeout单位是秒，120 表示单次请求最长执行两分钟，超时会被强行中断。这两个值要和业务体量匹配：如果接口是传一批明细（比如几百条记录），10MB 通常够；如果涉及图片或者附件，得往上调。但调大之前先想清楚，大报文在 SOAP 里会被完整读进内存解析，机器内存不够时会直接 OutOfMemory，这不是配置能救的。

<system.webServer>里的maxAllowedContentLength是 IIS 层面的限制，单位是字节，10485760 也是 10MB。这两个限制是串联的，任何一个超了都会返回 404.13 之类的错误，所以两个值必须一起调大，只改一个会出现“明明改了配置还是传不上去”的怪现象。这也是我踩过最经典的一个坑。

<webServices><protocols>这一段控制哪些协议对外暴露。HttpSoap是 SOAP 调用，必须开。Documentation控制的是那个自动生成的说明页面和 WSDL 端点，开发阶段必须开，否则浏览器访问.asmx会看到“测试窗体只能用于来自本地计算机的请求”或者干脆 404。上线时是否关闭，取决于你的安全策略，后面第 6 节会详细说。

注意：<webServices>节点在web.config里的位置有讲究，它必须出现在system.web下正确的位置，如果加错地方会报“无法识别的配置节”或者“配置节顺序错误”。最稳妥的做法是在httpRuntime之后插入。

2.4 启动后先拉 WSDL 自检

按 F5 启动，浏览器会自动打开.asmx页面。这时候先别急着测业务方法，做三件自检。第一，页面上能不能看到你写的方法列表，方法名、参数、说明都在不在。第二，点页面上的“服务说明”链接，也就是?wsdl那个地址，浏览器能不能正常返回一大段 XML。第三，把这段 XML 保存成service.wsdl，用文本编辑器搜一下里面的targetNamespace，确认是不是你在[WebService]里写的那个值。

这三步看着简单，但能提前发现大部分问题。方法列表里少了一个，多半是方法忘了加[WebMethod]或者被标成了private；WSDL 打不开，通常是Documentation协议没开或者路由被拦截；targetNamespace还是tempuri.org，说明特性写错位置或者被覆盖了。WSDL 是整个 SOAP 世界的“身份证”，它不对，后面全错，所以这一步值得花两分钟确认。

3. 让它经得起真实调用：序列化、异常、日志

能跑通HelloWorld只是万里长征第一步。真正上线后遇到的麻烦，八成集中在三件事上：类型序列化不符合预期、异常返回客户端看不懂、超时和并发把服务拖垮。这一节就是我这些年被这三点教育出来的经验。

3.1 参数与返回值序列化的三个坑

SOAP 的序列化规则比 JSON 严格得多，而且很多行为是隐式的，不写清楚就会出问题。第一个坑是DateTime。ASMX 默认按本地时区序列化，输出格式形如2024-01-01T10:00:00+08:00，但某些客户端在解析时会忽略时区偏移，直接按本地时间理解，结果就是跨时区对接时整整差八个小时。我的处理习惯是：接口层一律用字符串传时间，格式固定yyyy-MM-dd HH:mm:ss，在服务内部转换；如果必须用DateTime，就统一约定用 UTC 并在文档里写死。

第二个坑是decimal精度。XML Schema 里decimal是任意精度，但不同语言的反序列化实现差异很大，Java 侧可能映射成BigDecimal，PHP 侧可能变成浮点数而丢精度。涉及金额的场景，我通常再加一个字符串字段做冗余，比如Amount和AmountText两个属性同时返回，让对方选一个可靠的用。这个做法看起来笨，但联调效率极高。

第三个坑是空值和数组。ASMX 默认会把null字符串序列化成空元素，把空数组序列化成<Items />，某些客户端看到空元素会抛“无法将空字符串转换为数值”的异常。解决办法是在实体属性上控制，要么给默认值，要么用[XmlElement(IsNullable = true)]明确声明可为空，让 WSDL 里体现出来。数组为空时返回长度 0 的数组而不是null，这条几乎是我的硬性守则，能省掉对面一半的空指针问题。

[Serializable] public class OrderResult { public bool Success { get; set; } public string Message { get; set; } public string AmountText { get; set; } // 金额字符串，规避精度问题 public OrderItem[] Items { get; set; } = new OrderItem[0]; // 永远不返回 null }

3.2 异常怎么抛，客户端才看得懂

默认情况下，[WebMethod]里抛出的未处理异常，会被框架包装成 HTTP 500，并返回一个 SOAP Fault，但 Fault 里的detail往往只有System.ArgumentNullException这样的英文类型名，对方开发看到这个只能干瞪眼。更糟的是，有些客户端库遇到 500 会直接抛底层网络异常，根本拿不到错误信息。所以异常必须主动包装，让错误语义进入 SOAP Fault 的标准结构里。

using System.Web.Services.Protocols; using System.Xml; [WebMethod(Description = "按订单号查询订单详情")] public OrderResult GetOrder(OrderQuery query) { try { if (query == null || string.IsNullOrWhiteSpace(query.OrderNo)) { throw new SoapException( "订单号不能为空", SoapException.ClientFaultCode, Context.Request.Url.ToString()); } // 业务处理 return BuildResult(query); } catch (SoapException) { throw; // 已经是标准 Fault，原样抛出 } catch (Exception ex) { // 记录完整堆栈到日志，对外只暴露安全的信息 Logger.Error("GetOrder failed", ex); throw new SoapException( "服务处理异常，请联系管理员并提供时间点", SoapException.ServerFaultCode, Context.Request.Url.ToString()); } }

这里的关键是SoapException.ClientFaultCode和ServerFaultCode的区分。前者表示“你传的参数有问题”，属于调用方的责任；后者表示“我这边出错了”，属于服务方的责任。客户端可以据此决定是重试还是提示用户改参数。这个区分在自动化运维里特别有用，监控系统可以只对 ServerFault 告警，避免被参数错误刷屏。

如果想返回更结构化的错误码，SoapException还有一个带XmlNode数组的重载，可以把业务错误码塞进detail节点里。不过这个用法对客户端要求稍高，需要它们去解析 detail。我的建议是：简单场景用消息文本就够，复杂场景再上 detail，别一上来就搞得太重。

3.3 超时、大报文与并发设置

超时是双向的：服务端有executionTimeout，客户端也有自己的超时。两边任何一边设得太小都会出问题，而且报错信息往往不指向真正原因。我的经验是把服务端超时设成客户端超时的 1.5 倍左右，给网络抖动和排队留出余量。比如客户端设 60 秒，服务端就设 90 到 120 秒。

并发方面，ASMX 跑在 IIS 上，请求由工作线程池处理。默认线程池配置应对几十个并发一般没问题，但如果接口里有同步阻塞的数据库查询或者外部 HTTP 调用，线程会被长时间占用，高并发下就会出现排队。判断方法很直接：看 IIS 的性能计数器里Requests Queued是不是持续大于 0，如果是，说明线程不够用了。

真正要解决这个问题，靠调minWorkerThreads只是治标，根源还是接口内部的耗时操作。我的做法是把耗时逻辑拆成“立即返回受理结果 + 异步处理”，接口只做参数校验和任务入队，把结果通过另一个查询接口暴露出去。这套模式在 SOAP 里同样适用，对方先拿到一个任务号，隔几秒来轮询结果，用户体验和系统稳定性都好得多。

4. 客户端访问：代理类、HttpClient、原始SOAP三种姿势

服务端能跑起来、能自检通过，接下来就是怎么调。WebService 的好处是调用方式很多，好处也是坏处——方式太多，新手容易挑错。我把三种主流方式都走一遍，每种都说明适用场景和实际坑点。

4.1 wsdl.exe / dotnet-svcutil 生成代理

最传统也最省心的方式，用工具根据 WSDL 生成强类型代理类，然后像调本地方法一样调远程接口。.NET Framework项目里用wsdl.exe，打开“开发者命令提示符”，执行：

wsdl.exe /language:cs /out:Proxies/OrderServiceProxy.cs /namespace:Demo.Client.Proxy ^ http://localhost:52110/OrderService.asmx?wsdl

生成的文件里会有一个继承自SoapHttpClientProtocol的类，名字通常是OrderService，还有你定义的所有实体类。把它拖进项目，配置一下 URL 就能用：

var client = new Demo.Client.Proxy.OrderService { Url = "http://localhost:52110/OrderService.asmx", Timeout = 60000 // 毫秒 }; try { var result = client.GetOrder(new OrderQuery { OrderNo = "SO20240101" }); Console.WriteLine($"{result.Success} {result.AmountText}"); } catch (SoapException ex) { Console.WriteLine($"业务异常：{ex.Message}"); } catch (WebException ex) { Console.WriteLine($"网络异常：{ex.Status}"); }

Url属性一定要显式赋值，别依赖 WSDL 里写死的地址。因为开发环境是localhost:52110，测试环境和生产环境是另外的域名，如果靠默认值，发布后就会去调本机地址，这个错误非常隐蔽，日志里只会看到连接被拒绝。

.NET Core/.NET 6+的项目用dotnet-svcutil：

dotnet tool install --global dotnet-svcutil dotnet-svcutil http://localhost:52110/OrderService.asmx?wsdl ^ --namespace "*,Demo.Client.Proxy" --outputDir ./Proxies

注意--namespace "*,Demo.Client.Proxy"这个参数，星号表示“所有命名空间都映射到这个前缀下”。不加的话，生成出来的类型会散落在各种奇怪的命名空间里，用起来很别扭。这个工具生成的是基于HttpClient的代理，行为和老代理略有差异，尤其是超时和连接复用的处理，建议在联调环境多测几轮。

4.2 HttpClient 直发 SOAP 报文

有时候你不想生成代理，比如只调一个方法、或者项目里不允许引入额外代码、或者你想完全掌控报文内容做特殊处理。这时候可以直接用HttpClient发一段 SOAP 信封过去。这种方式最“裸”，也最能让你理解 SOAP 到底是怎么回事。

var envelope = @"<?xml version=""1.0"" encoding=""utf-8""?> <soap:Envelope xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xmlns:xsd=""http://www.w3.org/2001/XMLSchema"" xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/""> <soap:Body> <GetOrder xmlns=""http://services.example.org/order""> <query> <OrderNo>SO20240101</OrderNo> </query> </GetOrder> </soap:Body> </soap:Envelope>"; using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) }; var content = new StringContent(envelope, Encoding.UTF8, "text/xml"); content.Headers.Add("SOAPAction", "\"http://services.example.org/order/GetOrder\""); var resp = await http.PostAsync("http://localhost:52110/OrderService.asmx", content); var body = await resp.Content.ReadAsStringAsync(); Console.WriteLine(body);

这段代码里有三个细节，任何一个错了都会 500。

第一是SOAPAction头，它的值外面要套一层双引号，这是 SOAP 1.1 的规范要求，很多手写代码漏了引号就报“服务器未能识别 HTTP 头 SOAPAction 的值”。

第二是Content-Type必须是text/xml; charset=utf-8，这是 SOAP 1.1 的标准；如果服务端声明支持 SOAP 1.2，则要用application/soap+xml，而且 SOAPAction 不再是独立头部，而是塞进 Content-Type 的action参数里，这两套规则别混。

第三是信封体里GetOrder元素的xmlns，必须和 WSDL 里的命名空间一致，也就是你在[WebService]里定义的那个值。这个错最容易犯，因为soap:Envelope本身自带命名空间，新手容易以为下面也自动继承了。

4.3 三种方式的适用场景对比

我自己的习惯是：正式客户端用代理类，因为类型安全、IDE 提示友好，维护成本低；临时验证和写自动化脚本用 PowerShell 或者 HttpClient；遇到“为什么对方能调我不能调”的扯皮场景，就用 HttpClient 手写一个最小报文，跟对方对比，差异一目了然。

5. 访问验证：手工一遍、脚本一遍、上线前再一遍

接口写完不等于交付完成，验证才是。我一般把验证分成三层：手工验证确认基本功能，脚本验证确认可重复执行，上线前清单确认环境和边界。这三层做完，心里才有底。

5.1 手工验证的固定动作

手工验证我有一套固定动作，顺序固定，每次都不跳步。第一步，浏览器访问?wsdl，确认能返回 XML，这一步验证的是元数据端点。第二步，用 Postman 建一个 POST 请求，按 4.2 的报文结构手写一遍，确认返回的soap:Body里是正常结果，这一步验证的是 SOAP 通道。

第三步，故意传一个错误参数，比如空订单号，观察返回的是不是带faultcode的 SOAP Fault，消息是不是你写的那句中文提示。这一步特别重要，因为很多异常处理代码在正常流程下根本不会触发，只有故意走一遍才知道写没写对。第四步，传一个业务上不存在的订单号，看返回的Success是不是false而不是抛异常，这是“业务失败”和“系统失败”的分界线，必须验证清楚。

<!-- 错误参数时应该拿到的响应，重点看 faultcode 和 faultstring --> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <soap:Fault> <faultcode>soap:Client</faultcode> <faultstring>订单号不能为空</faultstring> </soap:Fault> </soap:Body> </soap:Envelope>

第四步之后我还会加一个“大报文”测试，构造一个包含几十条明细的查询报文，确认在maxRequestLength上限之内能正常返回，超过上限时返回的是明确的错误而不是白屏。这个测试能提前发现配置没同步调整的问题。

5.2 PowerShell 一把梭做回归

手工验证确认没问题之后，我会写一个 PowerShell 脚本把主要用例跑一遍，每次改代码或者换环境都跑一次。这个脚本很土但很有效，二十行代码能覆盖 80% 的回归风险。

$uri = "http://localhost:52110/OrderService.asmx?wsdl" try { $svc = New-WebServiceProxy -Uri $uri -Namespace "OrderProxy" -Class "OrderService" } catch { Write-Host "WSDL 拉取失败: $($_.Exception.Message)" -ForegroundColor Red exit 1 } $caseList = @( @{ Name = "正常查询"; OrderNo = "SO20240101" }, @{ Name = "空订单号"; OrderNo = "" }, @{ Name = "不存在订单"; OrderNo = "SO_NOT_EXIST" } ) foreach ($c in $caseList) { $q = New-Object OrderProxy.OrderQuery $q.OrderNo = $c.OrderNo try { $r = $svc.GetOrder($q) Write-Host ("[{0}] Success={1} Msg={2}" -f $c.Name, $r.Success, $r.Message) } catch { Write-Host ("[{0}] 抛出异常: {1}" -f $c.Name, $_.Exception.Message) -ForegroundColor Yellow } }

用New-WebServiceProxy的好处是它会自动根据 WSDL 生成代理类，连实体类都给你造好，New-Object OrderProxy.OrderQuery这种写法就能直接构造参数。-Namespace参数随便起个名字，但每次脚本里要用同一个，否则类型找不到。

注意：这个命令依赖 .NET Framework 的System.Web.Services，所以必须在 Windows PowerShell 5.1 下跑。如果你在 CI 里用 pwsh 7，会报“无法识别 New-WebServiceProxy”，换成Invoke-WebRequest手写报文即可。

5.3 上线前验证清单

上线前的验证和开发阶段的验证侧重点不一样，开发阶段关心“功能对不对”，上线前关心“环境变了还对不对”。我列了一张清单，每次发布前逐项打勾。

这张表里我最看重“客户端地址”和“日志可查”两项。前者是因为它出错后表现极其诡异——接口明明通了，数据却是旧的，因为调的是开发库；后者是因为 SOAP 的问题排查成本远高于 REST，没有日志基本靠猜。

6. 踩坑实录与排查速查表

这一节是纯干货，全是我在实际项目里撞过的墙。WebService 的报错信息普遍不友好，很多错误码指向的原因和实际原因差着十万八千里，有一张速查表能省下大量搜索时间。

6.1 服务端典型报错

先看服务端最常见的几个报错。服务器未能识别 HTTP 头 SOAPAction 的值这个几乎人人都会遇到，九成是 SOAPAction 缺少引号，或者命名空间和 WSDL 不匹配。检查方法很简单：把 WSDL 里soap:operation soapAction="..."那个值原样复制过来，包括引号。

无法识别请求元素或者请求格式无法识别，通常是信封结构写错了。比如soap:Body里漏了命名空间声明，或者把参数直接摊在 Body 下而没包在方法元素里。SOAP 的规矩是方法名是一个元素，参数是它的子元素，这个层级不能乱。

测试窗体只能用于来自本地计算机的请求这个提示，是Documentation协议只在本地可用的默认行为。开发阶段遇到它，说明你从另一台机器访问了.asmx页面，属于正常安全限制，不是 bug。如果确实需要远程看说明页，在web.config的webServices节点里显式加<add name="Documentation" />，但要清楚这意味着 WSDL 对外完全暴露。

404.13 - 内容长度超过限制是 IIS 层面的请求体超限，去改maxAllowedContentLength，别忘了同时改maxRequestLength。这两个报错长得像但配置位置不同，一个在system.web，一个在system.webServer。

6.2 部署到 IIS 后的额外变量

开发机用 IIS Express 一切正常，部署到 IIS 就出问题，这是最常见的“环境差异”。第一个变量是应用程序池。ASMX 必须跑在.NET CLR 版本为 v4.0 的池里，托管管道模式选“集成”。选“经典”有时也能跑，但某些模块行为不同，容易出奇怪问题，能选集成就别选经典。

第二个变量是身份验证。IIS 默认可能开了匿名，但你的代码里如果用了Context.User.Identity.Name做审计，就会拿到空值。需要在 IIS 里开 Windows 身份验证，同时在web.config里配<authentication mode="Windows" />和<identity impersonate="true" />。这两处少一个都拿不到用户名，而且不会报错，只是静默返回空串，非常难查。

第三个变量是.NET Framework版本和应用程序池的映射。服务器上装了 4.8，但池子指向的是 v2.0，一访问就报“未能加载文件或程序集”。改池子版本后记得回收，有时候还得重启 IIS，因为旧的编译缓存不会自动清。

第四个变量是防火墙和端口。内网服务器往往只开 80 或 443，如果你在项目里固定了52110这种端口，部署后外部根本连不上。我的习惯是发布前把项目 URL 改成相对路径，实际地址由 IIS 站点绑定决定，减少环境耦合。

6.3 安全加固的几条底线

.asmx那个自动生成的说明页，在开发阶段是神器，在生产环境就是信息泄露的入口——它把方法名、参数名、甚至注释里的业务描述全暴露了。上线前我一般会把Documentation协议关掉，只在需要对方生成代理时临时开启，生成完立刻关闭。

<!-- 生产环境：只保留 SOAP，关闭说明页 --> <webServices> <protocols> <add name="HttpSoap" /> </protocols> </webServices>

第二条底线是不要在参数里传敏感信息。SOAP 报文是明文 XML，除非你上了 HTTPS，否则链路中间的任何抓包工具都能看到完整内容。这不是 WebService 的锅，是 HTTP 的锅，但很多人对 SOAP 有一种莫名的“企业级安全感”，反而忘了加密这件事。内网也一样，内网不等于可信网络。

第三条是输入校验必须做在服务端。很多人以为强类型就安全了，其实不是——字符串字段可以传任意长度，数字字段可以传负数，枚举字段可以传未定义值。我习惯在每个[WebMethod]入口做一次统一的参数校验，长度、范围、格式都过一遍，超限直接抛SoapException。

第四条是限制方法暴露面。只把真正需要对外的方法标[WebMethod]，内部用的辅助方法一律private或者干脆放在别的类里。我见过有人图省事把整个业务层类都标了公开方法，结果 WSDL 里冒出来几十个接口，其中一半是调试用的，等于把自己家的后门挂在门口。

最后分享一个我在实际项目里养成的习惯：每加一个[WebMethod]，就在验证脚本里同步加一个用例。看着麻烦，但半年后你回头改这个接口时，会感谢当初那个多写了十行的自己。SOAP 这套东西的调试成本高，靠人肉记忆去回归是不现实的，脚本才是最可靠的备忘录。