Skip navigation
All Places > PI Developers Club > Blog > 2015 > January
2015

2014: We had a very exciting year 2014. We moved from our home of 6 years (vCampus) to our shiny new platform PI Developers Club in December. In the meantime we integrated with the bigger PI community, beefed up our development support crew, and opened up content to everybody in the community. We are confident these changes will help us grow the developer community even further and also integrate better with the broader PI System users community in PI Square. In 2014 we handled more than 900 new discussion threads. Looking forward to reaching for higher targets in 2015.

 

totalforumdiscussionsreport-2014.jpg

2015: Enabling development of applications for the PI System is a high priority for OSIsoft. We will continue the trend that was started last year and add more valuable pieces to this ecosystem.

 

  • PI Developers Club: we will continue nurturing and improving the features of our program, PI Developers Club. Customers on active SRP can enjoy specialized support on phone and email for their development-related questions. Share your other improvement ideas with me.
  • App Exchange: we will start looking into a more formal way to exchange applications in the community. There is a tremendous amount of energy and skill in PI Developers Club. We want to make it as easy as possible to build and share useful applications with the community. In 2015 we will talk to people from the technical and business sides and investigate best practices. Please share your thoughts on this topic with me! Tell me what would make it easier or more profitable for you to build applications for PI System. We love to know how we can help you do well building and distributing such applications!
  • Development PI System in the cloud: Cloud is not only a cost saver or matter of convenience; it fosters growth. We have already started investigating ways to offer PI Developers Club software package (aka. your development PI System) in the cloud. The idea is to offer a new way for developers to spawn a full development PI System in a matter of minutes. Expect to hear more on this issue in 2015 from us. Note that this will be in addition to the on-premise version of the development PI System.
  • UC TechCon 2015: in Users Conference 2015 we will start the technical conference in its new format (formerly known as vCampus Live!). We call it UC TechCon. We will have several rich technical hands-on sessions for developers and system admins to learn and connect with their peers. The good old Programming and Security hackathons are back; the theme of the Programming hackathon this year is Internet of Things (IoT). You can already register for the event.

 

I am very excited about the year ahead of us! 2015 will be a great year for the PI Community and, in particular, PI Geeks. Now that the new platform is in place it's time to innovate and build more apps together!

AF 2.x Clients contain an executable named RegPlugIn.exe used for registering plug-in assemblies, typically located in the \PIPC\AF directory. There are currently 4 types of PI AF Plug-Ins: DataReference, DeliveryChannel, TimeRule, and AnalysisRule. In addition, there may be support assemblies that are required for the implementation of the AF Plug-Ins or to provide translated resources for different languages. Starting in AF 2.1, support (or dependent) assemblies can be loaded by RegPlugIn as well.

 

The goal of this blog is to walk you through a simple example on the caveats of using RegPlugIn to register support assemblies. The following examples are tested with PI AF 2014 R2.

 

Background on the RegPlugIn Utility

 

The simplest way to register an AF Plug-In is to run the RegPlugIn utility located in the \PIPC\AF folder:

RegPlugIn Path\To\MyPlugIn.dll

which uploads the plug-in to the AF server. When an AF client (e.g. PI System Explorer) needs the Plug-In, it will download the Plug-In on to the client computer in the %ProgramData%\OSIsoft\AF\PlugIns directory.

 

Path

.NET of the Plug-In

Plug-Ins

PlugIns (root)

.NET 3.5

version Shipped with AF client

PlugIns\4.0

.NET 4+

version Shipped with AF client

PlugIns\x.x.x.x

.NET 3.5

dll version of the custom plug-In

PlugIns\4.0\x.x.x.x

.NET 4+

dll version of the custom plug-In

 

The above applies for plug-ins targeting “Any CPU”. If the plug-in specifically targets “x86”, it will be placed under the x86 folder under its respective directory; similarly, plug-ins targeting “x64” will be placed under the x64 folder.

 

After registering the plug-in, you can list the registered assemblies by running:

RegPlugIn /List


There are other parameters (e.g. you can specify the PI AF server) available for the RegPlugIn utility. For examples and parameters, I recommend checking out the “Managing plug-ins” section in the PI System Explorer User Guide.

 

My First Attempt at Registering a Support Plug-In (Do not Follow!)

 

In this example, I will use a custom delivery channel that I developed to output alerts at specific Twitter handle (TwitterDeliveryChannel.dll). As part of the project, I am referencing a support assembly that serves as a .NET wrapper to the Twitter API (LinqToTwitter.dll).

 

