PowerShell & BlackBerry Web Services (Part 1 – Preparation)

by

UPDATE: I’ve made an update to this posting for BlackBerry Enterprise Server 10.1. See the posting here.

If anyone is running BlackBerry Enterprise Server 5.0.3 or later, you should be aware that the new web front end also includes what Research in Motion is calling “BlackBerry Web Services.” This allows you to use Java (ew), C# (see previous), or another Web Service-aware system to interface with the BlackBerry Enterprise Server installation directly.

Now, I’m a huge PowerShell geek. I try to use it for just about everything. If I could, I’d write a script to wake me up, make toast, and drive me to work. Since that’s not really in the cards, I have to go for something else.

There are some gotchas in the process, so I’m going to go over what I did step-by-step to get this to work for me.

I started out with the basics according to Research In Motion. In the BlackBerry Web Services for Enterprise Administration Getting Started Guide for Microsoft .NET Developers (PDF Download), RIM tells us how to generate the necessary proxy files to have access to the objects defined in the web service. What they don’t tell us is how to do this for anything except C#.

Since RIM publishes the Web Service as two WDSL’s instead of one, we can’t just use the New-WebServiceProxy in PowerShell (much to my chagrin). So I needed to find another way. It turned out this way required that I get pretty creative in handling the Web Service files. I need to start by downloading the definition files.

Step 1) Download the two BlackBerry WSDL Files

  • https://[BlackBerryServerFQDN]/enterprise/admin/ws?wsdl
  • https://[BlackBerryServerFQDN]/enterprise/admin/util/ws?wsdl

I found that downloading the WSDL’s was harder than I anticipated. I started by trying to just copy them from the web pages that were created, but the content isn’t correct because of the +/-‘s that Internet Explorer puts into the formatting. Then I tried a File, Save As… and saved the XML files, but they never actually saved. In the end I just cheated like a big boy. I copied the contents of the WSDL’s down to the Notepad and did a global find/replace for ” – <” and replaced it with “<” – problem solved. I saved the two files as “BWSService.wsdl” and “BWSUtilService.wsdl.”

After I had the files down, I scanned through them to see what they contained. I wasn’t overly surprised to see that they were full of information that was practically greek to me, but I decided to run through each of them to see what was what. All the way near the bottom was a parameter for the SOAP Address Location. I was quite surprised that it returned the FQDN of the BlackBerry Administration Server, but not the pool name. We run a Highly Available BlackBerry Administration Service (actually we run 4 of them between two data centers), and although the HA pool name was defined everywhere that I could see these two files still returned an individual cluster member’s name. I put a pin in that and went on. Boop - put a Pin in it.

Step 2) Generate the BES Proxy C# File

I tried to use the process in the above BlackBerry document (Page 10 in the PDF) to generate the “Proxy.cs” file, but I ran into all kinds of problems. I’m sure that it would have worked if I imported the Self-Signed SSL Certificate from the BlackBerry servers, but I never install certificates. Sorry – just my thing.

The wsdl.exe program exists exactly where it should according to the document, and then it was just a matter of plugging in my variables. It looked like this:

“C:Program Files (x86)Microsoft SDKsWindowsv7.0Abinwsdl.exe” /sharetypes /o:C:ScriptsBlackBerryBesProxy.cs C:ScriptsBlackBerryBWSService.wsdl C:ScriptsBlackBerryBWSUtilService.wsdl

That threw an error because the WSDL files weren’t downloaded from a web server (Error: The /sharetypes switch cannot be used with a WSDL contract or an XSD schema, please use collection of urls and .discomap documents.). Well, crap on toast. Good thing I have a web server where I can just put stuff. Smile

I copied the files over to a web server that I operate.

“C:Program Files (x86)Microsoft SDKsWindowsv7.0Abinwsdl.exe” /sharetypes /o:C:ScriptsBlackBerryBesProxy.cs /namespace:BesWebServices http://www.kmsigma.com/files/BWSService.wsdl http://www.kmsigma.com/files/BWSUtilService.wsdl

Eureka! I’ve got a C# Script file now! What’s next? It’s time to go back and do something about that pin. Boop - put a Pin in it.

Step 3) Edit the C# File

If your BesProxy.cs file generated anything like mine, then at lines 148 and 28454 you should see a reference to the BlackBerry Server FQDN. If you used my files then it will look EXACTLY like mine (duh!).

Open the file in your favorite editor and replace the FQDN with either the name of your BlackBerry Server running the BAS Service or the pool name of the BAS Servers. Save the file.

We’re almost ready to actually start scripting!

Step 4) Compile the C# to a DLL

This is a very easy step. The only tricky part is finding which csc.exe that you want to use on your computer. I elected to go with the version included with the .NET Framework 2 because that’s the same version of wsdl.exe. I don’t think it matters, but I like the consistency.

In theory, you do not HAVE to compile the C# File to a DLL, you can actually call the C# Directly from PowerShell, but there is a problem or two with that, like the proper assemblies have to be loaded prior to importing the types from the C# file. I like the DLL option better, so that’s what I did.

“C:WindowsMicrosoft.NETFrameworkv2.0.50727csc.exe” /target:library /optimize+ /out:C:ScriptsBlackBerryBesProxy.dll C:ScriptsBlackBerryBesProxy.cs

If you get no errors, then you should have a brand new DLL file in place.

Part 2 of this post will show you how to use this new DLL with the code samples from the RIM document.