属性与状态机

提示

• 初始化请参考 初始化 页面。
• 过程数据（写 Q / 读 I）请参考 过程数据 页面。
• 诊断功能请参考 诊断 页面。

属性

类别	属性	类型	访问	说明
静态	IsServiceReady	bool	只读	本机服务是否就绪
	LastError	string	只读	全应用最近一次失败文案（sticky，成功路径不清空）
	LastErrorCode	PnSErrorCode	只读	全应用最近一次失败的调用错误码。从未失败为 Success
	ServiceConnected	bool	只读	主站是否周期交换。服务没起来 = false
	ServiceState	PnSState	只读	运行态。服务没起来 = Unknown
	ServiceWaitReason	string	只读	等待原因。服务没起来 = 「服务未就绪」
	ServiceStatusMessage	string	只读	状态文案。服务没起来 = 「服务未就绪」
连接与会话	Connected	bool	只读	IO 控制器是否已经建立周期数据交换。true 才表示周期数据在换
	Attached	bool	只读	本 SDK 会话是否已连上本机服务。Stop 不改变
	IsRunning	bool	只读	IO 设备是否已启用（Start 之后、Stop 之前）
运行态	State	PnSState	只读	运行态枚举。读不到真实状态为 Unknown，不要当成 None
	WaitReason	string	只读	本会话等待原因。主站已连时为空
	EverConnected	bool	只读	是否曾与 IO 控制器建立过连接。true 且 Connected 为 false = 掉线
错误码	ErrorCode	PnSRuntimeErrorCode	只读	最近一次运行错误。未识别值 Unknown。ErrorCodeEnum 已废弃，用本属性
	ErrorCodeRaw	int	只读	运行错误原值（0 = 无错误）。未识别值仍经本属性透传
	ErrorMessage	string	只读	运行错误中文消息
	LastServiceError	string	只读	本会话最近一次失败文案（sticky，成功路径不清空）
诊断入口	Events	PnSEvents	只读	运行态事件。见 [事件](./events)
	Diagnostics	PnSDiagnostics	只读	诊断子对象（快照 / IOPS / 报警 / 记录）。Snapshot / IoStatus / Alarms 与扁平属性同一数据
	DiagSnapshot	PnSDiagSnapshot	只读	诊断快照。字段见 [诊断](./diagnostics)
	IoStatus	PnSIoStatus	只读	IOPS / IOCS。见 [诊断](./diagnostics)
	ProcessData	PnSProcessData	只读	过程数据。见 [过程数据](./io)
周期	HighResolutionTimer	bool	只读	高精度时钟（服务进程持有）。写 = 通知服务打开/关闭；读 = 本会话经服务设置的值
本机会话	ServiceHost	string	只读	本会话连接的服务主机
	ServicePort	int	只读	本会话连接的服务端口
	IsServiceMode	bool	只读	是否为本机服务会话

PnSState 枚举值

本语言类型名 PnSState，取值见 枚举参考。

PnSRuntimeErrorCode 枚举值

本语言类型名 PnSRuntimeErrorCode，取值见 枚举参考。

启停

Start()

public PnSErrorCode Start()

使能 IO 设备。已 Start 且尚未 Stop 则幂等返回 Success。这不是主站已周期交换，主站是否在换数据看 Connected。

返回值：

• PnSErrorCode — Success 成功；已释放返回 InvalidHandle；过程数据未就绪 / 服务端启动失败返回 NativeError；服务不可达返回 ServiceUnreachable

失败写入静态 LastError。另一个实例正在使用时抛 InvalidOperationException；除此之外 IO 路径不抛。

示例：

PnSErrorCode rc = device.Start();
if (rc != PnSErrorCode.Success)
    Console.WriteLine(DarraPnS.LastError);

Stop()

public void Stop()

停用 IO 设备。实例仍在，可再次 Start。未 Start 或已 Stop 则幂等返回。失败写 LastError，不抛。

不是 Dispose()：Stop 不结束 SDK 会话。

示例：

device.Stop();

