企业官网建设流程全解析

简介：这是一套基于C#实现的ONVIF协议客户端工具源代码，面向安防监控、视频平台开发及物联网设备接入方向的开发者，尤其适合需要理解ONVIF接口调用流程的中高级程序员。工程覆盖设备发现、鉴权、参数获取与设置、用户信息管理、固件升级，以及视频流参数配置与RTSP流获取显示，并借助Live555完成流媒体解析，对使用其他语言分析ONVIF接口也有参考价值。资源包共约2000个文件，以1813个cs源文件为核心，辅以1141个c、530个h、199个cpp等底层实现，另有154个xaml界面文件、26个csproj工程文件及若干dll、xml配置，整体约31.69MB，结构完整便于编译调试。目前已有1409人学习下载，可作为二次开发与协议对接的实践参考。

1. 从零手搓 C# 版本 ONVIF 协议客户端工具：为什么我劝你先别急着写代码

如果你手里有一台网络摄像机，想用 C# 写个客户端去搜设备、拉 RTSP 地址、控制云台，那你大概率绕不开 ONVIF 协议。这个标题里的“C# 版本 ONVIF 协议客户端工具 源代码 VS 2015”，说白了就是一套用 C# 在 Visual Studio 2015 环境下编译运行的 ONVIF 客户端实现，能帮你完成设备发现、能力查询、媒体配置、PTZ 控制这几件事。我见过太多人一上来就搜“ONVIF 客户端源码”，下载下来发现编译不过、设备搜不到、RTSP 地址拿不到，最后卡在 SOAP 报文和 WS-Discovery 这两个黑匣子上。这篇笔记就是把我自己踩过的坑和能跑通的路径讲清楚，适合有 C# 基础、想快速对接 IPC 的开发者，也适合需要把 ONVIF 集成进自己平台的熟手做参数对照。

2. ONVIF 客户端到底在做什么：从设备发现到取流地址的完整链路

2.1 为什么不能直接 HTTP 请求设备 IP

ONVIF 不是普通的 REST 接口，它跑在 SOAP 1.2 之上，所有请求都是 POST 到设备的一个固定端点，比如http://192.168.1.64/onvif/device_service。你直接拿浏览器访问这个地址，设备可能返回 405 或者一段看不懂的 XML，因为 ONVIF 要求请求体必须是符合规范的 SOAP Envelope，并且带 WS-Security 头。更关键的是，设备发现阶段根本不知道 IP，得靠 WS-Discovery 组播去问“谁在线”。所以一个完整的 ONVIF 客户端至少包含两块：UDP 组播发现 + HTTP SOAP 调用。很多人只写了 SOAP 部分，结果设备搜不到，就以为协议有问题，其实是发现机制没做。

2.2 WS-Discovery 的组播地址和超时设置

WS-Discovery 的标准组播地址是239.255.255.250:3702，发送Probe消息后，在线设备会单播回复ProbeMatch，里面带XAddrs也就是设备服务地址。这里有个血泪经验：不同厂商的设备回复速度差异很大，有的 200ms 就回了，有的要 1.5 秒以上。如果你只等 1 秒就关掉 UDP 监听，就会漏设备。我一般把超时设到 3 秒，并且把收到的XAddrs去重后再做后续调用。另外，Windows 防火墙默认会拦 UDP 3702 的入站回复，调试时先确认防火墙规则，不然代码没问题却一台设备都搜不到。

2.3 SOAP 报文里必须带 WS-Security 吗

这取决于设备。大部分 IPC 在首次调用GetDeviceInformation或GetCapabilities时允许匿名，但一旦你要改配置或者调 PTZ，设备就会返回 401 并附带Security头要求。常见做法是：先匿名调GetCapabilities，拿到Media和PTZ的 XAddr，然后在后续请求里统一加UsernameToken。注意，ONVIF 的密码摘要用的是Base64(SHA1(nonce + created + password))，不是明文。VS 2015 里用System.Security.Cryptography.SHA1就能算，但要注意nonce是随机字节数组，created是 UTC 时间字符串，格式必须严格是yyyy-MM-ddTHH:mm:ss.fffZ，差一个字符设备就返回 400。

2.4 用 C# 发一个最小 SOAP 请求的代码骨架

