UA-.NETStandard/docs/FirstModel.md

Your first information model

This tutorial continues Route B of Getting started. You add a small information model to the server, give it behavior, and use it from the client. The model describes a room thermostat:

• A ThermostatType object type with a measured Temperature, a writable Setpoint, and a Boost method that raises the setpoint.
• A Thermostat object of that type in the server's Objects folder.

The server accepts setpoints from 5 to 30 degrees Celsius. The client finds the thermostat by name, reads and writes its variables, and calls its method. It also shows how the server reports an operation that it rejects.

Contents

• Before you begin
• 1. Describe the model
• 2. Add the model to the server
  • Generate the code
  • Implement the behavior
  • Register the node manager
• 3. Use the model from the client
  • Share the model
  • Replace the client code
• 4. Check the result
• What the code does
• Troubleshooting
• Next steps

Before you begin

Complete steps B1 to B4 of Getting started. This tutorial changes the GettingStartedServer and GettingStartedClient projects from those steps. The applications keep their certificates and already trust each other, so you do not repeat the trust steps.

The tutorial was verified with package version 2.0.0, the version that Route B installs.

If you ran only the repository samples, create the Route B projects first. The MinimalCalcServer sample uses the same server-side pattern as this tutorial.

1. Describe the model

A model file declares types and instances. At build time, the SDK source generator reads the file and generates C# code for it.

In the GettingStartedServer folder, create a Model folder and in it a file named Heating.xml:

<?xml version="1.0" encoding="utf-8"?>
<opc:ModelDesign
  xmlns:opc="http://opcfoundation.org/UA/ModelDesign.xsd"
  xmlns:ua="http://opcfoundation.org/UA/"
  xmlns="http://example.com/Heating/"
  TargetNamespace="http://example.com/Heating/"
  TargetXmlNamespace="http://example.com/Heating/Types.xsd"
  TargetVersion="1.0.0"
  TargetPublicationDate="2026-01-01T00:00:00Z">

  <opc:Namespaces>
    <opc:Namespace Name="Heating" Prefix="Heating"
      XmlNamespace="http://example.com/Heating/Types.xsd"
      XmlPrefix="Heating">http://example.com/Heating/</opc:Namespace>
    <opc:Namespace Name="OpcUa" Prefix="Opc.Ua"
      XmlNamespace="http://opcfoundation.org/UA/2008/02/Types.xsd"
      XmlPrefix="OpcUa">http://opcfoundation.org/UA/</opc:Namespace>
  </opc:Namespaces>

  <opc:Method SymbolicName="BoostMethodType">
    <opc:Description>Raises the setpoint and returns the new setpoint.</opc:Description>
    <opc:InputArguments>
      <opc:Argument Name="Degrees" DataType="ua:Double">
        <opc:Description>The number of degrees to add to the setpoint.</opc:Description>
      </opc:Argument>
    </opc:InputArguments>
    <opc:OutputArguments>
      <opc:Argument Name="NewSetpoint" DataType="ua:Double" />
    </opc:OutputArguments>
  </opc:Method>

  <opc:ObjectType SymbolicName="ThermostatType" BaseType="ua:BaseObjectType">
    <opc:Description>A thermostat that controls the temperature of a room.</opc:Description>
    <opc:Children>
      <opc:Variable SymbolicName="Temperature" DataType="ua:Double"
        AccessLevel="Read" ModellingRule="Mandatory">
        <opc:Description>The measured temperature in degrees Celsius.</opc:Description>
      </opc:Variable>
      <opc:Variable SymbolicName="Setpoint" DataType="ua:Double"
        AccessLevel="ReadWrite" ModellingRule="Mandatory">
        <opc:Description>The target temperature in degrees Celsius, from 5 to 30.</opc:Description>
      </opc:Variable>
      <opc:Method SymbolicName="Boost" TypeDefinition="BoostMethodType"
        ModellingRule="Mandatory" />
    </opc:Children>
  </opc:ObjectType>

  <opc:Object SymbolicName="Thermostat" TypeDefinition="ThermostatType">
    <opc:Description>The living-room thermostat.</opc:Description>
    <opc:References>
      <opc:Reference IsInverse="true">
        <opc:ReferenceType>ua:Organizes</opc:ReferenceType>
        <opc:TargetId>ua:ObjectsFolder</opc:TargetId>
      </opc:Reference>
    </opc:References>
  </opc:Object>