After compiling the class library, I am ready to register the delivery channel plug-in. I copied both assemblies from my development server to one of my AF client machines, under C:\Users\dng\Documents. After navigating to the \PIPC\AF directory, I first register my main Delivery Channel plug-in (TwitterDeliveryChannel.dll):

RegPlugIn “C:\Users\dng\Documents\TwitterDeliveryChannel.dll”


I then register the support assembly (LinqToTwitter.dll):

RegPlugIn “C:\Users\dng\Documents\LinqToTwitter.dll” /own:TwitterDeliveryChannel.dll


The /own or /owner parameter is used to specify the name of the owner assembly during support assembly registration. Alternatively, you can register both assemblies at the same time:

RegPlugIn “C:\Users\dng\Documents\TwitterDeliveryChannel.dll” “C:\Users\dng\Documents\LinqToTwitter.dll” /own:TwitterDeliveryChannel.dll

 

The following message shows that my assembly has been successfully registered. Note that the support assembly is registered at the relative path (“Users\dng\Documents\LinqToTwitter.dll”):

img1.png

This can be further confirmed by running RegPlugIn /List:

img2.png

However, when I tried to use my new Twitter Delivery Channel on a client machine, I encountered this error:

img3.png

On the client machine, the TwitterDeliveryChannel.dll is downloaded to the %ProgramData%\OSIsoft\AF\PlugIns\1.0.0.0 directory (version of the dll). Interestingly, the LinqToTwitter is located at %ProgramData%\OSIsoft\AF\PlugIns\1.0.0.0\Users\dng\Documents.

 

When I run Process Explorer to look at which directories PI Notifications is trying to find the supporting assembly (LinqToTwitter.dll):

img4.png

It looks like PI Notifications Manager is only looking for the supporting assembly at the PlugIns (root) and PlugIns\version directories. Since my supporting assembly is located at PlugIns\1.0.0.0\Users\dng\Documents, it cannot be found or loaded.

 

When (and how) are the assemblies loaded?

 

When a PI AF SDK client needs the plug-in (e.g. creating a delivery channel end point), it will download the necessary dll (e.g. TwitterDeliveryChannel.dll) from the AF server if the client does not have the plug-in with the same (or higher) version. It then calls loadLibrary to load the dll from the directory path according to the dll specifications (e.g. .NET 3.5 or 4+, x86/x64, and version).

 

On the other hand, PI AF SDK does not load the supporting dll (e.g. LinqToTwitter.dll) directly. Microsoft runtime (or .NET framework) is responsible to load any referenced dll when it is required. Since my custom delivery channel does not explicitly call loadLibrary to load the required dll by specifying the relative path, the runtime will search in the GAC and through the default search path. Since Users\dng\Documents is not in the search path. The support dll is not loaded.

 

RegPlugIn uses the same path for both the input and output file location for supporting assemblies

 

When using RegPlugIn to register an AF plug-in, the file name (defaulted to current directory) or the path name is needed to specify where the dll is that you are trying to register. For the main plugin dll, the location of the plug-in in the client machine is determined strictly by the dll specifications.

 

However, for support dlls, the file path argument is used for both input and output specification. The file path is used by RegPlugIn to find where the dll is located, as well as to specify the relative path where the supporting assembly will be downloaded on the client machine (in this case, Users\dng\Documents). I was therefore implicitly specifying the relative output path when I was trying to register the supporting assembly!

 

How to Register Supporting Plug-Ins? (A Better Way)

 

The easiest way to register support assemblies is to put them in the same directory as the main plug-in dll. This way, they will be downloaded to the same directory onto the AF client machine. Rather than specifying the input path for the dll as the input arguments for RegPlugIn.exe, navigate to the directory containing the dlls and run:

“%pihome%\AF\RegPlugIn.exe” TwitterDeliveryChannel.dll LinqToTwitter.dll /own:TwitterDeliveryChannel.dll


Then, use RegPlugIn /list to verify that the plug-in and its supporting dlls are put in the same directory:

img5.png

You can also verify on the client machine that the plugin and its supporting dlls are downloaded into the expected directory.

 

Note that the search path could be modified by the %path% environment variable or through the application config file. The directory where the calling program or dll is loaded is also path of the search path. You can also hardcode the relative directory path to load the supporting dll. However, I find the easiest way to register support assembly is to put them in the same directory as the main plug-in dll.

 

Conclusion

 

When invoking RegPlugIn, set the default directory to where the input dlls are located and explicitly specify the path of RegPlugIn.exe. I hope you find this blog post helpful!

Filter Blog

By date: By tag: