Beckhoff.TwinCAT.Ads.TcpRouter 6.1.290

Prefix Reserved
.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Beckhoff.TwinCAT.Ads.TcpRouter --version 6.1.290                

                    
                

            
NuGet\Install-Package Beckhoff.TwinCAT.Ads.TcpRouter -Version 6.1.290
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="Beckhoff.TwinCAT.Ads.TcpRouter" Version="6.1.290" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Beckhoff.TwinCAT.Ads.TcpRouter --version 6.1.290                

                    
                

            
#r "nuget: Beckhoff.TwinCAT.Ads.TcpRouter, 6.1.290"
#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. 
// Install Beckhoff.TwinCAT.Ads.TcpRouter as a Cake Addin
#addin nuget:?package=Beckhoff.TwinCAT.Ads.TcpRouter&version=6.1.290

// Install Beckhoff.TwinCAT.Ads.TcpRouter as a Cake Tool
#tool nuget:?package=Beckhoff.TwinCAT.Ads.TcpRouter&version=6.1.290

Description

The package 'Beckhoff.TwinCAT.Ads.TcpRouter' implements a lean TCP ADS Router class to use on systems where no standard TwinCAT router is established or available.

It is running in UserMode only (no realtime characteristics) and contains no further functionality than distributing the ADS Frames (e.g. no Port 10000, no ADS Secure). It is just used to route ADS frames locally between AdsServers and to/from remote ADS devices.

Implemented in asynchronous .NET Code it can be run in your own services/daemon, as standalone console application and also in your customized application.

Requirements

  • .NET 8.0, .NET 6.0 or .NET Standard 2.0 (e.g. >= .NET Framework 4.61) compatible SDK
  • No other System allocating the same port (e.g. a regular TwinCAT installation).
  • Installed Nuget package manager or Dotnet CLI.

Installation

Along with the deployment of the application where the TcpRouter is implemented, a valid Router / ADS configuration must be placed to specify the Local Net ID, the name and the default port of the Router system.

The preferred way to configure the system is with standard Configuration providers, which are part of the .NET Core / ASP .NET Core infrastructure.

See further information: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1

This enables common options for application configuration that can be used 'out-of-the-box':

  • Via the file appsettings.json
  • With the StaticRoutesConfigurationProvider (StaticRoutes.xml)
  • Using Environment Variables.
  • Command line arguments
  • etc.

The configuration has to be loaded during application startup and is placed into the 'TwinCAT.Ads.TcpRouter.AmsTcpIpRouter' class via constructor dependency injection and must contain the following information:

  • The name of the local System (usually the Computer or Hostname)
  • The Local AmsNetId of the local system as Unique Address in the network
  • Optionally the used TcpPort (48898 or 0xBF02 by default)
  • The static routes in the 'RemoteConnections' list.
  • Logging configuration.

Actually the configuration is not reloaded during the runtime of the 'TwinCAT.Ads.TcpRouter.AmsTcpIpRouter' class. Please be aware that the "Backroute" from the Remote system linking to the local system (via AmsNetId) is necessary also to get functional routes.

Example for a valid 'appSettings.json' file (please change the Addresses for your network/systems.)

{
  "AmsRouter": {
    "Name": "MyLocalSystem",
    "NetId": "192.168.1.20.1.1",
    "TcpPort": 48898,
    "RemoteConnections": [
      {
        "Name": "RemoteSystem1",
        "Address": "RemoteSystem1",
        "NetId": "192.168.1.21.1.1",
        "Type": "TCP_IP"
      },
      {
        "Name": "RemoteSystem2",
        "Address": "192.168.1.22",
        "NetId": "192.168.1.22.1.1",
        "Type": "TCP_IP"
      },
    ]
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console": {
      "IncludeScopes": true
    }
  }
}

Alternatively a "StaticRoutes.Xml" Xml File can configure the system equally. Don't forget to add the 'StaticRoutesXmlConfigurationProvider' to the Host configuration during startup (see FirstSteps below).

