Text preview for : TPI.NET_and_PlugIn_Documentation.zip part of Tektronix TPI.NET and PlugIn Documentation Tektronix TLA714 software TPI.NET_and_PlugIn_Documentation.zip
Back to : TPI.NET_and_PlugIn_Docume | Home
TLA Plug-In Design Guide
October 9, 2009
1 Introduction ............................................................................................................................... 2
2 Implementing Plug-Ins .............................................................................................................. 4
2.1 Software Implementation .................................................................................................. 4
2.2 Plug-In User Interfaces ..................................................................................................... 6
2.3 Generic, or "Tool," Plug-Ins............................................................................................... 8
2.4 Data Window Plug-Ins....................................................................................................... 8
2.5 Data Source Plug-Ins ...................................................................................................... 10
October 9, 2009 Page 1 of 12 TLA Plug-In Design Guide
1 Introduction
Plug-Ins Defined
Plug-ins are managed .NET classes that implement the IPlugIn interface or an interface derived
from it. The IPlugIn interface is defined by the TLA application software. Since plug-ins must
implement specific interfaces defined by the application, they have a subset of known properties,
methods, and events. The application uses these known members to initialize and interact with
plug-in instances. In turn, plug-in instances extend the functionality of the TLA application.
As managed types, plug-ins implementations are contained within assembly DLLs. A plug-in
class becomes "plugged-in" when the assembly containing it is placed into the
TLA700\System\PlugIns directory of the application installation.
Development Overview
Plug-ins are developed by creating managed classes that implement specific .NET interfaces.
Before a plug-in can be fully implemented, the following items are needed by the developer:
A .NET enabled compiler, Visual Studio .NET for example.
A copy of TlaNetInterfaces.dll.
All plug-in developers must use .NET-enabled compilers, which can create assemblies with code
that executes under the Common Language Runtime. The NET interface specifications for the
TLA application have been written with the expectation that plug-ins will be developed most often
with Microsoft's Visual Basic, C#, or Managed C++.
In order to create a plug-in class, the developer must have a copy of TlaNetInterfaces.dll, which is
a DLL present in every V5.0 TLA software installation. It is an assembly that contains metadata
for all plug-in interfaces and TPI.NET types. The file holds the compiled definitions of all .NET
types that are currently described in "DotNet Interfaces UIS.doc." Both the TLA application and
all plug-in assemblies are compiled using references to the metadata in this assembly.
TlaNetInterfaces.dll serves a purpose similar to that of a header file. It holds the definitions of
types that will be used by multiple projects, including projects that are compiled separately. Since
plug-in code must be programmed and compiled using metadata from this assembly,
TlaNetInterfaces.dll is provided to all plug-in developers.
Version 5.0 of the TLA application will recognize three kinds of plug-ins: Generic plug-ins, data
window plug-ins, and data source plug-ins. These plug-ins implement IPlugIn,
IDataWindowPlugIn, and IDataSourcePlugIn respectively; and a particular plug-in distinguishes
its itself to the TLA by the interfaces that it implements. The application determines which
interfaces a plug-in implements by examining its metadata, specifically by looking at the Type
object associated with the plug-in class. To qualify as a plug-in, a class must implement IPlugIn.
Generic plug-ins directly implement this base interface and no derived interfaces. Data window
and data source plug-ins implement specialized interfaces derived from IPlugIn.
Plug-in instances are expected to need relatively detailed information about System setup and
module data. This information is supplied by the TPI.NET programmatic interface, which exposes
major elements of a TLA as a hierarchy of managed objects. When plug-ins are initialized, they
are given a reference to an ITlaPlugInSupport object, which is at the very top of the TPI.NET
hierarchy. This means that all plug-in objects are also in-process TPI.NET clients, and plug-in
developers have access to all facilities of TPI.NET without needing to write any special code to
connect to the programmatic interface.
October 9, 2009 Page 2 of 12 TLA Plug-In Design Guide
Installation
A plug-in is installed by copying the assembly that contains it into the TLA700\System\PlugIns
directory or one of its subdirectories. At start-up the application searches the PlugIns directory
and all its subdirectories for .NET assemblies. The metadata in each assembly is examined; and
if the assembly contains any classes that implement IPlugIn, those classes are added to a
runtime list of installed plug-ins. Installing a plug-in class does not necessarily mean that any
objects of that class will be instantiated.
Instantiation
The TLA application is responsible for instantiating plug-ins at appropriate times. These are the
situations in which new plug-in instances are created:
The plug-in class attributes indicate that an instance should be automatically created
when the application starts up.
The user requests a new instance from the application UI.
A TPI.NET client requests a new instance by calling ITlaSystem.CreatePlugInInstance.
In the above situations, the application calls Assembly.CreateInstance to create instances of
plug-in classes. Plug-ins created this way are instantiated using their default constructor, so every
plug-in class must implement a constructor that takes no arguments. Plug-ins are not required to
take any specific action within their default constructors, but the constructor must exist in order to
instantiate the object. Once a plug-in is instantiated, the application guarantees that the
IPlugIn.Initialize method will be called before any other member methods are called.
A serializable plug-in that implements ISerializable can also be re-instantiated using its
deserialization constructor in the following situations.
Saved plug-ins are deserialized when the saved system that contains them is restored.
A saved data window plug-in can be deserialized when a user selects it from the Load
Data Window dialog.
A saved data source plug-in can be deserialized when selected from the Add Data
Source dialog.
Plug-In save/load is described inside section 2.1. Save and restore of data source plug-in data is
described inside section 2.5.
Samples
The same CD that contains this document also contains sample code for a generic tool plug-in
and a simple data window plug-in. These samples are presented in three separate languages
supported by Microsoft Visual Studio .NET 2003: Visual Basic .NET, C#, and C++ with managed
extensions. Each sample has a Visual Studio 2003 solution file that can be opened and built to
produce a working plug-in. To be used, the plug-in needs to be installed in the following directory
of a TLA software installation:
C:\Program Files\TLA 700\System\PlugIns
The tool plug-in sample is contained in the following directories:
TPI.NET and PlugIn Documentation\Tool PlugIn Samples\CSharp Tool PlugIn,
TPI.NET and PlugIn Documentation\Tool PlugIn Samples\VB Tool PlugIn,
TPI.NET and PlugIn Documentation\Tool PlugIn Samples\CPP Tool PlugIn.
The data window plug-in sample is contained in the following directories:
TPI.NET and PlugIn Documentation\Data Window PlugIn Samples\CSharp Data Window PlugIn,
TPI.NET and PlugIn Documentation\Data Window PlugIn Samples\VB Data Window PlugIn,
TPI.NET and PlugIn Documentation\Data Window PlugIn Samples\CPP Data Window PlugIn.
October 9, 2009 Page 3 of 12 TLA Plug-In Design Guide
To use the sample projects, copy the directory contents of the desired sample from the CD into a
directory on the computer that contains your development environment.
Please note that all the Visual Studio projects contain a pre-release version of the latest
TlaNetInterfaces.dll assembly. If you experience any runtime problems related to
TlaNetInterfaces.dll, you might get better results by compiling the samples, and any other
TPI.NET clients, with the final release version of this assembly. The release version is always
installed in the following directory of your TLA application software:
C:\Program Files\TLA 700\System\TlaNetInterfaces.dll
2 Implementing Plug-Ins
This section describes how to implement IPlugIn so that the resulting class can be installed for
use with the TLA application. The techniques and requirements presented in this section are
applicable to developing all kinds of plug-ins. Implementation specifics for the three different kinds
of plug-ins are described in later subsections.
2.1 Software Implementation
Minimum Requirements
The following list summarizes the minimum requirements for a plug-in class implementation.
The class must be a managed .NET class, meaning it's code executes under the
management of the Common Language Runtime.
The assembly containing the class implementation must be installed in the
TLA700\System\PlugIns directory or in a subdirectory.
The class must implement IPlugIn or implement an interface derived from IPlugIn.
The class must have public visibility.
The class must have been compiled with a copy of TlaNetInterfaces.dll whose version
number is less than or equal to the version of TLA700.exe.
The class must have a default constructor.
The TLA application will be able to find, recognize, and instantiate a plug-in class that meets all
the above requirements.
Custom Attributes Applicable to Plug-Ins
TlaNetInterfaces.dll defines two custom attributes that plug-in developers can apply to the classes
they design. Note that these attributes are applied to plug-in classes and not to instances of
classes. These attributes are used to describe a plug-in class to the TLA before any objects of the
type are created.
PlugInIdentityAttribute is used to specify the name and icon that the TLA should use to represent
a plug-in class to users. The name and icon will appear in the TLA UI in places where the user
can create instances of plug-ins. The kind of plug-in determines where the name appears in the
application UI. This attribute is required for any kind of plug-in to be instantiated from the UI.
When PlugInIdentityAttribute is absent from a plug-in class, the plug-in will not appear in any
menus, toolbars or dialog boxes.
PlugInInstantiationAttribute: Developers use this attribute to control whether the TLA
automatically creates an instance at startup and whether the TLA will allow more than one
instance of the plug-in to be created.
October 9, 2009 Page 4 of 12 TLA Plug-In Design Guide
Implementing IDisposable and IValidity
IPlugIn derives from IDisposable, which is a standard interface defined by the .NET Framework.
IDisposable has only one method, namely the Dispose method. When this method is called on an
implementing class, it must free all its unmanaged resources, such as file handles, device
contexts, or unmanaged memory. In the implementation of its own Dispose method, a plug-in
must call Dispose on all the visual components it has instantiated, such as Form and Control
objects.
In addition to IDisposable, plug-ins must also implement the IValidity interface defined in
TlaNetInterfaces.dll. This interface has two properties and an event. The IsValid and IsGarbage
properties indicate whether the object is valid for use by other objects. When either of these
properties change, the implementing object must raise the IValidity.ValidityChanged event. The
TLA application subscribes to the ValidityChanged event, and removes any plug-in whose IsValid
property has become false. In addition the TLA calls Dispose on any object that it removes from
the system.
Plug-in implementations need to coordinate IValidity with IDisposable. Whenever a plug-in is
disposed, it must set IsValid to false, set IsGarbage to true, and raise the ValidityChanged event.
Multi-threading
Plug-ins are expected to be single-threaded. If a plug-in attempts to be multithreaded, it must
protect against deadlock. Any call from the TLA application, including event callbacks, must
complete without blocking the thread on which the call is made.
Plug-In Deletion
Plug-ins will sometimes need to delete themselves from the system. For example if a data
window plug-in is closed by the user, it is reasonable for the plug-in to remove itself from the
system.
The recommended way for a plug-in to delete itself is by changing its IsValid property to 'false',
then raising its ValidityChanged event. The TLA application will respond to the event by removing
the plug-in from the system.
Implementing Plug-In Save/Load
The V5.0 TLA application supports saving and loading the state of plug-ins to and from a .tla
setup file. Supporting save/load is optional for plug-in classes. A plug-in supports being saved
and loaded by both implementing the .NET Framework interface ISerializable and applying the
Serializable attribute to the implementation class.
To properly implement a serializable plug-in, the class must fulfill these requirements:
The SerializableAttribute must be applied to the plug-in class.
The class must derive from ISerializable and implement this interface.
The class must implement the method GetObjectData in a way that is consistent with the
.NET Framework's defined semantics for that method
It must implement a deserialization constructor with the signature
Constructor(SerializationInfo info, StreamingContext context). This constructor is in
addition to the default constructor required of all plug-in classes.
From the plug-in perspective, a save is simply a call made on its implementation of
GetObjectData(). The plug-in is expected to place its state into a serialization stream by calling
SerializationInfo.AddValue(). The SerializationInfo object is provided as one of the
October 9, 2009 Page 5 of 12 TLA Plug-In Design Guide
GetObjectData() arguments. Note that acquisition data for a data source plug-in should not be
saved when GetObjectData() is called. Data from data source plug-ins are saved using a
separate mechanism as described in section 2.5 on data source plug-ins.
A plug-in is restored by instantiation of the class through its deserialization constructor. The plug-
in is expected to deserialize its model state using the SerializationInfo object provided as a
deserialization constructor argument. A data source plug-in should not attempt to de-serialize
acquisition data at this step