Quick Start

• Scripts that are executed inside BVMS applications

  The entry point for client scripts is the IClientApi. Client scripts are executed in the BVMS Operator Client. The entry point for server scripts is the IServerApi. Server scripts are executed by the BVMS Management Server.

• SDK Application

  The entry point of the Client SDK for applications is class RemoteClientApi. The constructor of this class tries to establish a connection to the BVMS Operator Client running on the computer with the given network address. The entry point of the Server SDK for applications is class RemoteServerApi. The constructor of this class tries to establish a connection to the BVMS Management Server running on the computer with the given network address.

  The RemoteClientApi and the RemoteServerApi provide access to so-called manager objects which deliver the actual SDK functionality. Each SDK method call may throw an SdkException. A SdkException will be thrown in cases of a usage error, an execution error or a program error.

  RemoteClientApi and RemoteServerApi both provide a ConnectionLostEvent which will be raised when the connection between the SDK application and the remote is broken. After this event the RemoteClientApi and RemoteServerApi as well as all SDK managers are invalid and must be instantiated again.

• Security considerations

Since BVMS version 6.0 the ClientScript class which contains the client scripts supports the Dispose Pattern. The Dispose() method of the ClientScript class is called, when the Operator Client application exits (terminates).

Dispose can be used to cleanup resources explicitly if needed.

The Dispose Pattern is supported for C# and VB.net client scripts (example code shows only C#).

[BvmsScriptClass()]
public class ClientScript : IDisposable
{
    private readonly IClientApi Api;
    private readonly ILog Logger;    

    public ClientScript(IClientApi api)
    {
        this.Logger = LogManager.GetLogger("ClientScript");
        this.Api = api;        
    }

    public void Dispose()
    {
        // Use this method to cleanup any resources here (consider fully
        // implementing the Dispose pattern).
        // For example, stop and dispose any started timers. Ensure that
        // all threads that were started are stopped here.
        // DO NOT BLOCK in this method for a very long time, as this may
        // block the applications current activity.
    }
}

Since BVMS version 5.5 the ServerScript class which contains the server scripts supports the Dispose pattern that allows explicitly cleanup of resources. For this, the ServerScript class implements the IDisposable interface (see C# sample below).

The Dispose() method of the ServerScript class is called by the Management Server, when a new configuration gets activated or when the Management Server stops. This enables stopping threads and timers at a defined point in time.

The Dispose Pattern is supported for C# and VB.net server scripts (example code shows only C#).

[BvmsScriptClass()]
public class ServerScript : IDisposable
{
    private readonly IServerApi Api;
    private readonly ILog Logger; 

    public ServerScript(IServerApi api)
    {
        this.Logger = LogManager.GetLogger("ServerScript");
        this.Api = api; 
    }

    public void Dispose()
    {
        // Use this method to cleanup any objects here (consider fully
        // implementing the Dispose pattern).
        // For example, stop and dispose any started timers. Ensure that
        // all threads that were started are stopped here.
        // DO NOT BLOCK in this method for a very long time, as this may
        // block the activation process of a changed configuration.
    }
}

Many SDK functions can throw an exception of type SdkException (or a sub-type), for indicating failure. When a BVMS Management Server or an Operator Client calls a script, it catches any exception that is thrown by the script or by an operation called by the script. BVMS does not notify or inform users of the system about any exception caught from a script. Bosch recommends writing each script in a way that it catches and handles possible exceptions thrown by any of the functions it calls or operations it performs. The script can then control whether and how to indicate such failure to users or administrators of the system.

When a script starts timers or when it uses thread-pool threads for performing tasks, consider the following: If the script-code that is executed on a timer thread or on a thread-pool-thread throws an exceptions, BVMS is not able to catch this exception. It depends on the behavior of the employed timer class or the thread-pool class whether an unhandled exception will cause the application to terminate. An unhandled exception, raised in the scope of script code, can terminate the host application (Management Server or Operator Client). The script programmer is responsible to catch and handle all exceptions that might be raised by any operation performed or called on a timer thread or thread pool thread.

Important

Bosch recommends avoiding the usage of timer-callbacks or thread-pool threads in server scripts, to ensure the integrity and availability of the Management Server. If you need timers or thread-pool threads for implementing the use case at hand, Bosch recommends putting such code in a separate SDK application. This ensures that an unhandled exception terminates only the SDK-application but not the BVMS Management Server.

1. Run the BVMS Setup on the development workstation and install the BVMS SDK. This will install the required SDK assemblies into the global assembly cache and into the folder "<BVMS SDK Installation Directory>\bin\". The later location can be used for referencing the assemblies at compile time.

2. Add the following assembly references (from folder "<BVMS SDK Installation Directory>\bin\" ) to the project that represents the SDK application:

   • Bosch.Vms.SDK.dll

   Note
   This assembly need to be referenced on the development workstation to allow compiling the SDK application. The assembly should not be copied together with the SDK application to the target workstation (see deploying below).

Since BVMS version 10.0.1 classes RemoteClientApi and RemoteServerApi support the Dispose pattern that allows to close the communication channel. After the communication channel has been closed by disposing the RemoteServerApi or RemoteClientApi a new instance of the RemoteServerApi or RemoteClientApi needs to be created. If the communication to the BVMS Management Server has been lost, then a new instance of the RemoteServerApi needs to be created. If the communication to the BVMS Operator Client has been lost, then a new instance of the RemoteClientApi needs to be created. Please note that a configuration activation also leads to a communication loss to the BVMS Management Server with the consequence that a new RemoteServerApi needs to be instantiated.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Bosch.Vms.SDK;

namespace SdkSample
{
    public class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var remoteServerApi = new RemoteServerApi("localhost", "Admin", "");
                remoteServerApi.ConnectionLostEvent += OnConnectionLost;

                var virtualInputManager = remoteServerApi.VirtualInputManager;
                IList<DeviceInfo<Device>> virtualInputs = virtualInputManager.GetVirtualInputInfoList();

                remoteServerApi.Dispose();
            }
            catch (SdkException exception)
            {
                Console.WriteLine("An SDK error has occured: " + exception.ToString());
            }
        }

        private static void OnConnectionLost(object sender, EventArgs e)
        {
            // from here on the current instance of the RemoteServerApi can't be used anymore.
            // A new instance must be instantiated.
            var remoteServerApi = sender as RemoteServerApi;
            if (remoteServerApi != null)
            {
                remoteServerApi.ConnectionLostEvent -= OnConnectionLost;
                Console.WriteLine("Connection lost.");
            }
        }
    }
}

On the target workstation, run the BVMS Setup and install the BVMS SDK. This will install the previously referenced SDK assemblies into the global assembly cache. At runtime, the SDK application will then use the SDK assemblies from the GAC.

Important:

When the BVMS is upgraded to a newer version, then the BVMS SDK of the newer version needs to be installed on all workstations where SDK applications have been deployed, because the SDK assemblies can only communicate to a BVMS of the same version. This is the reason why the BVMS setup program offers the SDK as an independent installation option.