下面这段代码在 VS 2015 下用 .NET Framework 4.5 就能跑，核心是构造HttpWebRequest并写入 SOAP Envelope。注意Content-Type必须是application/soap+xml; charset=utf-8，少个分号都可能被设备拒。

// 构造一个最小的 GetDeviceInformation SOAP 请求 string soapBody = @"<?xml version=""1.0"" encoding=""utf-8""?> <s:Envelope xmlns:s=""http://www.w3.org/2003/05/soap-envelope""> <s:Body xmlns:tds=""http://www.onvif.org/ver10/device/wsdl""> <tds:GetDeviceInformation/> </s:Body> </s:Envelope>"; byte[] bodyBytes = Encoding.UTF8.GetBytes(soapBody); HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://192.168.1.64/onvif/device_service"); request.Method = "POST"; request.ContentType = "application/soap+xml; charset=utf-8"; request.ContentLength = bodyBytes.Length; request.Timeout = 5000; // 超时设 5 秒，太短容易误判设备离线 using (Stream stream = request.GetRequestStream()) { stream.Write(bodyBytes, 0, bodyBytes.Length); } using (HttpWebResponse response = (HttpWebResponse)request.GetResponse()) using (StreamReader reader = new StreamReader(response.GetResponseStream())) { string result = reader.ReadToEnd(); Console.WriteLine(result); // 输出设备厂商、型号、固件版本 }

这段代码的逻辑很直接：把 SOAP 字符串转成字节数组，通过HttpWebRequestPOST 到设备服务地址，然后读回响应。参数上最需要注意的是ContentType和Timeout。ContentType如果写成text/xml，部分设备会直接返回 415。Timeout设 5 秒是折中值，局域网内通常 100ms 内就返回，但设备刚上电时可能响应慢。如果你要批量搜设备，建议把这段封装成方法，传入不同的 XAddr 复用。

2.5 从 GetCapabilities 到 GetStreamUri 的调用顺序

拿到设备信息后，下一步是调GetCapabilities，从返回的 XML 里解析出Media的 XAddr 和PTZ的 XAddr。然后调GetProfiles拿到媒体配置文件的 token，再调GetStreamUri传入 token 和StreamType（RTP-Unicast 或 RTP-Multicast），最终拿到 RTSP 地址。这个顺序不能乱，因为GetStreamUri必须带ProfileToken，而 token 来自GetProfiles。我见过有人直接拼 RTSP 地址，结果换个厂商设备就失效，就是因为没走标准流程。解析 XML 时建议用XDocument而不是XmlDocument，LINQ to XML 处理命名空间更顺手。

3. 在 VS 2015 里搭出可调试的 ONVIF 客户端工程

3.1 新建项目时选控制台还是 WinForm

如果你只是验证协议，控制台程序最省事，输出直接Console.WriteLine，不用处理 UI 线程。但如果你要做 PTZ 方向控制，WinForm 加几个按钮更直观。VS 2015 新建项目时选 “Windows 窗体应用” 或 “控制台应用”，目标框架选 .NET Framework 4.5 或 4.6，不要选 .NET Core，因为 ONVIF 客户端里用到的HttpWebRequest和SHA1在 .NET Core 早期版本里行为有差异，容易出玄学问题。另外，VS 2015 默认的 C# 版本是 6.0，支持字符串插值和 null 条件运算符，写起来比 5.0 舒服很多。

3.2 用 NuGet 装哪些包，哪些包其实不用装

很多人一搜 ONVIF 就去找现成的 NuGet 包，比如ONVIF.Client之类的。我的建议是：核心的 SOAP 调用自己写，因为第三方包往往封装太厚，设备返回的原始 XML 被吞掉，出问题没法排查。真正需要装的只有System.ServiceModel吗？其实不用，HttpWebRequest就够了。如果你要用XDocument，System.Xml.Linq是框架自带的。唯一可能需要的是Newtonsoft.Json，但 ONVIF 返回的是 XML，用不上。所以新建工程后，NuGet 里什么都不用装，直接写代码，减少依赖。

3.3 封装一个 OnvifClient 类的字段设计