An example of the local "StaticRoutes.xml" is given here:

<?xml version="1.0" encoding="utf-8"?>
<TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\TwinCAT3\Config\TcConfig.xsd">
  <Local>
      <Name>MyLocalSystem</Name>
      <NetId>192.168.1.20.1.1</NetId> 
      <TcpPort>48898</TcpPort> 
  </Local>
  <RemoteConnections>
    <Route>
      <Name>RemoteSystem1</Name>
      <Address>RemoteSytem</Address> 
       
      <NetId>192.168.1.21.1.1</NetId>
      <Type>TCP_IP</Type>
    </Route>
    <Route>
      <Name>RemoteSystem2</Name>
      <Address>192.168.1.22</Address> 
       
      <NetId>192.168.1.21.1.1</NetId>
      <Type>TCP_IP</Type>
    </Route>
  </RemoteConnections>
</TcConfig>

Alternatively, the configuration can also be set via Environment variables.

PS> $env:AmsRouter:Name = 'MyLocalSystem'
PS> $env:AmsRouter:NetId = '192.168.1.20.1.1'
PS> $env:AmsRouter:TcpPort = 48898
PS> $env:AmsRouter:RemoteConnections:0:Name = 'RemoteSystem1'
PS> $env:AmsRouter:RemoteConnections:0:Address = 'RemoteSystem1'
PS> $env:AmsRouter:RemoteConnections:0:NetId = '192.168.1.21.1.1'
PS> $env:AmsRouter:RemoteConnections:1:Name = 'RemoteSystem2'
PS> $env:AmsRouter:RemoteConnections:1:Address = '192.168.1.22'
PS> $env:AmsRouter:RemoteConnections:1:NetId = '192.168.1.22.1.1'
PS> $env:AmsRouter:Logging:LogLevel:Default = 'Information'

PS> dir env: | where Name -like AmsRouter* | format-table -AutoSize

Name                                  Value
----                                  -----
AmsRouter:Name                        MyLocalSystem
AmsRouter:NetId                       192.168.1.20.1.1
AmsRouter:TcpPort                     48898
AmsRouter:RemoteConnections:0:Name    RemoteSystem1
AmsRouter:RemoteConnections:0:Address RemoteSystem1
AmsRouter:RemoteConnections:0:NetId   192.168.1.21.1.1
AmsRouter:RemoteConnections:1:Name    RemoteSystem2
AmsRouter:RemoteConnections:1:Address 192.168.1.22
AmsRouter:RemoteConnections:1:NetId   192.168.1.22.1.1
AmsRouter:Logging:LogLevel:Default    Information

Configuration Parameters

