简介C#版本的ONVIF协议客户端工具源码基于VS2015开发面向需要对接IPC/NVR等ONVIF兼容设备的开发者。工具覆盖设备发现、设备鉴权、参数获取与设置、用户信息管理、固件升级、视频流参数配置等常见环节并集成Live555对RTSP流进行解析与显示可帮助理解ONVIF协议交互流程及视频拉流实现方式。压缩包共2000个文件其中C#源文件cs约1800余个C/C库文件c/h/cpp覆盖Live555等底层依赖XAML文件提供WPF界面布局整体包体31.69MB目录结构完整。目前已有1406人学习浏览适用于需要移植或参考ONVIF接口实现的C#开发者也适合其他语言开发者借阅接口调用逻辑。该工程可直接在VS2015中编译调试也可作为二次开发基础框架。其中还包含FFmpeg相关C源码及大量H.264测试向量可辅助深入理解视频编解码与容器解析细节。 搞安防集成的兄弟应该都有这个体会今天接海康明天接大华后天又来一批杂牌枪机每家SDK一套写法光在代码里做兼容层就够喝一壶的。ONVIF协议就是用来解决这个问题的它是安防设备之间的“通用语言”。这个C#版本的ONVIF客户端工具是我在项目里一直维护的基础模块基于VS 2015工程构建能够完成设备自动发现、基本信息读取、Profile查询、RTSP取流地址获取以及PTZ云台控制这几项最高频的对接需求。整套源代码结构清晰、注释完整做安防平台、上位机开发或者视频接入网关的朋友建议直接拿去做二次开发也可以当协议学习资料来读。我先把核心经验和代码思路都拆开讲清楚文章最后也会附上实践中容易踩的坑。1. 项目背景与需求拆解1.1 安防设备接入的核心痛点做视频监控平台这几年我发现一个现象每个设备厂商都有自己的一套SDK接口风格完全不一样。海康的SDK基于设备网络SDK大华有自己的NetSDK还有一部分小厂商直接丢过来一份ActiveX控件让人调用。如果你需要同时接入多家设备代码里就得写多套对接逻辑后期维护和版本适配非常痛苦。稍不注意还会遇到SDK之间动态库冲突、回调模型不兼容的问题相当糟心。ONVIFOpen Network Video Interface Forum的价值就在于此它把设备发现、设备配置、媒体流协商、云台控制、事件订阅等能力全部标准化统一走Web Service接口。也就是说只要设备支持ONVIF协议你就有机会用同一套代码去对接不同品牌的设备。虽然实际使用中各家对协议标准的实现程度略有差异但至少在“获取RTSP地址”“读取设备信息”“控制云台”这些基础场景上ONVIF是真实可信赖的。1.2 工具的核心能力清单这个C#客户端工具围绕安防集成中最常见的几类需求来做每一块对应ONVIF协议里的不同服务功能模块解决的问题对应的ONVIF能力设备自动发现局域网内搜索在线设备免去手动填IPWS-Discovery广播探测设备信息读取获取厂商、型号、固件版本、序列号Device Service的GetDeviceInformation能力协商获取设备支持的媒体、PTZ等服务地址Device Service的GetCapabilities媒体Profile查询拿到视频编码配置、分辨率参数Media Service的GetProfilesRTSP地址获取拿到真正可播放的取流地址Media Service的GetStreamUriPTZ云台控制上下左右转动、缩放、预置位跳转PTZ Service的ContinuousMove/Move等对照这个表格去读源码会轻松很多每一个界面按钮背后基本都能对应到协议中某一个具体的服务请求。1.3 源码工程的目录结构与阅读顺序拿到源码后不要急着按F5先花五分钟理清工程结构。项目里通常包含三个关键部分OnvifDiscoveryUDP发现模块、OnvifClient对WCF代理的二次封装、OnvifToolWinForm界面层。我的建议阅读顺序是先打开界面层看看按钮对应哪些操作再进到OnvifClient里看每个方法如何组织请求最后需要参考协议字段时再去查WSDL生成的代理类。这样由外到内理解效率最高也不会一上来就被大段生成的代码淹没。2. 协议原理与技术选型2.1 ONVIF到底做了什么先纠正一个常见误区ONVIF协议本身不传视频流。很多人以为ONVIF和RTSP是同一种东西其实二者分工明确。ONVIF处理的是管理面和控制面比如“找到设备”“查一下支持哪些参数”“请把流地址给我”“转一下云台”这些操作全部通过SOAP/XML消息完成而真正的视频数据是RTSP协议承载的。如果做个不严谨的类比ONVIF是遥控器RTSP是水管遥控器负责指挥开阀门水流本身走的是另一套通道。搞清楚这个关系后你就理解了为什么开发ONVIF客户端的重点是“拼SOAP请求”和“解析SOAP响应”。而WCF帮我们省掉了大量手工拼XML的体力活它可以根据WSDL文件自动生成客户端代理类把SOAP通信封装成普通的C#方法调用。这也是这个工具能够以较少代码量覆盖多类功能的基础。2.2 为什么选择C#和VS2015这个组合选型这件事我向来主张“能解决问题就行没有银弹”。在这个项目里C# VS2015是务实的选择。第一C#有WCF这个成熟的Web Service框架对SOAP协议的支持在主流语言里是数一数二的。配合svcutil.exe工具拿到WSDL就能自动生成强类型的客户端代理类写起代码来比在Java里折腾CXF、在Python里手拼XML舒服太多。第二VS2015对应的.NET Framework 4.6.x在Windows平台下部署非常省事工业现场、监控机房里的机器大多还是Windows环境跑起来毫无压力。第三从后续可维护性上讲这套代码的兼容性很好如果以后要升级到.NET Core/.NET 5只需要安装System.ServiceModel.Http等NuGet包把命名空间微调一下就能跑起来迁移成本很低。2.3 一次完整调用链路是怎样的理解一次完整调用的地址流转是开发ONVIF客户端最关键的一步。用一句话概括就是先靠发现拿到设备服务地址再靠设备服务拿到能力地址最后靠能力地址调用具体服务。顺序是这样的通过WS-Discovery向局域网内发送UDP组播Probe消息在线设备会回复自身的探测响应消息里带有Device Service的XAddr类似http://192.168.1.64/onvif/device_service。调Device Service的GetCapabilities拿到Media Service、PTZ Service等多个子服务的XAddr。向Media Service发GetProfiles请求拿到视频编码Profile列表。向Media Service发GetStreamUri请求拿到RTSP取流地址例如rtsp://192.168.1.64:554/Streaming/Channels/101。需要控制云台时向PTZ Service发云台移动请求。整套流程的本质是“一层层解开地址再带着凭证去调更细分的服务”。源码里最值得研究的就是这条主链路把这一条线打通剩下的动作基本都是同一种套路。3. 核心模块实现与代码解析3.1 设备自动发现模块WS-Discovery的细节与坑设备发现是整个工具的第一步也是最容易出幺蛾子的一步。ONVIF的发现协议基于WS-Discovery本质是向组播地址239.255.255.250的3702端口发一条SOAP Probe消息。下面是Probe消息的核心XML结构e:Envelope xmlns:ehttp://www.w3.org/2003/05/soap-envelope xmlns:whttp://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:dhttp://schemas.xmlsoap.org/ws/2005/04/discovery xmlns:dnhttp://www.onvif.org/ver10/network/wsdl e:Header w:MessageIDuuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/w:MessageID w:Tourn:schemas-xmlsoap-org:ws:2005:04:discovery/w:To w:Actionhttp://schemas.xmlsoap.org/ws/2005/04/discovery/Probe/w:Action /e:Header e:Body d:Probe d:Typesdn:NetworkVideoTransmitter/d:Types /d:Probe /e:Body /e:EnvelopeC#侧发送和接收的骨架代码如下。这里有个重要的实现细节UDP客户端不能绑定到0.0.0.0要绑定到本机实际网卡的IP地址否则在很多设备上会收不到组播回包。using (var udp new UdpClient()) { udp.ExclusiveAddressUse false; udp.Client.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.ReuseAddress, true); // localIp 是本机指定网卡的IP不要用 0.0.0.0 udp.Client.Bind(new IPEndPoint(IPAddress.Parse(localIp), 3702)); udp.JoinMulticastGroup(IPAddress.Parse(239.255.255.250)); var probeMessage BuildProbeXml(); // 组装上面的XML模板 var sendBytes Encoding.UTF8.GetBytes(probeMessage); await udp.SendAsync(sendBytes, sendBytes.Length, new IPEndPoint(IPAddress.Parse(239.255.255.250), 3702)); var remoteEndPoint new IPEndPoint(IPAddress.Any, 0); var receiveBytes udp.Receive(ref remoteEndPoint); var responseXml Encoding.UTF8.GetString(receiveBytes); // 解析 responseXml 中的 ProbeMatches - XAddrs 节点 }从收到的响应XML里用XDocument解析出XAddrs节点的值那就是设备服务地址。解析时有两个坑要提前规避XAddrs节点可能返回多个地址要优先取与本机处于同一网段的那个否则后续请求可能走不通。部分设备返回的地址不是纯IP而是设备主机名遇到这种情况需要做一次主机名到IP的转换或者直接字符串替换成IP访问。注意发送Probe时MessageID必须是合法的uuid格式否则部分严格实现协议栈的设备会静默丢弃。理论上还可以发单播Probe到某个特定IP定向探测一台设备这在设备组播支持不完善时是很好的备选方案。3.2 服务代理生成svcutil的正确打开方式拿到设备地址后需要调用各种服务。最省力的方式是先用svcutil.exe把ONVIF官方的WSDL文件生成C#代理类。ONVIF官网提供了完整的WSDL文件集合建议把device_service.wsdl、media_service.wsdl、ptz_service.wsdl等需要用到的一起下载到本地同一目录。注意这些WSDL之间会相互引用所以不要单独拿一个文件去生成也不要在引用相对路径上做改动。命令行示例svcutil.exe device_service.wsdl media_service.wsdl ptz_service.wsdl /edb /n:*,OnvifContract /o:OnvifServices.cs参数解释/edb生成数据契约时使用现有的可扩展类型避免重复定义基础类型。/n:*,OnvifContract把生成的所有类型统一放到OnvifContract命名空间方便引用。/o:OnvifServices.cs指定输出文件。生成完成后工程里引用了System.ServiceModel就能直接调用接口方法已被封装成强类型方法。例如获取设备信息var deviceClient new DeviceClient(binding, endpointAddress); deviceClient.ClientCredentials.HttpDigest.ClientCredential.UserName userName; deviceClient.ClientCredentials.HttpDigest.ClientCredential.Password password; var deviceInfo deviceClient.GetDeviceInformation(); Console.WriteLine(${deviceInfo.Manufacturer} {deviceInfo.Model});有一点要提前提醒很多设备的ONVIF服务需要鉴权如果直接用默认的匿名访问会收到访问拒绝错误。WCF代理类可以利用ClientCredentials直接配置HttpDigest凭据大部分海康、大华等主流设备都支持这种鉴权方式。3.3 取流、PTZ与鉴权的关键代码细节确保WCF绑定配置正确是一件容易被忽略但极其重要的事。ONVIF标准走的是SOAP 1.2而WCF里BasicHttpBinding默认是SOAP 1.1直接使用默认配置会收到“无法处理消息”的异常。正确做法是指定MessageVersion为Soap12并且放宽消息大小和超时限制因为有些设备返回的响应字段比较多var binding new BasicHttpBinding(BasicHttpSecurityMode.TransportCredentialOnly) { MessageEncoding WSMessageEncoding.Text, MaxReceivedMessageSize 10485760, SendTimeout TimeSpan.FromSeconds(10), ReceiveTimeout TimeSpan.FromSeconds(10) }; binding.MessageVersion MessageVersion.Soap12; binding.Security.Transport.ClientCredentialType HttpClientCredentialType.Digest;取RTSP地址的调用逻辑是这样的先通过GetProfiles拿到第一个Profile再把ProfileToken传给GetStreamUri。这里最容易犯的错是把整个Profile对象传进去而接口其实只需要Token字段。var profiles mediaClient.GetProfiles(); if (profiles.Length 0) throw new Exception(设备未配置任何媒体Profile); var profileToken profiles[0].token; var streamUri mediaClient.GetStreamUri( new StreamSetup { Stream StreamType.RTPUnicast, Transport new Transport { Protocol TransportProtocol.RTSP } }, profileToken); var rtspAddress streamUri.Uri;PTZ控制同样简单常见的连续转动指令如下速度向量x表示水平速度y表示垂直速度范围为-1.0到1.0// 向右上方转动 ptzClient.ContinuousMove(profileToken, new PTZSpeed { PanTilt new Vector2D { x 0.5f, y 0.3f }, Zoom new Vector1D { x 0f } }, null); // 停止转动 ptzClient.Stop(profileToken, true, true);如果设备只支持WS-UsernameToken鉴权而不支持DigestWCF自带的凭据配置就不够用了。这时候需要手工构造SOAP头按标准算法填充Nonce、Created和PasswordDigest。核心计算逻辑是这样byte[] nonce Guid.NewGuid().ToByteArray(); string created DateTime.UtcNow.ToString(yyyy-MM-ddTHH:mm:ssZ); byte[] digestBytes SHA1.Create().ComputeHash( Encoding.UTF8.GetBytes( Convert.ToBase64String(nonce) created password)); string passwordDigest Convert.ToBase64String(digestBytes);把这三个值按WS-Security的规则塞进SOAP Header后加上用户名就得到了UsernameToken。这套算法在对接一些自定义平台时非常有用建议单独封装成一个方法方便多处调用。4. 实操演示与踩坑记录4.1 完整跑通一次设备对接流程整个工具跑通一次的真实流程我按步骤描述一遍方便你对照源码验证。第一步打开工具界面在网卡下拉框中选中本机与摄像头处于同一局域网的网卡。第二步点击“搜索设备”等2到3秒界面上会列出发现的所有ONVIF设备这里注意如果什么也没搜到优先检查本机防火墙是否放行了UDP 3702端口。第三步双击设备条目输入摄像头的登录用户名和密码就是Web登录那套账号点击“获取信息”界面会显示厂商、型号、序列号等信息这时说明鉴权和服务地址链路已经通了。第四步点击“获取RTSP地址”把拿到的地址复制出来用VLC播放器或者FFmpeg验证一下能否出图。我实测主流设备返回的地址形如rtsp://user:pass192.168.1.64:554/Streaming/Channels/101如果无法播放十有八九是密码中有特殊字符没有做URL编码。第五步切到云台控制页按方向按钮试试转动和停止。到这里整套工具的核心功能就算完全验证通过了。4.2 高频问题排查速查表下面这份速查表是从一遍遍踩坑中整理出来的按出现频率排序基本覆盖了开发ONVIF客户端时最容易遇到的一批问题。现象原因解决办法设备搜索不到防火墙拦截UDP组播入站规则放行UDP 3702端口或临时关闭防火墙测试搜索能发现但调用服务超时XAddr指向的端口不通或地址错网段抓包确认设备回包的XAddrs必要时手动替换为本机可达IP报“无法处理消息”异常WCF绑定默认SOAP 1.1与ONVIF期望的1.2不匹配设置MessageVersion为MessageVersion.Soap12无鉴权直接调用提示AccessDenied部分设备默认禁止匿名访问配置ClientCredentials的HttpDigest用户密码GetStreamUri返回地址无法播放RTSP地址中用户名密码未做URL编码或端口不对使用Uri.EscapeDataString处理账号密码设备信息能拿但GetProfiles为空设备没有配置任何视频Profile换个ONVIF Profile S兼容性更好的设备测试IPv6环境搜不到设备组播地址需要切换成IPv6范围地址一些设备默认只开了IPv4发现需在设备Web端开启IPv64.3 几条用钱买来的实战教训最后分享几条特别值得说的经验尤其是对第一次上手ONVIF开发的兄弟能帮你少走很多弯路。第一多网卡机器上做设备发现必须指定网卡绑定。笔记本开着WiFi又插着网线用0.0.0.0监听时经常只能搜到虚拟机的网卡响应或者干脆收不到设备回包。绑定到实际通信网卡的IP后问题就消失了。这一点在工控机上做上位机开发时尤其常见。第二不要盲目相信设备返回的XAddr。大华和部分OEM设备在某些固件版本下返回的XAddr可能是本机的主机名而不是IP或者是一个跨网段的地址。这种情况下要么在代码里做字符串替换把主机名替换成IP要么在界面上提供手动修改地址的入口。千万别觉得这个很基础就忽视它现场项目里因为地址解析导致对接不上的情况我遇到过好几次。第三超时时间不要设置得太短。普通Web服务两三秒没响应可能就觉得挂了但有些老设备处理GetProfiles请求需要好几秒设置5秒以上的超时时间会从容很多。同时把重试机制做好设备偶尔会丢一次请求重试一次往往就好了。第四如果只是快速验证摄像头是否支持ONVIF不一定非要先写代码。有现成的ONVIF Device Manager这类工具可以先测一下设备能力等确认设备端OK再让代码去调试这样能省掉很多不必要的怀疑。等自己的工具写好了再用它去验证自己写的代码定位问题也不迟。这个工具做完之后我对ONVIF协议的信任度提升了一个档次。以前总觉得不同品牌设备一定得靠私有SDK才能接现在只要看到设备支持ONVIF心里就踏实很多。后面如果你要继续扩展可以考虑在这个基础上加上ONVIF事件订阅比如移动侦测、报警输入这类Event再把RTSP播放器集成进界面里做成一个完整的客户端。代码已经放在那里了照着协议一层层去理解比自己从零开始摸索要节省大量时间。希望这篇拆解能帮到正在和安防设备较劲的你。本文还有配套的精品资源点击获取