我一般会建一个OnvifClient类，字段包括string deviceServiceUrl、string mediaServiceUrl、string ptzServiceUrl、string username、string password。构造函数传入设备 IP 和凭据，内部先调GetCapabilities填充三个 URL。这样后续调GetProfiles、GetStreamUri、PtzMove都直接复用字段，不用每次传 URL。注意deviceServiceUrl的格式是http://{ip}/onvif/device_service，但有些设备返回的XAddrs里带的是https，如果你没配证书，就得手动替换成http，否则请求会抛TrustFailure异常。

3.4 处理 SOAP 响应里的命名空间陷阱

ONVIF 的 XML 命名空间特别多，tds、trt、tt、tptz等等。用XDocument解析时，如果直接doc.Descendants("GetDeviceInformationResponse")是找不到的，因为元素名带命名空间。正确做法是doc.Descendants(XName.Get("GetDeviceInformationResponse", "http://www.onvif.org/ver10/device/wsdl"))。我一般会先把常用命名空间定义成XNamespace静态字段，比如static readonly XNamespace tds = "http://www.onvif.org/ver10/device/wsdl";，然后doc.Descendants(tds + "GetDeviceInformationResponse")。这样代码干净，也不容易写错。

3.5 调试时用 Fiddler 抓包看原始报文

VS 2015 调试时，如果设备返回 400 或 500，光看异常信息没用。我习惯开 Fiddler，让HttpWebRequest走代理。在代码里加request.Proxy = new WebProxy("127.0.0.1", 8888);，然后 Fiddler 里就能看到完整的 SOAP 请求和响应。重点看Security头里的Nonce和Created是否和设备要求的一致，以及Body里的元素顺序。ONVIF 对元素顺序有要求，比如GetStreamUri里ProfileToken必须在StreamSetup之前，顺序反了设备就报错。这个坑我踩过不止一次，抓包一看就明白。

4. 避坑与排查：设备搜不到、RTSP 拿不到、PTZ 没反应

4.1 组播搜不到设备，先查防火墙和网卡

现象：代码发了Probe，但一个ProbeMatch都没收到。原因通常是 Windows 防火墙拦了 UDP 3702 的入站，或者你的机器有多张网卡，组播包从错误的网卡发出去了。解决：在防火墙里给程序放行 UDP 3702 入站，或者在代码里绑定Socket到指定网卡的 IP。我一般会枚举NetworkInterface.GetAllNetworkInterfaces()，找到OperationalStatus.Up且不是回环的网卡，用它的 IP 来绑定组播。另外，有些交换机默认关闭 IGMP Snooping，组播包会被泛洪到所有端口，反而能收到，但这不是可靠做法。

4.2 调用 GetStreamUri 返回 400，多半是 ProfileToken 传错

现象：GetProfiles能返回一堆 token，但拿其中一个去调GetStreamUri就报 400。原因通常是 token 里带了特殊字符，比如Profile_1里的下划线在 XML 里没问题，但如果你手动拼接字符串时没做转义，或者把 token 前后的空格带进去了，设备就认不出来。解决：从GetProfiles的响应里用XDocument取token属性值时，用.Value.Trim()去空格，然后直接传给GetStreamUri的ProfileToken元素。另外，StreamSetup里的Stream必须是RTP-Unicast，Transport里的Protocol通常是RTSP，这两个值写错也会 400。

4.3 PTZ 控制返回 200 但镜头不动，检查 ContinuousMove 的 Velocity

现象：调ContinuousMove返回 200，但云台没反应。原因可能是Velocity里的PanTilt的x和y值范围不对。ONVIF 规范里x和y是 -1 到 1 的浮点数，但有些设备只认 -0.5 到 0.5，或者要求Zoom的x不能同时给。解决：先调GetConfigurationOptions看设备支持的 PTZ 配置，确认PanTilt和Zoom的最大最小值。然后发一个ContinuousMove，x=0.1, y=0.1，看镜头是否缓慢移动。如果还不动，检查ProfileToken是否和 PTZ 配置绑定，有些设备要求 PTZ 的 token 必须和媒体 profile 的 token 一致。

4.4 密码里带特殊字符导致 WS-Security 摘要算错

