MessageValidation.SparkplugB 2.2.0

dotnet add package MessageValidation.SparkplugB --version 2.2.0
                    
NuGet\Install-Package MessageValidation.SparkplugB -Version 2.2.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MessageValidation.SparkplugB" Version="2.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="MessageValidation.SparkplugB" Version="2.2.0" />
                    
Directory.Packages.props
<PackageReference Include="MessageValidation.SparkplugB" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add MessageValidation.SparkplugB --version 2.2.0
                    
#r "nuget: MessageValidation.SparkplugB, 2.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package MessageValidation.SparkplugB@2.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=MessageValidation.SparkplugB&version=2.2.0
                    
Install as a Cake Addin
#tool nuget:?package=MessageValidation.SparkplugB&version=2.2.0
                    
Install as a Cake Tool

MessageValidation.SparkplugB

Eclipse Sparkplug B validator for the MessageValidation pipeline. It parses spBv1.0 topics and Protocol Buffers payloads, then rejects messages that break the spec before they reach your handlers.

Installation

dotnet add package MessageValidation.SparkplugB
dotnet add package MessageValidation.MqttNet   # or any MQTT transport adapter

Quick Start

services
    .AddMessageValidation(
        options => options.MapSource<SparkplugBMessage>("spBv1.0/#"),
        pipeline =>
        {
            pipeline.UseSparkplugB();                              // topic + protobuf → SparkplugBMessage
            MessageValidationPipeline.ConfigureDefaults(pipeline); // validate → failure handling → handler
        })
    .AddSparkplugBValidation()                                     // seq/bdSeq/birth tracking on by default
    .AddMessageHandler<SparkplugBMessage, MyHandler>()
    .AddMqttNetMessageValidation();

Handlers receive only valid messages:

public sealed class MyHandler : IMessageHandler<SparkplugBMessage>
{
    public Task HandleAsync(SparkplugBMessage msg, MessageContext ctx, CancellationToken ct = default)
    {
        // msg.Topic.GroupId / EdgeNodeId / DeviceId / MessageType
        // msg.Payload.Metrics, msg.Payload.Seq …
        return Task.CompletedTask;
    }
}

Invalid messages follow your configured FailureBehavior (Log, DeadLetter, Skip, Throw, Custom), the same as any other MessageValidation adapter.

Standalone

var validator = new SparkplugBValidator();
var result = validator.Validate(topic, payloadBytes);

What is validated

Rule Details
Topic spBv1.0/<group_id>/<message_type>/<edge_node_id>[/<device_id>]. Device messages (D*) require a device_id; node messages (N*) must not have one. IDs must be non-empty and contain no + or #.
Payload The payload must be valid Sparkplug B protobuf.
timestamp Required on every message except NDEATH.
seq Required (0–255) on NBIRTH, DBIRTH, NDATA, DDATA and DDEATH. NDEATH must not include it.
bdSeq NBIRTH and NDEATH must carry a 64-bit bdSeq metric.
Node Control/Rebirth NBIRTH must carry this Boolean metric.
Birth metrics Every metric needs a name and a datatype.
Data metrics Every metric needs a name or an alias.
DataType The value field must match the declared datatype (e.g. Double → double_value). UInt8/UInt16 values are range-checked, and a metric with is_null must not carry a value.

Session tracking (AddSparkplugBValidation(trackSessionState: true), the default)

Session state is tracked per edge node (group_id + edge_node_id):

  • seq: each message must be (previous + 1) % 256, rolling over from 255 to 0. After a gap, tracking resyncs to the received value.
  • No NBIRTH yet: data is rejected until an NBIRTH is seen, because the spec says the host must request a rebirth.
  • Datatypes: they are remembered from NBIRTH/DBIRTH, so NDATA/DDATA metrics sent by alias only are still type-checked.
  • Stale NDEATH: an NDEATH whose bdSeq doesn't match the current NBIRTH is reported as stale (it is an old MQTT Will).

State is held in memory per process. If several consumers share the same edge node, turn tracking off (trackSessionState: false) or keep state elsewhere.

Not covered (yet)

  • STATE host messages (spBv1.0/STATE/<host_id>)
  • Deep DataSet/Template validation

Notes

  • UseSparkplugB() must be registered before ConfigureDefaults. The core deserialization stage skips messages that are already parsed.
  • AddSparkplugBValidation() registers a fallback IMessageDeserializer if you haven't registered one, so Sparkplug-only apps don't need a JSON deserializer.
  • Proto/sparkplug_b.proto comes from Eclipse Tahu and is licensed under EPL-2.0 (only a csharp_namespace option was added). The rest of the package is MIT.

See examples/MessageValidation.SparkplugB.Example for a runnable worker.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.2.0 58 11/16/2026