Vorstellung "PowerIPS.dll" Die kleine .net Klasse zur Verbindung Powershell<->IPS

Hallo,

ich würde Euch heute gerne meine kleine .net Klasse zur JSON-RPC Kommunikation von Powershell oder anderen .net Programmen mit IPS vorstellen.
Mein Ziel war die Erstellung einer kleinen dll, mit der ich Powershell Scripte einfach mit IPS kommunizieren lassen kann.

Die Klasse kapselt das komplette Handling der JSON-RPC Komminikation. Ich brauche die PowerIPS.dll nur in ein Powershell Script einbinden, WebFront URL, Username, Passwort und bei Bedarf einen Proxy Server angeben und schon kann Powershell IPS Befehle senden und empfangen.

Was brauche ich dazu:
1.) Powershell 4.0 Sollte ab Windows 8 / Server 2012 schon integriert. Für Windows 7 / Server 2008 muss das Windows Management Framework 4.0 installiert werden. Falls dies nicht erwünscht ist, besteht noch eine andere Möglichkeit die im Anhang in PowerShell4.txt beschrieben ist. Als Powershell Editor empfehle ich PowerGUI (Freeware)
2.) Microsoft .NET 4.0. Die DLL nutzt für die JSON Serialisierung bestimmte Klassen, die erst ab dieser Version vorhanden sich. Falls .NET 4.0 noch nicht installiert ist, bitte updaten. (Bei Powershell 4.0 bzw. Windows Management Framework 4.0 bereits integriert)
3.) Die „PowerIPS.dll“ befindet sich im Anhang.

Wie nutze ich die PowerIPS.dll:
Die Datei kann in ein beliebiges Verzeichnis kopiert werden. (Ich nutze c:\PowerIPS\PowerIPS.dll in den Beispielen)
In dem Powershell Script muss diese Datei dann mit Add-Type eingebunden, eine Instanz auf eine Variable erzeugt und die WebFront Zugangsdaten konfiguriert werden:


#Powershell Code
Add-Type -Path 'C:\PowerIPS\PowerIPS.dll'
$IPS = [PowerIPS]::Instance
$IPS.setWF_Url("http://10.10.33.114:82/api/")
$IPS.setWF_Username("mail@ip-symcon.de")
$IPS.setWF_Password("***********")
#$IPS.setWF_Proxy("http://12.12.12.1:8080")

Das war schon alles!
Unter der gewählten Instanzvariable ($IPS) stehen jetzt alle IPS Variablenzugriff Befehle zur Verfügung. Zum Beispiel.


#PHP
$result = SetValueString(12345, "Hello World");

#Powershell
$result = $IPS.SetValueString(12345, "Hello World")

Mit den Variablenzugriff Befehlen deckt man vermutlich 99% der Scriptinganforderungen ab, da ja meistens Variablenwerte zwischen IPS<->Powershell Script ausgetauscht werden. Es lassen sich Dank JSON-RPC Schnittstelle aber auch alle anderen IPS Befehle nutzen. Ich habe mir allerdings nicht die Arbeit gemacht, sie alle als eigene Methode einzubinden.
Für diesen Anwendungsfall gibt es:


#Powershell Code
$IPS.IPSCommand($method, @(params))

#Beispiele
$KernelDir = $IPS.IPSCommand("IPS_GetKernelDir", @())

$result = $IPS.IPSCommand("SetValueString", @(12345, "Hello World!"))

Wie das letzte Beispiel zeigt, kann man alle IPS Befehle mit der IPSCommand Methode verwenden. Wichtig ist allerdings, dass der zweite params Parameter immer ein Array ist. Befehle ohne Parameter müssen wie im KernelDir Beispiel mit einem leeren Array @() angegeben werden. IPS Befehle, welche ein Array zurückliefern, sind bis auf das Semikolon identisch bei der Auswertung. Man bekommt ein Collections Object zurück, welches über die Key/Values Werte durchsucht werden kann.


#PHP
$result = IPS_GetObject(14065);
$ObjectName = $result['ObjectName'];

#Powershell Code
$result =  $IPS.IPSCommand("IPS_GetObject", @(14065))
$ObjectName = $result['ObjectName']

Wie erkenne ich Fehler?
Alle IPS und .NET Fehlermeldungen können über die Methode:


#Powershell Code
$LastErrorCode = $IPS.getLastErrorCode()
$LastErrorText = $IPS.getLastError()

abgefragt werden. Da .net typsicher ist, muss man bei manchen Abfragen etwas mitdenken. Ein $IPS.GetValueInteger(12345) liefert bei einem Fehler kein „false“ sondern 0.
Ich kann aber immer auf den Wert in $IPS.getLastErrorCode() zurück greifen. Ist dieser ungleich 0 ist ein Fehler aufgetreten.
Den Fehlertext bekommt man mit $IPS.getLastError().

IPS Fehlermeldungen werden einfach durchgereicht. Es könne aber auch Fehlermeldungen von .NET auftreten.
Zum Beispiel wenn keine Verbindung zum IPS-Service aufgebaut werden kann. (wegen Netzwerkproblemen o.ä.)
In diesem Fall enthält der Fehlertext die .NET Fehlermeldung. Dies ist durch ein [.net] am Beginn der Meldung kenntlich gemacht.

Die PowerIPS.dll kann natürlich auch mit Visual Studio eingebunden und in .net Programmen genutzt werden.
Falls hier Bedarf besteht kann ich auch einige Beispiele geben.

Feedback und Fragen sind gerne gesehen.:wink:

Nachtrag/Update:

Die neue Version 2.1 unterstützt ein Konfigurationsfile im INI Format. Die Zugangsdaten können dann dort abgelegt werden.
Man braucht dann nur den Pfad zur INI Datei angeben:


#Powershell Code
Add-Type -Path 'C:\PowerIPS\PowerIPS.dll'
$IPS = [PowerIPS]::Instance
$IPS.setWF_LoadIniFile("c:\PowerIPS\PowerIPS.ini")


PowerIPS_2.1.zip (9.87 KB)

Mir ist leider erst später aufgefallen, dass die DLL nicht unter Windows 7 / Server 2008 läuft. :o
Ich hatte nur mit Windows 8.1 und Server 2012 R2 getestet.

Ursache ist die fehlende Unterstützung von .net 4.0 Funktionen in der Default Powershell von Windows 7.

Die Eingabe von „$PSVersionTable“ in einem Powershell Fenster (powershell.exe) zeigt die auf dem Sytem installierte Version an.


PS C:\> $PSVersionTable

Name                           Value
----                           -----
PSVersion                      4.0
WSManStackVersion              3.0
SerializationVersion           1.1.0.1
CLRVersion                     4.0.30319.34011
BuildVersion                   6.3.9600.16394
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0}
PSRemotingProtocolVersion      2.2

Die OS Versionen größer Windows 8 und Server 2012 sollten bereits die Powershell 4.0 mit Unterstützung des
MS .net 4.0 Framemework installiert haben. Auf diesen Systemen funktioniert die „PowerIPS.dll“.

Bei Windows 7 und Server 2008 sollte die 2.0 Version der Powershell installiert sein. Diese unterstützt nur das
MS .net 2.0 Framework. Auf diesen Systemen funktioniert die „PowerIPS.dll“ NICHT!


PS C:\> $PSVersionTable

Name                           Value
----                           -----
CLRVersion                     2.0.50727.5472
BuildVersion                   6.1.7601.17514
PSVersion                      2.0
WSManStackVersion              2.0
PSCompatibleVersions           {1.0, 2.0}
SerializationVersion           1.1.0.1
PSRemotingProtocolVersion      2.1

In diesem Fall kann die PowerShell4.exe (im Anhang Post #1) statt der Systemeigenen powershell.exe verwendet werden.
Siehe http://stackoverflow.com/questions/2094694/how-can-i-run-powershell-with-the-net-4-runtime

Die beste Lösung für Windows 7 / Server 2008 wäre aber ein Update auf das „Windows Management Framework 4.0“
Siehe http://www.microsoft.com/de-de/download/details.aspx?id=40855

Neue Version im Post #1.

Wooow, wooow, woow!!!
Ich wollte nächste Woche auch anfangen, mich mit JSON-RPC und C# zu beschäftigen!
Ich werde in den nächsten Tagen Deine .dll ausprobieren und hier berichten.

Vielen Dank schonmal für Deine Mühe!!!

Gruß
Peter

Habs eben mit wenig Hoffnung aufgrund des Alters (von mir und dem Post) auf einem relativ frischen Win10 getestet:

Läuft auf Anhieb ! Klasse Klasse !

Hab vielen Dank !

Die JSON-RPC API ist immer noch aktuell und wurde nur um viele Funktionen erweitert. Wichtig ist dass du den Port 3777 statt 82 verwendest :slight_smile:

paresy