现象：用户名密码明明是对的，但设备一直返回 401。原因：ONVIF 的密码摘要计算里，password是直接拼在nonce和created后面的，如果你的密码里有&、<、>这些字符，在 XML 里需要转义，但摘要计算时用的是原始密码，不是转义后的。解决：在构造PasswordText时，用SecurityElement.Escape(password)做 XML 转义，但计算 SHA1 时用原始password字符串。这个坑很隐蔽，因为抓包看 XML 是对的，但摘要就是不对。我一般会在代码里单独写一个ComputePasswordDigest方法，传入原始密码，避免混淆。

4.5 设备返回的 XAddrs 是 IPv6 地址，HttpWebRequest 不认

现象：WS-Discovery 收到的XAddrs是http://[fe80::1]/onvif/device_service这种 IPv6 格式，直接丢给HttpWebRequest会抛UriFormatException。原因：部分设备同时支持 IPv4 和 IPv6，组播回复里可能带 IPv6 地址。解决：在解析XAddrs时，用Uri.TryCreate判断，如果是 IPv6 且你的网络环境没有 IPv6 路由，就跳过这个地址，或者手动把设备 IP 替换成 IPv4 地址。更稳妥的做法是，在发Probe时指定IPv4的组播地址，减少收到 IPv6 回复的概率。

5. 进阶技巧：把 ONVIF 客户端做成可复用的库

5.1 用接口隔离设备差异，方便换厂商

不同厂商的 ONVIF 实现有细微差别，比如某家设备GetCapabilities返回的MediaXAddr 带端口号，另一家不带。如果你把调用逻辑写死在OnvifClient里，换设备就要改代码。我的做法是定义一个IOnvifDevice接口，包含GetDeviceInfo、GetProfiles、GetStreamUri、PtzMove等方法，然后针对不同厂商写VendorAOnvifDevice、VendorBOnvifDevice实现类。这样上层业务代码只依赖接口，新增厂商时只加一个实现类，不用动原有逻辑。VS 2015 里建类库项目，把接口和实现放进去，主程序引用即可。

5.2 把 SOAP 请求模板抽成资源文件

SOAP 请求的 XML 模板很长，如果直接写在 C# 字符串里，改一个参数就要重新编译。我一般把模板放到.xml文件里，用EmbeddedResource嵌入程序集，运行时用Assembly.GetManifestResourceStream读取，然后替换占位符比如{ProfileToken}、{Username}。这样调整报文格式不用改代码，也方便做多语言。注意 VS 2015 里设置文件属性时，生成操作要选“嵌入的资源”，否则读不到。

5.3 用异步方法避免 UI 卡死

WinForm 里如果同步调HttpWebRequest，界面会卡住。VS 2015 支持async/await，把GetResponse换成GetResponseAsync，然后await一下就行。但要注意，HttpWebRequest的异步方法在 .NET 4.5 里已经可用，不需要额外装包。我一般把OnvifClient的所有公开方法都写成async Task<T>，这样在按钮事件里await client.GetStreamUriAsync()，界面就不会假死。另外，Timeout在异步模式下依然有效，但ReadWriteTimeout也要设，否则读响应流时可能无限等待。

5.4 一个验证客户端是否正常的检查清单

写完代码后，别急着接业务。按这个清单过一遍：第一，用Probe能搜到至少一台设备，并且XAddrs能解析成有效 URL。第二，匿名调GetDeviceInformation能返回厂商和型号。第三，带用户名密码调GetCapabilities能拿到Media和PTZ的 XAddr。第四，GetProfiles返回的 token 数量大于 0。第五，GetStreamUri返回的 RTSP 地址用 VLC 能播放。第六，ContinuousMove发x=0.1后镜头有动作，再发Stop能停住。这六步都过了，说明客户端基本可用。如果哪一步卡住，回到第 4 章对应的小节排查。

5.5 我自己的习惯：先抓包再写代码

最后说个我自己的习惯。每次对接新厂商的设备，我不会先写 C# 代码，而是先用一个通用的 SOAP 调试工具（比如 Postman 配好 SOAP 模板）手动发几个请求，把GetCapabilities、GetProfiles、GetStreamUri的原始响应都抓下来，确认设备返回的 XML 结构和我预期的一致。然后再打开 VS 2015 写代码，把抓到的响应作为单元测试的输入。这样能避免“代码写完了才发现设备不按标准返回”的翻车。ONVIF 协议虽然标准，但厂商实现总有差异，先抓包再写代码，能省下大量调试时间。希望帮到你。

本文还有配套的精品资源，点击获取