</opc:ModelDesign>

Part	Meaning
TargetNamespace	The namespace URI that identifies the model. When the server starts, it assigns each namespace URI a number, the namespace index. Clients look up the index by the URI.
Prefix="Heating"	The C# namespace of the generated code.
BoostMethodType	Declares the arguments of the Boost method: one Double input and one Double output.
ThermostatType	The object type. Every instance has the Mandatory children. AccessLevel decides whether clients can write a variable.
Thermostat	An instance of ThermostatType. The inverse Organizes reference places it in the Objects folder, where clients start browsing.

The file uses the ModelDesign format, which is compact to write by hand. The generator also reads NodeSet2 files: the standard exchange format of modeling tools and companion specifications. See Source-generated node managers.

The Boost method takes its arguments from BoostMethodType, so other methods can share the same arguments. A method can also declare its arguments itself, without a method type.

2. Add the model to the server

Stop the server if it is still running from Getting started.

Generate the code

From the GettingStartedServer folder, add the source generator package. It runs at build time and adds no assembly to your application.

dotnet add package OPCFoundation.NetStandard.Opc.Ua.SourceGeneration

Open GettingStartedServer.csproj, and add the model file inside the <Project> element:

<ItemGroup>
  <AdditionalFiles Include="Model/Heating.xml" />
</ItemGroup>

Implement the behavior

Create HeatingNodeManager.cs in the GettingStartedServer folder:

using Opc.Ua;
using Opc.Ua.Server.Fluent;

namespace Heating;

[NodeManager(NamespaceUri = "http://example.com/Heating/")]
public partial class HeatingNodeManager
{
    private const double MinimumSetpoint = 5.0;
    private const double MaximumSetpoint = 30.0;

    private readonly Lock m_lock = new();
    private double m_setpoint = 21.0;

    partial void Configure(IHeatingNodeManagerBuilder builder)
    {
        builder.Thermostat.Temperature
            .PollEvery(TimeSpan.FromSeconds(1), SampleTemperature);
        builder.Thermostat.Setpoint
            .OnRead(ReadSetpoint)
            .OnWrite(WriteSetpoint);
        builder.Thermostat.Boost
            .OnCall(Boost);
    }

    // Simulates a measurement within half a degree of the setpoint.
    private double SampleTemperature()
    {
        return Math.Round(ReadSetpoint() - 0.5 + Random.Shared.NextDouble(), 1);
    }

    private double ReadSetpoint()
    {
        lock (m_lock)
        {
            return m_setpoint;
        }
    }

    private void WriteSetpoint(double value)
    {
        CheckSetpoint(value);
        lock (m_lock)
        {
            m_setpoint = value;
        }
    }

    private double Boost(double degrees)
    {
        lock (m_lock)
        {
            double newSetpoint = m_setpoint + degrees;
            CheckSetpoint(newSetpoint);
            m_setpoint = newSetpoint;
            return newSetpoint;
        }
    }

    // The client receives the status code of an exception that a callback throws.
    private static void CheckSetpoint(double setpoint)
    {
        if (setpoint is not (>= MinimumSetpoint and <= MaximumSetpoint))
        {
            throw new ServiceResultException(
                StatusCodes.BadOutOfRange,
                $"The setpoint must be from {MinimumSetpoint} to {MaximumSetpoint}.");
        }
    }
}

The [NodeManager] attribute asks the generator to complete this partial class. The generated part loads the model's nodes into the server's address space. The generator also creates a HeatingNodeManagerFactory class and an IHeatingNodeManagerBuilder interface. Set NamespaceUri to the model's namespace URI as a string literal. The generated constant for it, Heating.Namespaces.Heating, cannot be used here, because the attribute is read before that constant is generated.

