简介：这份资源面向具备一定C#基础的开发者，聚焦ONVIF协议在摄像头视频查看与云台控制中的落地实现，适用于安防监控、智能家居等需要接入网络摄像机的场景。压缩包共266个文件，约2.48MB，以datasource、xsd、wsdl、svcinfo等协议描述与数据文件为主，配合dll、nupkg等依赖库，以及cs、csproj、sln、config等工程源码与配置，完整呈现一个可编译运行的ONVIF客户端项目结构。内容围绕设备管理服务、媒体服务与PTZ服务展开，涵盖设备发现、认证连接、视频流获取、平移倾斜缩放控制、预设点调用及异常处理等关键环节，并封装为设备管理、媒体控制、云台控制等模块化类。已有618人学习下载，读者可据此理解SOAP请求与RTSP流处理流程，掌握从设备发现到云台操控的完整链路，并借助现成工程快速调试与二次开发。
1. ONVIF 摄像头接入：为什么你的 C# 项目总在“发现设备”这一步翻车
很多做安防上位机的同行都有过类似经历：设备明明在局域网里，用厂商自带的客户端能看能控，自己用 C# 写 ONVIF 客户端却连设备都发现不了，或者发现了设备却拿不到 RTSP 地址，云台控制更是发出去没反应。ONVIF 实现摄像头视频查看和云台控制，本质上是用一套标准 SOAP 协议去替代各家私有 SDK，让同一份 C# 代码能对接不同品牌的网络摄像机。它解决的是多品牌设备统一接入的问题，适合做安防平台、NVR 客户端、巡检机器人视觉模块的开发者。但 ONVIF 的坑不在协议本身，而在设备厂商对标准的裁剪程度、鉴权方式的差异，以及媒体配置文件的解析逻辑。下面按“先跑通发现和取流，再打通云台，最后处理兼容性”的顺序，把这条链路拆开讲。
2. 用 C# 搭一个最小 ONVIF 客户端：从设备发现到拿到 RTSP 地址
2.1 先搞清楚 ONVIF 的通信骨架
ONVIF 不是单一协议，而是一组基于 SOAP over HTTP 的 Web Service 规范。设备发现走的是 WS-Discovery，本质是 UDP 组播；设备能力查询、媒体配置、云台控制走的是 SOAP 请求，端口通常是 80 或 8080。C# 这边不需要引入官方 SDK，直接用HttpClient发 SOAP 信封就能干活，但要注意几个关键点：SOAPAction 头必须带，Content-Type 必须是application/soap+xml，鉴权用 WS-Security UsernameToken 而不是 HTTP Basic。
我一般会先写一个通用的 SOAP 调用方法，把鉴权、命名空间、超时都封装进去。这样后面查能力、取媒体配置、发云台指令都复用同一套逻辑，不用每个接口重写一遍。
// 通用 SOAP 调用封装，传入设备服务地址、SOAPAction 和请求体 public async Task<string> SendSoapRequestAsync( string serviceUrl, string soapAction, string requestBody, string username, string password) { using var client = new HttpClient(); client.Timeout = TimeSpan.FromSeconds(10); // ONVIF 鉴权走 WS-Security，不是 HTTP Basic var authHeader = BuildWsSecurityHeader(username, password); var envelope = $@"<?xml version=""1.0"" encoding=""utf-8""?> <s:Envelope xmlns:s=""http://www.w3.org/2003/05/soap-envelope"" xmlns:tds=""http://www.onvif.org/ver10/device/wsdl""> <s:Header>{authHeader}</s:Header> <s:Body>{requestBody}</s:Body> </s:Envelope>"; var content = new StringContent(envelope, Encoding.UTF8, "application/soap+xml"); // SOAPAction 必须显式设置，否则部分设备直接返回 400 content.Headers.Add("SOAPAction", soapAction); var response = await client.PostAsync(serviceUrl, content); var xml = await response.Content.ReadAsStringAsync(); if (!response.IsSuccessStatusCode) throw new Exception($"SOAP 调用失败: {response.StatusCode}, 返回: {xml}"); return xml; }这段代码里serviceUrl是设备能力里返回的具体服务地址，不是设备根地址。soapAction每个接口不同，比如取设备信息是http://www.onvif.org/ver10/device/wsdl/GetDeviceInformation。BuildWsSecurityHeader需要生成 Nonce、Created 和 PasswordDigest，其中 PasswordDigest 是Base64(SHA1(Nonce + Created + Password))，这是 ONVIF 鉴权的核心，写错了设备会返回 401 但不告诉你哪里错。
2.2 设备发现：UDP 组播发出去收不到回应怎么办
WS-Discovery 的流程是向239.255.255.250:3702发一个 Probe 消息，设备收到后单播回复 ProbeMatch。C# 里用UdpClient就能做，但有几个细节容易翻车：绑定端口要绑0让系统分配，组播要设置MulticastLoopback，接收超时要给够，因为有些设备响应慢。
// WS-Discovery 设备发现，返回设备服务地址列表 public List<string> DiscoverDevices(int timeoutMs = 3000) { var devices = new List<string>(); var probeMessage = @"<?xml version=""1.0"" encoding=""utf-8""?> <soap:Envelope xmlns:soap=""http://www.w3.org/2003/05/soap-envelope"" xmlns:wsa=""http://schemas.xmlsoap.org/ws/2004/08/addressing"" xmlns:wsd=""http://schemas.xmlsoap.org/ws/2005/04/discovery""> <soap:Header> <wsa:Action>http://schemas.xmlsoap.org/ws/2005/04/discovery/Probe</wsa:Action> <wsa:MessageID>urn:uuid:{Guid.NewGuid()}</wsa:MessageID> <wsa:To>urn:schemas-xmlsoap-org:ws:2005:04:discovery</wsa:To> </soap:Header> <soap:Body> <wsd:Probe/> </soap:Body> </soap:Envelope>"; var multicastEndpoint = new IPEndPoint(IPAddress.Parse("239.255.255.250"), 3702); using var udpClient = new UdpClient(); udpClient.Client.Bind(new IPEndPoint(IPAddress.Any, 0)); udpClient.JoinMulticastGroup(IPAddress.Parse("239.255.255.250")); udpClient.MulticastLoopback = false; var data = Encoding.UTF8.GetBytes(probeMessage); udpClient.Send(data, data.Length, multicastEndpoint); var stopwatch = Stopwatch.StartNew(); while (stopwatch.ElapsedMilliseconds < timeoutMs) { if (udpClient.Available > 0) { var remoteEndPoint = new IPEndPoint(IPAddress.Any, 0); var response = udpClient.Receive(ref remoteEndPoint); var xml = Encoding.UTF8.GetString(response); // 从 ProbeMatch 里提取 XAddrs，就是设备服务地址 var match = Regex.Match(xml, @"<[^>]*XAddrs[^>]*>([^<]+)</[^>]*XAddrs>"); if (match.Success) devices.Add(match.Groups[1].Value.Trim()); } Thread.Sleep(50); } return devices; }timeoutMs给 3000 是经验值，有些国产设备响应要 1 秒以上。MulticastLoopback = false是为了避免收到自己发的包。如果发现不了设备，先确认防火墙有没有放行 UDP 3702，再确认设备是否开启了 ONVIF 功能——很多摄像头默认关闭，需要在 Web 界面里手动打开。
2.3 取 RTSP 地址：媒体配置文件的解析顺序不能乱
拿到设备服务地址后，先调GetCapabilities拿到 Media 服务地址，再调GetProfiles拿到媒体配置文件列表，最后对每个 Profile 调GetStreamUri才能拿到 RTSP 地址。顺序不能跳，因为GetStreamUri需要 ProfileToken 作为参数。
// 获取设备的 RTSP 流地址，返回主码流和子码流地址 public async Task<(string mainStream, string subStream)> GetStreamUrisAsync( string mediaServiceUrl, string username, string password) { // 第一步：拿 Profile 列表 var profilesXml = await SendSoapRequestAsync( mediaServiceUrl, "http://www.onvif.org/ver10/media/wsdl/GetProfiles", "<trt:GetProfiles xmlns:trt=\"http://www.onvif.org/ver10/media/wsdl\"/>", username, password); var profileTokens = Regex.Matches(profilesXml, @"token=""([^""]+)""") .Cast<Match>().Select(m => m.Groups[1].Value).ToList(); string mainStream = null, subStream = null; // 第二步：对每个 Profile 取流地址 foreach (var token in profileTokens) { var streamXml = await SendSoapRequestAsync( mediaServiceUrl, "http://www.onvif.org/ver10/media/wsdl/GetStreamUri", $@"<trt:GetStreamUri xmlns:trt=""http://www.onvif.org/ver10/media/wsdl""> <trt:StreamSetup> <tt:Stream xmlns:tt=""http://www.onvif.org/ver10/schema"">RTP-Unicast</tt:Stream> <tt:Transport xmlns:tt=""http://www.onvif.org/ver10/schema""> <tt:Protocol>RTSP</tt:Protocol> </tt:Transport> </trt:StreamSetup> <trt:ProfileToken>{token}</trt:ProfileToken> </trt:GetStreamUri>", username, password); var uriMatch = Regex.Match(streamXml, @"<[^>]*Uri[^>]*>([^<]+)</[^>]*Uri>"); if (!uriMatch.Success) continue; var uri = uriMatch.Groups[1].Value.Trim(); // 一般第一个是主码流，第二个是子码流，但不同厂商顺序可能相反 if (mainStream == null) mainStream = uri; else if (subStream == null) subStream = uri; } return (mainStream, subStream); }这里有个血泪经验：GetStreamUri返回的地址里可能带rtsp://也可能不带，有些设备返回的是rtsp://192.168.1.100:554/stream1，有些返回rtsp://[fe80::1]:554/stream1这种 IPv6 链路本地地址，直接丢给播放器会连不上。我一般会在拿到地址后做一次规范化，把 IPv6 地址替换成设备发现时拿到的 IPv4 地址。另外主码流和子码流的顺序不能靠猜，最好通过 Profile 的VideoEncoderConfiguration里的分辨率来判断，分辨率高的当主码流。
3. 云台控制：PTZ 指令发出去没反应，先查这三个地方
3.1 PTZ 服务地址和能力查询
云台控制走的是 PTZ 服务，地址同样从GetCapabilities里拿。拿到地址后先调GetConfigurations确认设备支持哪些 PTZ 配置，再调GetConfigurationOptions看支持哪些指令。有些球机支持连续移动，有些只支持预置位跳转，不查清楚就发指令，设备会直接忽略。
// 查询 PTZ 配置，确认设备支持的控制方式 public async Task<string> GetPtzConfigurationsAsync( string ptzServiceUrl, string username, string password) { var xml = await SendSoapRequestAsync( ptzServiceUrl, "http://www.onvif.org/ver20/ptz/wsdl/GetConfigurations", "<tptz:GetConfigurations xmlns:tptz=\"http://www.onvif.org/ver20/ptz/wsdl\"/>", username, password); // 返回里会包含 PTZConfiguration token 和 SupportedPTZSpaces // 重点关注 ContinuousPanTiltVelocitySpace 和 RelativePanTiltTranslationSpace return xml; }返回的 XML 里，ContinuousPanTiltVelocitySpace表示支持连续速度控制，RelativePanTiltTranslationSpace表示支持相对位移控制。如果两个都没有，说明这个设备只支持预置位，那就别发连续移动指令了。
3.2 连续移动和停止指令的配对使用
连续移动用ContinuousMove，发出去之后设备会一直动，必须再发Stop才会停。我见过有同行只发ContinuousMove不发Stop，结果云台转到限位还在转，最后卡死。正确的做法是按下方向键发ContinuousMove，松开时发Stop。
// 连续移动云台，panSpeed/tiltSpeed 范围 -1.0 到 1.0 public async Task ContinuousMoveAsync( string ptzServiceUrl, string profileToken, float panSpeed, float tiltSpeed, string username, string password) { var requestBody = $@"<tptz:ContinuousMove xmlns:tptz=""http://www.onvif.org/ver20/ptz/wsdl""> <tptz:ProfileToken>{profileToken}</tptz:ProfileToken> <tptz:Velocity> <tt:PanTilt xmlns:tt=""http://www.onvif.org/ver10/schema"" x=""{panSpeed}"" y=""{tiltSpeed}""/> </tptz:Velocity> </tptz:ContinuousMove>"; await SendSoapRequestAsync( ptzServiceUrl, "http://www.onvif.org/ver20/ptz/wsdl/ContinuousMove", requestBody, username, password); } // 停止云台，PanTilt 和 Zoom 都要停 public async Task StopPtzAsync( string ptzServiceUrl, string profileToken, string username, string password) { var requestBody = $@"<tptz:Stop xmlns:tptz=""http://www.onvif.org/ver20/ptz/wsdl""> <tptz:ProfileToken>{profileToken}</tptz:ProfileToken> <tptz:PanTilt>true</tptz:PanTilt> <tptz:Zoom>true</tptz:Zoom> </tptz:Stop>"; await SendSoapRequestAsync( ptzServiceUrl, "http://www.onvif.org/ver20/ptz/wsdl/Stop", requestBody, username, password); }panSpeed和tiltSpeed的取值范围是 -1.0 到 1.0，正数向右/向上，负数向左/向下。有些设备对速度值不敏感，给 0.5 和给 1.0 转得一样快，这是固件实现差异，不用纠结。Stop指令里PanTilt和Zoom都要设成 true，只停一个另一个可能还在动。
3.3 预置位：设置、调用和删除的 token 管理
预置位用SetPreset、GotoPreset、RemovePreset三个接口。SetPreset时如果不传 PresetToken，设备会自动分配一个；如果传了已存在的 token，就是覆盖更新。我一般会在本地维护一个预置位列表，把 token 和名称对应起来，避免调用时找不到。
// 设置预置位，presetName 是自定义名称，返回设备分配的 token public async Task<string> SetPresetAsync( string ptzServiceUrl, string profileToken, string presetName, string username, string password) { var requestBody = $@"<tptz:SetPreset xmlns:tptz=""http://www.onvif.org/ver20/ptz/wsdl""> <tptz:ProfileToken>{profileToken}</tptz:ProfileToken> <tptz:PresetName>{presetName}</tptz:PresetName> </tptz:SetPreset>"; var response = await SendSoapRequestAsync( ptzServiceUrl, "http://www.onvif.org/ver20/ptz/wsdl/SetPreset", requestBody, username, password); var match = Regex.Match(response, @"<[^>]*PresetToken[^>]*>([^<]+)</[^>]*PresetToken>"); return match.Success ? match.Groups[1].Value.Trim() : null; }预置位 token 在不同设备上格式不一样，有的是数字1，有的是Preset1，还有的是 GUID。不要硬编码，每次从返回值里取。删除预置位时如果 token 不存在，有些设备返回错误，有些直接静默成功，做批量删除时要逐个判断返回值。
4. 避坑与排查：ONVIF 对接中最容易翻车的五个场景
4.1 鉴权失败但返回 200 OK
现象是 SOAP 请求返回 HTTP 200，但 Body 里是Sender not Authorized的 Fault。原因是 WS-Security 的 PasswordDigest 算错了，最常见的是 Nonce 没有做 Base64 编码就直接拼进 SHA1，或者 Created 时间格式不对。解决方法是把 Nonce 用Convert.ToBase64String编码后再拼，Created 用yyyy-MM-ddTHH:mm:ss.fffZ格式，并且确保设备时间和本机时间差不超过 5 分钟。
4.2 发现设备后拿不到媒体服务地址
现象是GetCapabilities返回的 XML 里找不到 Media 节点。原因是有些设备把 Media 服务地址放在GetServices接口里而不是GetCapabilities。解决方法是先调GetServices拿到所有服务地址列表，再从中筛选 Media 和 PTZ 的地址。GetServices的 SOAPAction 是http://www.onvif.org/ver10/device/wsdl/GetServices。
4.3 RTSP 地址能拿到但播放器连不上
现象是GetStreamUri返回了地址，但 VLC 或 FFmpeg 打开超时。原因通常是地址里的 IP 是设备自己的回环地址或者 IPv6 链路本地地址，不是局域网可达的地址。解决方法是在拿到 URI 后做一次替换，把 host 部分换成设备发现时拿到的 IPv4 地址。另外确认 RTSP 端口 554 没有被防火墙拦截。
4.4 云台连续移动后停不下来
现象是发了ContinuousMove后云台一直转，发Stop也没用。原因是Stop请求里的 ProfileToken 和ContinuousMove用的不是同一个，或者Stop的 SOAPAction 写错了。解决方法是确保两个请求用同一个 ProfileToken，并且Stop的 SOAPAction 是http://www.onvif.org/ver20/ptz/wsdl/Stop。如果还是停不下来，发一个速度为 0 的ContinuousMove作为兜底。
4.5 不同品牌设备返回的 XML 命名空间前缀不一致
现象是用正则解析 XML 时，有的设备返回<trt:Profiles>，有的返回<ns1:Profiles>，正则匹配不到。原因是 ONVIF 只规定命名空间 URI，不规定前缀。解决方法是不要用正则匹配前缀，改用XDocument按命名空间 URI 查询，或者用正则时只匹配本地名Profiles而不带前缀。
5. 把 ONVIF 客户端做稳的几个进阶习惯
5.1 用 XDocument 替代正则解析 SOAP 响应
正则解析 XML 在命名空间前缀变化时非常脆弱。我后来全部改成XDocument，按命名空间 URI 查元素，代码稍微长一点但稳定得多。比如取 ProfileToken 可以这样写：
// 用 XDocument 按命名空间解析，避免前缀差异导致匹配失败 XNamespace trt = "http://www.onvif.org/ver10/media/wsdl"; XNamespace tt = "http://www.onvif.org/ver10/schema"; var doc = XDocument.Parse(profilesXml); var tokens = doc.Descendants(trt + "Profiles") .Select(p => p.Attribute("token")?.Value) .Where(t => !string.IsNullOrEmpty(t)) .ToList();这样不管设备返回的前缀是trt还是ns1，只要命名空间 URI 对就能取到。代价是每次解析都要传命名空间，但比正则可靠得多。
5.2 给每个 SOAP 请求加超时和重试
ONVIF 设备在网络波动时响应会很慢，不加超时会导致 UI 卡死。我一般给HttpClient设 10 秒超时，超时后重试一次，重试还失败就报错给用户。注意重试时不要重试ContinuousMove这种有副作用的指令，只重试查询类接口。
5.3 把设备能力缓存到本地
GetCapabilities和GetServices不需要每次操作都调，设备能力在运行期间不会变。我一般会在首次连接时查一次，把 Media 地址、PTZ 地址、ProfileToken 列表缓存起来，后续操作直接用缓存。这样能减少一半以上的 SOAP 请求，UI 响应也快很多。
5.4 云台控制加一个“心跳停止”
连续移动的Stop指令有可能因为网络问题丢失，我后来加了一个定时器，每次发ContinuousMove后启动一个 500ms 的定时器，如果 500ms 内没有新的移动指令，就自动发一次Stop。这样即使松开的Stop丢了，云台也不会一直转。这个习惯帮我省了很多现场调试的麻烦。
5.5 用 FFmpeg 拉流做视频查看的兜底方案
ONVIF 只负责拿到 RTSP 地址，实际视频查看要靠 RTSP 客户端。C# 里可以用FFmpeg命令行拉流转码后推给 UI，也可以用LibVLCSharp直接播放。我一般用 FFmpeg 拉流到本地端口，再用MediaElement播放，这样兼容性最好。FFmpeg 命令大概是ffmpeg -rtsp_transport tcp -i "rtsp://..." -f mpegts udp://127.0.0.1:8888，注意加-rtsp_transport tcp，UDP 模式在无线网络下丢包严重。
这套东西我前后调了快两个月，最大的教训是：ONVIF 标准文档写得很全，但设备厂商只实现了一个子集，而且各自有各自的“方言”。不要假设设备会按标准返回，每个接口拿到返回值后都要做容错解析。另外，云台控制一定要做“停止兜底”，不然现场调试时云台撞限位是常有的事。希望帮到你。
本文还有配套的精品资源，点击获取