Name Description
Name Name of the local System/Device
NetId The AmsNetId of the local System/device
TcpPort The TCP port used for external communication (communication to the routes/RemoteConnections)
LoopbackIP This is the IPAddress, that is used by the TcpRouter for its Loopback Connections (in combination with the LoopbackPort. By default this is set to IPAddress.Loopback (127.0.0.1) and is only accessible from the local machine. If AdsClient/AdsServers should run seperated from the Router System, this LoopbackIP must be set to valid local IPAddress. Furthermore valid external addresses (where the AdsClients/AdsServer lives) must be specified via LoopbackExternalIPs or LoopbackExternalSubnet. Only those connections will be accepted
LoopbackPort Sets the TCP Port that is used for the loopback. The LoopbackPort defines the Loopback TcpEndpoints in combination with the LoopbackIP
LoopbackExternalIPs The Loopback externals are IPAddresses, that are allowed to use the Loopback connection. Use this IP list or specify alternatively the LoopbackExternalSubnet
LoopbackExternalSubnet Sets the loopback externals subnet. This is an alternative approach to set the allowed 'LoopbackIPs' for loopback communication. In docker/virtual enviroments often a whole subnet will be spanned
RemoteConnections Sets the list of remote Routes/Connections. This is the list of external devices which can be reached via the route.

Version Support lifecycle

Package Description .NET Framework TwinCAT Active Support
6.1 Package basing on .NET 7.0/6.0 net7.0, net6.0, netstandard2.0 >= 3.1.4024.10 [^1] X
6.0 Package basing on .NET 6.0 net6.0, netcoreapp3.1, netstandard2.0, net461 >= 3.1.4024.10 [^1] X
5.x Package basing on .NET 5.0[^3] net5.0, netcoreapp3.1, netstandard2.0, net461 >= 3.1.4024.10 [^1]
4.x Package basing on .NET Framework 4.0 net4 All X

[^1]: Requirement on the Host system. No version limitation in remote system communication.

[^2]: Microsoft support for .NET5 ends with May 8, 2022. Therefore it is recommended to update Beckhoff.TwinCAT packages from Version 5 to Version 6.

Migrate from ASP.NET Core 5.0 to 6.0

migrating to the latest .NET Microsoft .NET support lifecycle

First Steps

Example of starting the TcpIpRouter from a simple Console application with logging.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using TwinCAT.Ads.TcpRouter;

namespace TwinCAT.Ads.AdsRouterService
{
    class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureServices((hostContext, services) =>
                {
                    services.AddHostedService<RouterWorker>();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    // Uncomment to overwrite configuration
                    //config.Sources.Clear(); // Clear all default config sources 
                    //config.AddEnvironmentVariables("AmsRouter"); // Use Environment variables
                    //config.AddCommandLine(args); // Use Command Line
                    //config.AddJsonFile("appSettings.json"); // Use Appsettings
                    //config.AddStaticRoutesXmlConfiguration(); // Overriding settings with StaticRoutes.Xml 
                })
                .ConfigureLogging(logging =>
                {
                    // Uncomment to overwrite logging
                    // Microsoft.Extensions.Logging.Console Nuget package
                    // Namespace Microsoft.Extensions.Logging;
                    //logging.ClearProviders();
                    //logging.AddConsole();
                })
            ;
    }
}

public class RouterWorker : BackgroundService
{
    private readonly ILogger<RouterWorker> _logger;
    private readonly IConfiguration _configuration;

    public RouterWorker(ILogger<RouterWorker> logger, IConfiguration configuration)
    {
        _logger = logger;
        _configuration = configuration;
    }

    protected override async Task ExecuteAsync(CancellationToken cancel)
    {
        AmsTcpIpRouter router = new AmsTcpIpRouter(_logger, _configuration);

        //Use this overload to instantiate a Router without support of StaticRoutes.xml and parametrize by code
        //AmsTcpIpRouter router = new AmsTcpIpRouter(new AmsNetId("1.2.3.4.5.6"), AmsTcpIpRouter.DEFAULT_TCP_PORT, _logger);
        //router.AddRoute(...);

        await router.StartAsync(cancel); // Start the router
    }
}

Further documentation

The actual version of the documentation is available in the Beckhoff Infosys. Beckhoff Information System

Sample Code

Beckhoff GitHub RouterSamples

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  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. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Beckhoff.TwinCAT.Ads.TcpRouter:

Package Downloads
Beckhoff.TwinCAT.Ads.SystemServer

The Beckhoff.TwinCAT.Ads.SystemServer Package implements an TwinCAT System Service ADS Server (Port 10000) for usage in combination with the Beckhoff.TwinCAT.Ads.TcpRouter Package.
dsian.TwinCAT.Ads.Server.Mock

Mocking a TwinCAT Ads Server, for unit testing code with ADS read/write requests.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
6.1.298 138 11/7/2024
6.1.294 1,359 10/18/2024
6.1.290 879 10/7/2024
6.1.272 2,363 9/3/2024
6.1.266 406 8/28/2024
6.1.260 3,234 8/6/2024
6.1.244 2,647 6/20/2024
6.1.231 2,637 5/27/2024
6.1.203 8,641 3/15/2024
6.0.404 32 11/7/2024
6.0.380 113 8/6/2024
6.0.356 902 2/12/2024