In Configure, the builder has a property for each node of the model: builder.Thermostat.Setpoint is the Setpoint variable of the Thermostat object. A misspelled name is a compile error. The callbacks connect the nodes to the state that the node manager holds:

• PollEvery samples Temperature every second and updates the node when the value changes. Reads return the latest sample, and subscriptions receive each change.
• OnRead and OnWrite handle each read and write of Setpoint. A value that is returned only by an OnRead callback does not reach subscriptions; see pushing value changes to subscribers.
• OnCall receives the method's input as a double and returns its output.

To reject an operation, throw a ServiceResultException with a Bad status code. The server returns that status code to the client. The server checks some rules itself before it calls your callback: it rejects a value of the wrong data type and a write to the read-only Temperature.

The server runs callbacks for several requests at the same time, and PollEvery runs in the background, so a lock guards the setpoint.

Register the node manager

Replace the contents of Program.cs:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services
    .AddOpcUa()
    .AddServer(options =>
    {
        options.ApplicationName = "GettingStartedServer";
        options.ApplicationUri = "urn:localhost:GettingStartedServer";
        options.ProductUri = "urn:example.com:GettingStartedServer";
        options.EndpointUrls.Add("opc.tcp://localhost:62560/GettingStartedServer");
        options.PkiRoot = Path.Combine(builder.Environment.ContentRootPath, "pki");
    })
    .AddNodeManager<Heating.HeatingNodeManagerFactory>();

await builder.Build().RunAsync();

Only the AddNodeManager line is new. It adds the generated factory, which creates the node manager when the server starts.

Start the server:

dotnet run

The server is ready when it logs:

OPC UA server listening at opc.tcp://localhost:62560/GettingStartedServer.

Leave the server running.

3. Use the model from the client

Share the model

The client generates code from the same model file: constants for the namespace URI and the browse names, and a typed client for ThermostatType.

In the second terminal, from the GettingStartedClient folder, add the source generator package:

dotnet add package OPCFoundation.NetStandard.Opc.Ua.SourceGeneration

Open GettingStartedClient.csproj, and add the following inside the <Project> element:

<PropertyGroup>
  <ModelSourceGeneratorOmitFluentApi>true</ModelSourceGeneratorOmitFluentApi>
</PropertyGroup>

<ItemGroup>
  <AdditionalFiles Include="../GettingStartedServer/Model/Heating.xml" />
</ItemGroup>

ModelSourceGeneratorOmitFluentApi turns off the server-side helpers, which need the server package.

Replace the client code

Replace the contents of Program.cs:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Opc.Ua;
using Opc.Ua.Client;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Logging.SetMinimumLevel(LogLevel.Warning);

builder.Services
    .AddOpcUa()
    .AddClient(options =>
    {
        options.ApplicationName = "GettingStartedClient";
        options.ApplicationUri = "urn:localhost:GettingStartedClient";
        options.ProductUri = "urn:example.com:GettingStartedClient";
        options.PkiRoot = Path.Combine(builder.Environment.ContentRootPath, "pki");
        options.Session = new ManagedSessionOptions
        {
            ReconnectPolicy = new ReconnectPolicyOptions { MaxRetries = 2 },
        };
    })
    .AddDiscoveryAndConnect(options =>
    {
        options.DiscoveryUrl = "opc.tcp://localhost:62560/GettingStartedServer";
        options.SecurityMode = MessageSecurityMode.SignAndEncrypt;
        options.SecurityPolicyUri = SecurityPolicies.Basic256Sha256;
    });

using IHost host = builder.Build();
await host.StartAsync();

using var timeout = new CancellationTokenSource(TimeSpan.FromMinutes(1));
CancellationToken ct = timeout.Token;

