AdsSession Class

Inheritance Hierarchy

System.Object
  TwinCAT.Session
    TwinCAT.Ads.AdsSessionBase
      TwinCAT.Ads.AdsSession

Namespace: TwinCAT.Ads
Assembly: TwinCAT.Ads (in TwinCAT.Ads.dll) Version: 7.0.0+e56d35ccc4675faac24789a4aab60071fc61d470

C#

public class AdsSession : AdsSessionBase

The AdsSession type exposes the following members.

Constructors

Properties

Methods

Events

Fields

Remarks

On top of the well known AdsClient class that is used traditionally for ADS communication, the AdsSession class provides the following additionally abilities out of the box: These are used to provide more stable connections to ADS Servers than the AdsClient can provide. The main issues are Resurrection / Self-Healing after communication timeouts, faster and less error prone reaction to communication errors (not necessarily waiting for communication timeouts) und enhanced communication diagnosis. These enhanced features are provided by the following additions to the TwinCAT.Ads API:

• AdsConnection class.
• Enhanced diagnosis in form of communication statistics Statistics
• (semi-automatic) Resurrectable client communication with AdsConnection objects.
• Symbol caching SymbolServer
• Fail fast handler for connection stabilization IFailFastHandler

The AdsConnection is established by calling the Connect() method. The returned AdsConnection can be used as long the AdsSessionBase exists.

Example

The following sample shows a simple use of the AdsSessionBase object. The AdsSession object (and the dynamic SymbolLoader features) are only available from .NET 4 and upwards.

Use Session (async)

using System;
using System.Diagnostics;
using System.Threading;

using TwinCAT;
using TwinCAT.Ads;
using TwinCAT.Ads.TypeSystem;
using TwinCAT.TypeSystem;
using TwinCAT.TypeSystem.Generic;

namespace Sample
{
    class SessionAsync
    {
    /// <summary>
    /// Defines the entry point of the application.
    /// </summary>
    /// <param name="args">The arguments.</param>
    static async void Main(string[] args)
    {
        AmsAddress address = ArgParser.Parse(args);

        CancellationTokenSource cancelSource = new CancellationTokenSource();
        CancellationToken cancel = cancelSource.Token;
        SessionSettings settings = SessionSettings.Default; // Default settings are Async access with Timeout 5 sec

        // Async access is necessary for Console applications!

        using (AdsSession session = new AdsSession(address, settings))
        {
        AdsConnection connection = (AdsConnection) session.Connect(); // Establish the connection
        connection.ConnectionStateChanged += Connection_ConnectionStateChanged;

        ConnectionState connectionState = connection.ConnectionState; // The actual connection state

        // Read the identification and version number of the device
        var result = await connection.ReadDeviceInfoAsync(cancel);

        result.ThrowOnError(); // Throws exception if failed.

        DeviceInfo deviceInfo = result.DeviceInfo; 
        Version version = deviceInfo.Version.ConvertToStandard();
        Console.WriteLine(string.Format("DeviceName: {0}", deviceInfo.Name));
        Console.WriteLine(string.Format("DeviceVersion: {0}", version.ToString(3)));

        /// Read the state of the device
        var resultReadState = await connection.ReadStateAsync(cancel);
        resultReadState.ThrowOnError();

        StateInfo stateInfo = resultReadState.State;
        AdsState adsState = stateInfo.AdsState;
        short deviceState = stateInfo.DeviceState;

        Console.WriteLine(string.Format("DeviceState: {0}", deviceState));
        Console.WriteLine(string.Format("AdsState   : {0}", adsState));

        // Other ADS methods (as formerly used on AdsClient) can be used also on connection object:

        // connection.ReadAsync(...)
        // connection.WriteAsync(...)
        // connection.AddDeviceNotificationEx += ...

        // Session communication Diagnostic:

        int resurrectionTries = connection.TotalResurrectingTries;
        int succeededResurrections = connection.TotalResurrections;

        AdsCommunicationStatistics statistics = session.Statistics; // The communication statistics

        // Symbol access:
        // The Session holds and Caches the Symbolic data information
        var resultDataTypes = await session.SymbolServer.GetDataTypesAsync(cancel);
        var resultSymbols = await session.SymbolServer.GetSymbolsAsync(cancel);

        if (resultDataTypes.Succeeded && resultSymbols.Succeeded) // Check for succeed
        {
            IDataTypeCollection<IDataType> types = resultDataTypes.DataTypes;
            ISymbolCollection<ISymbol> symbols = resultSymbols.Symbols;

            Symbol projectNameSymbol = (Symbol)symbols["TwinCAT_SystemInfoVarList._AppInfo.ProjectName"];
            var resultReadProjectName = await projectNameSymbol.ReadValueAsync(cancel);
            string projectName = (string)resultReadProjectName.Value;

            // Or use dynamic objects
            dynamic appInfo = symbols["TwinCAT_SystemInfoVarList._AppInfo"];
            string projectName2 = appInfo.ProjectName; // Property dynamically created (synchronous call)!
        }
        Console.WriteLine("");
        Console.WriteLine("Press [Enter] for leave:");
        Console.ReadLine();
        }
    }

