Easy test script for PI Web Services

Blog Post created by mhamel Employee on Jan 24, 2012

One of the common things I have noticed with Web Services is that after you installed them you need a quick way to test them to say they work or not. As PI Web Services responds to web queries using the Simple Object Access Protocol (SOAP) related data from the PI Server and/or the PI AF Server, you need to test the pathways. Many components are involved during the installation: configure the virtual application on the Web Server (IIS), ASP.NET, application pool, web.config, PI SDK, AF SDK, security, etc. Also, other elements can come into the game: questions related to Active Directory forest, domain(s) and workgroup, and the network routes and filters. Looking at all these details, I know many things can go wrong. So, my focus is starting from a basic scenario to test the main components to assess a minimal set of things. I learned with Web Services that the more security layer you add the more difficult it becomes. Anyway, your first idea should be testing that each components can communicate and close the loop. The higher level of security will come up at a later time.


The first test to do is to try to open a connection on your Web Server, then try to reach the folder of your virtual application (here it is the PI Web Services). Try to retrieve the service descriptors (WSDL) which will be returned when you query the service handler at this URI: http://<server>/PIWebServices/PITimeSeries.svc?wsdl. If you got success until that part you need to test a specific method provided by this service but you will need to either code your application or use a Web Service functional tool. Both of these solutions require time or an installation process that would leave a footprint on the machine. What you want it's an easy solution that could say my installation is working from A to Z. This takes more sense if you are performing the installation at a customer's site on production assets. There are a lot of chances they would refuse you the rights to install other pieces of software that might affect the server.


An easy solution is possible for you and it is a Powershell script. For those of you which would not be familiar with Powershell, I propose you a nice and short description coming from Wikipedia which is: "Windows PowerShell is Microsoft's task automation framework, consisting of a command-line shell and associated scripting language built on top of, and integrated with the .NET Framework. PowerShell provides full access to COM and WMI, enabling administrators to perform administrative tasks on both local and remote Windows systems."


The use of scripts give you strong advantages, as it does not install a codebase on the machine and it can be easily modified to suit your needs. You will need Powershell version 2.0 and later to achieve this. The version 1.0 of Powershell was based on .NET Framework 2.0 only but the later version was ported to use the .NET Framework 3.5. As we are communicating with Web Services implementing the Windows Communication Foundation (WCF) which was introduced with the .NET Framework 3.5 we need Powershell version 2.0. For an easy introduction, I will cover only the basics to connect using basic bindings (meaning with no security), other bindings would be part of a later post.


The script contains two cmdlets: PIWS-TestGetPIArchiveDataWithSOAP and Format-XML, the first one is to send a SOAP message to PI Web Services via a WebClient object and receive the answer, the second is process for processing the XML returned string. Starting from cmdlet PIWS-TestGetPIArchiveDataWithSOAP, we need to create a Webclient object to communicate with the PI Web Services, a WebHeaderCollection object to define the content of the message and the SOAP action, and finally an XML message that will contain all the necessary information for the Web Services. Using the [string]::Format method, you can easily manipulate an XML template with the different arguments to replace within to form your message. The final stage is to post your message to PI Web Services and wait for an answer. This is done as a synchronous process. The returned XML is formatted with the second cmdlet and output to the console. The PIWS-TestGetPIArchiveDataWithSOAP cmdlet is called with the last instruction which is part of the main of your script. You need to pass the endpoint, the URI of PI Web Services, the item which is a valid path, the start and end time, and the number of values to return for interpolated values. Save your file with the name PIWS-TestGetPIArchiveDataWithSOAP.ps1.


To utilize your script, you will need to open a command prompt and call powershell or call powershell directly from the Run command. As a very important step, you will need to unlock the policy for using this type of script by invoking the cmdlet: Set-ExecutionPolicy RemoteSigned at the Powershell prompt. Afterward, you can invoke your script wherever you saved it by simply typing its full path and name. If you receive errors directly inside the Powershell session, it means something is not configured properly somewhere. Otherwise in case of success you will receive a screen that looks like the following.





The same error message will be sent thorough Powershell then if it was your Visual Studio environment. Try different paths involving PI AF to test this part of the configuration. After successful tests from the machine, you can copy your script to a client machine and see if it still works from there. This completes the testing workflow for basic bindings.







Get a copy of this script from this link (as publishing Powershell scripts is not nice on the Web). Stay tune for later blog posts and a white paper to test all other Web methods offered by PI Web Services. Did you use scripts of your own before, share some thoughts with me by replying to my blog.



I have added a link to a new version of the script here. It fixes the PIArcManner object parameters to handled properly.