try
{
    var connect = host.Services
        .GetRequiredService<Func<CancellationToken, Task<ManagedSession>>>();
    ManagedSession session = await connect(ct);
    await using (session)
    {
        // The server assigns the namespace index at run time. Look it up
        // from the namespace URI that the model defines.
        int namespaceIndex = session.NamespaceUris.GetIndex(Heating.Namespaces.Heating);
        if (namespaceIndex < 0)
        {
            throw new ServiceResultException(
                StatusCodes.BadNotFound,
                "The server does not expose the Heating model.");
        }
        var ns = (ushort)namespaceIndex;
        Console.WriteLine($"Heating namespace index: {ns}");

        // Translate three browse paths, starting at the Objects folder, in one request.
        TranslateBrowsePathsToNodeIdsResponse translated =
            await session.TranslateBrowsePathsToNodeIdsAsync(
                null,
                [
                    PathFromObjects(ns, Heating.BrowseNames.Thermostat),
                    PathFromObjects(ns, Heating.BrowseNames.Thermostat,
                        Heating.BrowseNames.Temperature),
                    PathFromObjects(ns, Heating.BrowseNames.Thermostat,
                        Heating.BrowseNames.Setpoint),
                ],
                ct);
        NodeId thermostatId = GetTarget(session, translated.Results[0]);
        NodeId temperatureId = GetTarget(session, translated.Results[1]);
        NodeId setpointId = GetTarget(session, translated.Results[2]);

        // Read both variables in one request. Each value has its own status.
        (ArrayOf<DataValue> values, ArrayOf<ServiceResult> errors) =
            await session.ReadValuesAsync([temperatureId, setpointId], ct);
        PrintValue("Temperature", values[0], errors[0]);
        PrintValue("Setpoint", values[1], errors[1]);

        // Write a valid setpoint, then one outside the range the server accepts.
        foreach (double setpoint in new[] { 22.5, 35.0 })
        {
            WriteResponse response = await session.WriteAsync(
                null,
                [
                    new WriteValue
                    {
                        NodeId = setpointId,
                        AttributeId = Attributes.Value,
                        Value = new DataValue(new Variant(setpoint)),
                    },
                ],
                ct);

            // The Write service succeeds as a whole; each write has its own result.
            Console.WriteLine($"Write Setpoint {setpoint}: {response.Results[0]}");
        }

        // Call the Boost method through the client generated from the model.
        var thermostat = new Heating.ThermostatTypeClient(
            session,
            thermostatId,
            host.Services.GetRequiredService<ITelemetryContext>());
        double newSetpoint = await thermostat.BoostAsync(2.0, ct);
        Console.WriteLine($"Boost 2: new setpoint {newSetpoint}");
        try
        {
            await thermostat.BoostAsync(10.0, ct);
        }
        catch (ServiceResultException ex)
        {
            Console.WriteLine($"Boost 10: {ex.StatusCode}");
        }
    }
}
catch (ServiceResultException ex)
{
    Console.Error.WriteLine($"OPC UA error {ex.StatusCode}: {ex.Message}");
    Environment.ExitCode = 1;
}
catch (OperationCanceledException)
{
    Console.Error.WriteLine("The client did not finish within one minute.");
    Environment.ExitCode = 1;
}
finally
{
    await host.StopAsync();
}

static BrowsePath PathFromObjects(ushort ns, params string[] browseNames)
{
    return new BrowsePath
    {
        StartingNode = ObjectIds.ObjectsFolder,
        RelativePath = new RelativePath
        {
            Elements = browseNames
                .Select(name => new RelativePathElement
                {
                    ReferenceTypeId = ReferenceTypeIds.HierarchicalReferences,
                    IncludeSubtypes = true,
                    TargetName = new QualifiedName(name, ns),
                })
                .ToArray(),
        },
    };
}

static NodeId GetTarget(ManagedSession session, BrowsePathResult result)
{
    if (StatusCode.IsBad(result.StatusCode) || result.Targets.Count == 0)
    {
        throw new ServiceResultException(
            result.StatusCode,
            "A browse path was not found.");
    }
    return ExpandedNodeId.ToNodeId(result.Targets[0].TargetId, session.NamespaceUris);
}