HighResolutionTimer

public bool HighResolutionTimer { get; set; }

1ms 高精度时钟由服务进程持有。写 = 通知本机服务进程打开/关闭（POST /api/high-resolution-timer）；读 = 本会话经服务设置的值，不是系统真值（服务端配置里打开的 1ms 时钟不会被本属性读出）。安装包默认不打开。

示例：

device.HighResolutionTimer = true;

备注

打开后等待更准，鼠标可能变顿。非 Windows 为空操作。

运行态

State

运行态（只读）。Start / Stop 只管启用 / 停用 IO 设备；本属性始终按现场如实读。读不到真实状态为 Unknown，不要当成 None。

public PnSState State { get; }

示例：

if (device.State == PnSState.DataExchange)
    Console.WriteLine("周期数据交换正常");

WaitReason

public string WaitReason { get; }

本会话等待原因。主站已连时为空。循环 if (!device.Connected) 时读本属性或 LastServiceError。

示例：

if (!device.Connected)
    Console.WriteLine(device.WaitReason);

EverConnected

public bool EverConnected { get; }

是否曾与 IO 控制器建立过连接。false = 从未连过；true 且 Connected == false = 掉线。掉线后此判别仍保留。

示例：

if (!device.Connected && device.EverConnected)
    Console.WriteLine("掉线");

错误码

ErrorCode

public PnSRuntimeErrorCode ErrorCode { get; }

最近一次运行错误（枚举）。未识别值 Unknown。原值仍经 ErrorCodeRaw 透传。中文消息用 ErrorMessage。

示例：

PnSRuntimeErrorCode err = device.ErrorCode;
string text = device.ErrorMessage;
int raw = device.ErrorCodeRaw;

ErrorCodeRaw

public int ErrorCodeRaw { get; }

运行错误原值（0 = 无错误）。未识别值仍经本属性透传。

示例：

int raw = device.ErrorCodeRaw;

ErrorMessage

public string ErrorMessage { get; }

运行错误中文消息。未识别码返回带原值的说明，不丢信息。

示例：

Console.WriteLine(device.ErrorMessage);

LastServiceError

public string LastServiceError { get; }

本会话最近一次失败文案（sticky）。成功路径不清空。循环 if (!Connected) 时若本属性为空，读 WaitReason。

示例：

Console.WriteLine(device.LastServiceError);

诊断

Diagnostics

public PnSDiagnostics Diagnostics { get; }

诊断子对象（快照 / IOPS / 报警 / 记录）。Snapshot / IoStatus / Alarms / AlarmHistory / Records 与下方扁平属性同一数据。类结构见 DarraPnS。

示例：

var snap = device.Diagnostics.Snapshot;
foreach (var a in device.Diagnostics.Alarms)
    Console.WriteLine(a.Message);

DiagSnapshot

public PnSDiagSnapshot DiagSnapshot { get; }

一次取回链路、帧计数、看门狗、抖动。读不到时 Ok == false，读 Message，不视为异常。字段见 诊断。

示例：

PnSDiagSnapshot snap = device.DiagSnapshot;
if (!snap.Ok)
    Console.WriteLine(snap.Message);

IoStatus

public PnSIoStatus IoStatus { get; }

IOPS / IOCS 快照。0x80 = GOOD，0x00 = BAD。掉线如实全 BAD。读不到返回 PnSIoStatus.Empty。字段见 诊断。

示例：

if (!device.IoStatus.AllGood)
    Console.WriteLine(device.IoStatus.ToString());

完整示例

using Darra.PnS;

using (var device = new DarraPnS())
{
    PnSErrorCode rc = device.Start();
    if (rc != PnSErrorCode.Success)
        return;
    while (running)
    {
        if (!device.Connected)
        {
            Console.WriteLine(device.State);
            Console.WriteLine(device.WaitReason);
            Console.WriteLine(device.ErrorMessage);
            continue;
        }

        device.WriteBool("Q0.0", true);
        device.ReadBool("I0.0", out bool fromPlc);
    }
    device.Stop();
}