    private static void Connection_ConnectionStateChanged(object sender, ConnectionStateChangedEventArgs e)
    {
        Console.WriteLine("Connection State changed (NewState: {0}, OldState: {1}",e.NewState,e.OldState);
    }

Use Session (sync)

using System;
using System.Diagnostics;
using System.Threading;

using TwinCAT;
using TwinCAT.Ads;
using TwinCAT.Ads.TypeSystem;
using TwinCAT.TypeSystem;
using TwinCAT.TypeSystem.Generic;

namespace Sample
{
    class Session
    {
    /// <summary>
    /// Defines the entry point of the application.
    /// </summary>
    /// <param name="args">The arguments.</param>
    static void Main(string[] args)
    {
        AmsAddress address = ArgParser.Parse(args);
        SessionSettings settings = SessionSettings.Default; // Default settings are Async access with Timeout 5 sec

        // Async access is necessary for Console applications!

        using (AdsSession session = new AdsSession(address, settings))
        {
        AdsConnection connection = (AdsConnection) session.Connect(); // Establish the connection
        connection.ConnectionStateChanged += Connection_ConnectionStateChanged;

        ConnectionState connectionState = connection.ConnectionState; // The actual connection state

        // Read the identification and version number of the device
        DeviceInfo deviceInfo = connection.ReadDeviceInfo();
        Version version = deviceInfo.Version.ConvertToStandard();
        Console.WriteLine(string.Format("DeviceName: {0}", deviceInfo.Name));
        Console.WriteLine(string.Format("DeviceVersion: {0}", version.ToString(3)));

        /// Read the state of the device
        StateInfo stateInfo = connection.ReadState();
        AdsState adsState = stateInfo.AdsState;

        short deviceState = stateInfo.DeviceState;
        Console.WriteLine(string.Format("DeviceState: {0}", deviceState));
        Console.WriteLine(string.Format("AdsState   : {0}", adsState));

        // Other ADS methods (as formerly used on AdsClient) can be used also on connection object:

        // connection.Read(...)
        // connection.Write(...)
        // connection.AddDeviceNotificationEx += ...


        // Session communication Diagnostic:

        int resurrectionTries = connection.TotalResurrectingTries;
        int succeededResurrections = connection.TotalResurrections;

        AdsCommunicationStatistics statistics = session.Statistics; // The communication statistics

        // Symbol access:
        // The Session holds and Caches the Symbolic data information
        IDataTypeCollection<IDataType> types = session.SymbolServer.DataTypes;
        ISymbolCollection<ISymbol> symbols = session.SymbolServer.Symbols;

        Symbol projectNameSymbol = (Symbol)symbols["TwinCAT_SystemInfoVarList._AppInfo.ProjectName"];
        string projectName = (string) projectNameSymbol.ReadValue();

        // Or use dynamic objects
        dynamic appInfo = symbols["TwinCAT_SystemInfoVarList._AppInfo"];
        string projectName2 = appInfo.ProjectName;

        Console.WriteLine("");
        Console.WriteLine("Press [Enter] for leave:");
        Console.ReadLine();
        }
    }

    private static void Connection_ConnectionStateChanged(object sender, ConnectionStateChangedEventArgs e)
    {
        Console.WriteLine("Connection State changed (NewState: {0}, OldState: {1}",e.NewState,e.OldState);
    }

Add a custom logger

static async void Main(string[] args)
{
    CancellationTokenSource cancelSource = new CancellationTokenSource();
    CancellationToken cancel = cancelSource.Token;

    var address = new AmsAddress(AmsNetId.Local, AmsPort.SystemService);
    var sessionSettings = SessionSettings.Default;

    //https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line

    // Create a configuration for the custom logger
    var loggerConfig = new AdsLoggerConfiguration
    {
    LogLevel = LogLevel.Information,
    EventId = 0
    };

    // Create an ILoggerFactory and add the custom logger provider
    var loggerFactory = LoggerFactory.Create(builder =>
    {
    //builder.SetMinimumLevel(LogLevel.Information)
    builder.AddProvider(new AdsLoggerProvider(() => loggerConfig))
       .AddConsole(); // Adds the console
    });

    // Use AdsClient with custom logger
    using (AdsClient client = new AdsClient(loggerFactory))
    {
    // Connect
    client.Connect(address);
    }

    // Use AdsSession with custom logger
    using (AdsSession session = new AdsSession(address, sessionSettings, loggerFactory))
    {
    // Connect
    session.Connect();
    }
}

Reference

TwinCAT.Ads Namespace Session IAdsSessionIInterceptionFactory

Beckhoff Automation GmbH & Co. KG 2001-2026