static void PrintValue(string name, DataValue value, ServiceResult error)
{
    if (ServiceResult.IsBad(error) || StatusCode.IsBad(value.StatusCode))
    {
        Console.WriteLine($"{name}: failed with {value.StatusCode}");
    }
    else if (value.WrappedValue.TryGetValue(out double number))
    {
        Console.WriteLine($"{name}: {number} ({value.StatusCode})");
    }
    else
    {
        Console.WriteLine($"{name}: unexpected value {value.WrappedValue}");
    }
}

4. Check the result

Run the client:

dotnet run

The client prints output like this and exits with exit code 0:

Heating namespace index: 2
Temperature: 21.1 (Good [0x00000000])
Setpoint: 21 (Good [0x00000000])
Write Setpoint 22.5: Good [0x00000000]
Write Setpoint 35: BadOutOfRange [0x803C0000]
Boost 2: new setpoint 24.5
Boost 10: BadOutOfRange [0x803C0000]

The temperature varies, and the number format follows your system's culture. The server rejects the setpoint 35 and the boost to 34.5, because both are above 30.

The server keeps its state between client runs: if you run the client again, the setpoint starts at 24.5. Restart the server to start again from 21. When you are done, press Ctrl+C in the server terminal.

What the code does

Step	Code	Learn more
Find the namespace	session.NamespaceUris.GetIndex(Heating.Namespaces.Heating) returns the index that this server assigned to the model's namespace URI. Heating.Namespaces.Heating is a generated constant. Do not hard-code namespace indexes: they can differ between servers.	Concepts: node identity and namespaces
Find the nodes	TranslateBrowsePathsToNodeIdsAsync follows browse names from the Objects folder. It returns the NodeId of each path, or a Bad status such as BadNoMatch. The server chooses the NodeIds of instances; browse paths are the same on every server that implements the model.	Concepts: the address space
Read	ReadValuesAsync reads several values in one request, and returns a DataValue and a ServiceResult for each.	Concepts: values, status codes, and timestamps
Write	WriteAsync returns one status code for each value in the request. The request succeeds even when the server rejects a value. The value must have the variable's data type: 22.0 is a Double, but 22 is an Int32, which fails with BadTypeMismatch.	Concepts: service results and errors
Call	ThermostatTypeClient is generated from ThermostatType. Its BoostAsync method calls Boost with typed arguments, and throws a ServiceResultException when the call fails.	Methods with arguments (server side)
Implement nodes	The generated typed builder attaches PollEvery, OnRead, OnWrite, and OnCall callbacks to the model's nodes.	Typed model traversal

Troubleshooting

Symptom	Cause	What to do
The client build fails with error CS0234: The type or namespace name 'Server' does not exist in the namespace 'Opc.Ua'.	The generator creates server-side helpers, which need the server package.	Set ModelSourceGeneratorOmitFluentApi to true in the client project.
The server build fails with error MODELGEN035: The NamespaceUri expression ... could not be resolved during source generation.	[NodeManager] uses a generated constant, such as Namespaces.Heating.	Use the namespace URI as a string literal.
The server does not expose the Heating model.	The server does not register the node manager, or the model uses another namespace URI.	Check the AddNodeManager call in the server, and the TargetNamespace in the model.
OPC UA error BadNoMatch [0x806F0000]: A browse path was not found.	A browse name in the client does not match the model. Browse names are case-sensitive.	Use the generated Heating.BrowseNames constants.
A write fails with BadTypeMismatch.	The value's data type differs from the variable's data type.	Write a Double, such as 22.0.
BadSecurityChecksFailed or BadCertificateUntrusted	The applications do not trust each other.	Repeat step B3 of Getting started.

Next steps

• Monitor the temperature: pass temperatureId to SubscribeDataChangesAsync, as the Getting started client does for the server clock. See Subscriptions.
• Learn more about generated node managers: NodeSet2 models, instances created at run time, events, and alarms. See Source-generated node managers.
• Load models into a running server without generated code. See Runtime NodeSets.
• Define your own structures. See Source-generated data types.
• Use a standard model, such as Device Integration. See Use companion models.
• Before you deploy, work through the production readiness checklist.