### 6.1.222
Enh: Using Version 8.0 depends for .NET8 Builds
### 6.1.197
Fix: TcpIpRouter returns 'NoError' on disconnected AdsServer with WriteAsync, #175987
Enh: Replaces .NET7 dependency by .NET8
### 6.1.146
Enh: Changing Dependencies to .NET Assemblies from 7.0 --> 6.0 to Support Powershell Version 7.2 (LTS) and lower pressure for Custom Application Package updates.
### 6.1.66
Fix: TcpIpRouter doesn't receive external messages, after remove system restart (not reconnecting), #153764
### 6.1.60
Fix: Build process sometimes creates Version Number 1.0.0.0 for Package assemblies.
### 6.1.46
Breaking Change: Removing netcoreapp3.1 target because it is out-of Microsoft Support
Enh: Adding net7.0 target support
### 6.0.235
Fix: AdsServer instances doesn't unregister properly from Router on shutdown #121520, GitHub: https://github.com/Beckhoff/TF6000_ADS_DOTNET_V5_Samples/issues/41
### 6.0.212
Fix: AssemblyVersion and FileVersion of the Package Dlls are 1.0.0.0 for netcoreapp3.1 instead of 6.X. Netcoreapp3.1 Package dependencies were broken.
### 6.0.207
Fix: TwinCAT.Ads.TcpRouter.AmsTcpIpRouter.IsLoopbackSource returned wrong results, if external Loopback configurations are set.
### 6.0.164
Fix: Keep other Adapter TcpListeners running when one Adapter throws SocketException
### 5.0.490
Enh: Extended logging capabilities.
### 5.0.411
Fix: Use only one TcpClient connection for all AmsPorts to remote systems, fixes #46417
### 5.0.320
Enh: Updated Package Dependencies to 5.0 Versions

### 5.0.297

### 5.0.274-rc00
Fix: RouterConsole: Timout error with AdsRouterConsole on ReadWrite with large writebuffer (larger 1994 bytes) (ADOS 29672)

### 5.0.268-prerelease00
Fix: Use NullLogger (NullRerenceException when no Logger is specified)

### 5.0.1-preview.12
Enh: Added configurations for the eternal TcpPort, LoopbackIP, LoopbackPort to support several virtualization scenarios.

### 5.0.1-preview.11
Enh: Target change dotnet core 3.0 --> 3.1
Fix: TcpListener is not opened for external requests.

### 5.0.1-preview.10
Enh: Adding .NET Core 5.0 as platform

### 5.0.0-preview9
Enh: Null-Reference awareness in API Interfaces c# 8.0 (see [Nullable Reference Types ](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/nullable-reference-types))

### 5.0.0-preview8

### 5.0.0-preview7
Fix: Broken AdsRouter fixed.

### 5.0.0-preview6

### 5.0.0-preview5
Breaking Change: Removing the explicit .net core 2.0 platform support, .NET Standard 2.0 should be used instead.

### 5.0.0-preview4
Breaking Change: IAmsRouter.IsStarted replaced by IAmsRouter.RouterState and IAmsRouter.RouterStateChanged\
Enh: Using .NET Core Configuration and Logging providers for AmsTcpIpRouter class.\
Enh: Support of AppSettings.json for static routes and Router configuration\
Enh: Support of EnvironmentConfigurationProvider for Router configuration by Environment variables\
Enh: Implementation of StaticRoutesXmlConfigurationProvider for application configuration by 'classic' StaticRoutes.xml

### 5.0.0-preview3
Enh: Framework dependency changed net48 --> net48\
Enh: Adding Framework target netcoreapp2.0\
Enh: Optimizing Nuget Package dependencies

### 5.0.0-beta9
Enh: Referencing .NET Core 3.0 instead of .NET Core 2.2

### 5.0.0-beta6
Enh: Adding/Removing routes programatically via AmsTcpIpRouter.AddRoute() AmsTcpIpRouter.RemoveRoute