PlugInBeispielProjekt
Aus Sceneo Wiki
Beispielprojekt ’’mein erstes plugin’’
Intention
Die Anleitung richtet sich an alle, die gerne in die plugin Entwicklung einsteigen möchten, aber vor der Frage stehen „Wie mach ich das denn jetzt nun genau?“. Es gibt ja leider (noch) kein offizielles SDK, dafür aber einige Infos im Forum als auch hier im Wiki. Diese Anleitung hat nicht den Anspruch in die Tiefe zu gehen, und bei jedem Detail zu erklären, warum und wieso, sondern versucht den Leser Schritt für Schritt zu seinem ersten plugin zu führen. Die Codierung erfolgt in C#, trotzdem sollte die Anleitung auch für die Entwicklung in anderen Programmiersprachen hilfreich sein.
Allgemeines
Anregungen, Fehler und Verbesserungsvorschläge können gerne hier im Forum diskutiert werden.
Teil 1
Im Teil 1 geht es um die Einrichtung der Entwicklungsumgebung, die Erstellung des plugin Codes und verschiedener zusätzlicher Dateien bis zur Integration in TVC4.
Einrichtung der Entwicklungsumgebung
Als Entwicklungsumgebung wird das kostenlose Microsoft Visual Studio 2008 Express C# verwendet. Dies kann hier herunter geladen und danach installiert werden.
Nach dem Start von Visual Studio muss ein neues Projekt angelegt werden. Dies erfolgt über Datei -> Neues Projekt…. Als Vorlage muss Klassenbibliothek gewählt werden und weiter unten ein sinnvoller Projektname.
Der erste Beispielcode
Der Inhalt der automatisch angelegten Datei class1.cs wird mit folgendem Code überschrieben:
using System;
using System.Collections.Generic;
using System.Text;
using System.Xml;
using System.Reflection;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using System.Net;
using System.IO;
using System.Diagnostics;
namespace flipper
{
[ComVisible(true), GuidAttribute("eigene GUID hier einsetzen")]
[ProgId("flipper.flipper")]
[ClassInterface(ClassInterfaceType.None)]
public class tvcplugin : TVcentral.ICentralPlugin
{
public string Name
{
get { return "flipper"; }
}
//wird z.Z. nicht benutzt
public void CloseConfiguration(TVcentral.TVcentralServer core)
{
}
//wenn Message an Plugin gesendet wird
public void Execute(TVcentral.TVcentralServer core, TVcentral.MessageItem msg)
{
if (msg.Command == "flipper_command_1")
{
// Dieses Kommando wird später von TVC4 ausgelöst, wenn das plugin aufgerufen wird
//Screenobjekt erstellen
TVcentral.Screen screen = core.Screens.NewScreen("flipper_screen_name", "flipperxml", true);
//Headline setzen
screen.get_Labels("lHeadline").set_Property("caption", "Ueberschrift");
//Screen anzeigen
screen.Show();
return;
}
//Plugin beenden
else if (msg.Command == "control" && (msg.Value == "exit" || msg.Value == "back"))
{
TVcentral.Screen screen = core.Screens.get_Screen("flipper_screen_name");
if (screen.IsValid()) screen.Close();
return;
}
}
//Plugin wird geladen (Start von TVC)
public void LoadPlugin(TVcentral.TVcentralServer core)
{
}
//wird z.Z. nicht benutzt
public void OpenConfiguration(TVcentral.TVcentralServer core)
{
}
//Plugin wird geschlossen (Ende von TVC)
public void UnloadPlugin(TVcentral.TVcentralServer core)
{
}
}
//hier können noch andere Klassen hin
}
Dieses Beispiel ist bewusst so einfach wie möglich gehalten. Es macht nur zwei Dinge: Wenn es von TVC4 aufgerufen wird, baut es einen eigenen Screen auf und setzt eine Überschrift. Dann wartet es darauf, mit back oder exit beendet zu werden.
GUID erstellen
Damit das plugin eindeutig identifizierbar wird, braucht es eine so genannte GUID. Diese kann mit dem Tool guidgen.exe erstellt werden. Dieses Tool ist scheinbar in der Express Version nicht enthalten, kann aber hier herunter geladen werden. Als Format ist das registry format zu empfehlen. Die erzeugte GUID muss dann zwischen den Anführungszeichen im Source Code eingefügt werden, wobei die geschweiften Klammern noch zu entfernen sind.
.NET Version einstellen
Visual Studio 2008 Express C# wird zusammen mit .NET 3.5 geliefert und installiert. Da TVC4 .NET 2.0 nutzt, muss man das erst einstellen. Dazu geht man auf Projektmappen-Explorer -> <Projekt> -> properties und dann auf der Seite Anwendung das Zielframework auf .NET Framework 2.0 setzen.
Verweis zu TVC4 herstellen
Damit das plugin die Klassen von TVC4 kennt, müssen diese dem Projekt bekannt gemacht werden. Warum man nicht direkt auf die COM TVcentral type Library sondern auf die Interop.TVcentral.dll verweisen sollte, ist hier beschrieben. Im Projektmappen-Explorer rechts-clicken auf Verweise und Verweis hinzufügen…. Im Reiter Durchsuchen auf den Pfad <TVcentral-install>\Plugins gehen und die Interop.TVcentral.dll auswählen. Jetzt mit Erstellen -> Projektmappe erstellen (oder F6) den Compiler anwerfen und – wenn alles richtig gemacht wurde – in der Statuszeile die Meldung Erstellen erfolgreich sehen.
Plugin kopieren
Um das plugin automatisch in das richtige Verzeichnis zu bringen, kann man im Visual Studio einen Postbuild Befehl eintragen. Dies geht über die Project Properties -> Buildereignisse.
Die Befehlszeile lautet z.B.: copy $(TargetPath) d:\programme\sceneo\tvcentral-v4\plugins\
Nicht vergessen den eigenen TVC4 Pfad anpassen!
Der Vorteil des Makros $(TargetPath) ist, dass es automatisch die Release oder Debug Version nimmt. Man kann sich natürlich auch eine batch Datei schreiben.
Danach führt ein Erstellvorgang (F6) zu einer Kopie des plugins im Verzeichnis <TVcentral-install>\Plugins. Beim ersten mal sollte man sich zur Sicherheit überzeugen, dass es auch wirklich dort ankommt.
Windows Vista:
- Die Pfadangaben des COPY-Befehls müssen in Anführungszeichen gesetzt werden z.B.: copy "$(TargetPath)" "C:\Program Files\Sceneo\TVcentral-v4\Plugins\"
- Visual Studio muss als Administrator gestartet werden
Plugin registrieren
Als nächstes muss das plugin noch als COM Object (?) registriert werden. Da dies nur einmal nötig ist, kommt es nicht in die Postbuild Anweisung sondern wird als Befehl ausgeführt:
d:\programme\sceneo\tvcentral-v4\tools\regasm.exe d:\programme\sceneo\tvcentral-v4\plugins\flipper.dll /codebase
Es kommt zwar folgende Warnung, die noch nicht verstanden ist. Aber wenn am Ende Types registered successfully steht, ist alles ok.
RegAsm : warning RA0000 : Registering an unsigned assembly with /codebase can ca use your assembly to interfere with other applications that may be installed on the same computer. The /codebase switch is intended to be used only with signed assemblies. Please give your assembly a strong name and re-register it. Types registered successfully
.tvc Datei erstellen
Als nächstes muss eine .tvc Datei erstellt werden. Diese wird von TVC4 (bzw. Sceneomatic) benötigt, um zu wissen welche Befehle und Parameter das plugin unterstützt. Für dieses Beispiel reicht es erstmal aus, das plugin und den Aufrufbefehl bekannt zu machen. Dabei ist auch hier die GUID einzusetzen die anfangs erstellt und im source code eingetragen wurde.
<?xml version="1.0" encoding="ISO-8859-1"?>
<tvcentral-plugin-control version="1.0">
<name>flipper</name>
<title>Flipper Plugin</title>
<company>Flipper</company>
<class-guid>{eigene GUID hier einsetzen }</class-guid>
<file-name>flipper.dll</file-name>
<enabled>True</enabled>
<global-params>
</global-params>
<messages>
<message>
<command description="Ein Testplugin ohne Sinn">plugin.flipper.flipper_command_1</command>
</message>
</messages>
</tvcentral-plugin-control>
Die Datei muss ebebfalls im Verzeichnis <TVcentral-install>\Plugins als <plugin-name>.tvc gespeichert werden.
Menü Eintrag erstellen
Um das Plugin in der TVC4 Oberfläche aufrufen zu können, wird Sceneomatic gestartet und der Menü-Editor aufgerufen. Dann auf den Button Neue Aktion clicken und dem leeren Eintrag einen Namen geben. Expertenoptionen einschalten und dann sollte der Name des Plugins in der Modul-Auswahl auftauchen. Änderungen übernehmen und Sceneomatic beenden. Wer mag, kann sich noch ein Symbol hinzufügen, notwendig ist das aber nicht.
XML Datei erstellen
Zuletzt brauchen wir noch eine XML Datei, die dem System sagt, wie die Oberfläche des plugins aussehen soll. Diese wird vom plugin mit der NewScreen-Methode aufgerufen. Dazu muss eine Datei erstellt werden mit genau dem Dateinamen, der auch im soure code gewählt wurde mit der Dateiendung xml, also hier flipperxml.xml. Der folgende Inhalt kann dann in diese Datei eingefügt werden.
<?xml version="1.0" encoding="ISO-8859-1" ?>
<MediaCenterScreen version="1.0.1">
<globals>
<position-left>0</position-left>
<position-top>0</position-top>
<position-width>1280</position-width>
<position-height>1024</position-height>
<background-color></background-color>
<background-image>backgrounds\bg_general.png</background-image>
<first-focus>menuCategory</first-focus>
</globals>
<elements>
<element type="label">
<name>lHeadline</name>
<caption></caption>
<position-left>40</position-left>
<position-top>10</position-top>
<position-width>1280</position-width>
<position-height>90</position-height>
<align-h></align-h>
<font-size>${font-header-size}</font-size>
<font-family>${font-header}</font-family>
<font-color>#ffffff</font-color>
</element>
</elements>
<controls>
<input cmd="exit" target="mein plugin Name"/>
<input cmd="back" target="mein plugin Name"/>
</controls>
</MediaCenterScreen>
Diese XML Datei muss danach in jedes einzelne Verzeichnis <TVcentral-install>\template\<template-name> kopiert werden. Danach müssen ggf. noch alle Positionsangaben angepasst werden, mindestens aber Höhe und Breite der <globals> Sektion. Zum Entwickeln und Testen reicht es natürlich aus, sich auf das Template zu beschränken, dass man aktiv nutzt. Wichtig ist bei den beiden target Zeilen fast am Ende noch den eigenen plugin-Namen einzusetzen, ansonsten kommt man nicht mehr aus dem plugin Screen zurück!
Der erste Aufruf
Wenn bisher alles richtig gemacht wurde, sollte nach dem Start von TVC4 im Hauptmenü ein weiterer Eintrag auftauchen mit dem Namen des Plugin:
Die Auswahl dieses Menüeintrags sollte dann zu folgendem Screen führen:
Mit exit oder back kommt man dann wieder zum Hauptbildschirm zurück.
Teil 2
Im Teil 2 geht es um die verschiedenen Möglichkeiten, plugins zu debuggen.
PVR service tool
Dieses tools PVRControl.exe ist sehr hilfreich weil es viele Information von TVC4 mitloggt, z.B. welche module gerade aufgerufen und welche messages gesendet werden. Eine kurze Beschreibung findet sich hier.
Debuggen mit Visual Studio
Mit der Express Version ist es ohne Tricks nicht möglich DLLs zu debuggen, wenn man nicht selbst der Entwickler des aufrufenden Programms ist. Damit es trotzdem geht, geht man auf Projektmappen-Explorer -> <Projekt> -> properties und dann auf der Seite debuggen das Arbeitsverzeichnis auf <TVcentral-install>\ setzen. Danach muss das Projekt geschlossen werden! Im Projektverzeichnis öffnet man dann die Datei <Projektname>.csproj.user und fügt die folgenden 2 Zeilen hinzu:
<StartAction>Program</StartAction>
<StartProgram><TVcentral-install>\tvcentral.exe</StartProgram>
Beispielhaft sieht es dann so aus:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<StartAction>Program</StartAction>
<StartProgram>d:\Programme\Sceneo\TVcentral-v4\tvcentral.exe</StartProgram>
<StartWorkingDirectory>D:\programme\Sceneo\TVcentral-v4\</StartWorkingDirectory>
</PropertyGroup>
</Project>
Beim nächsten Öffnen des Projekts erkennt Visual Studio diesen Eintrag. Ab sofort kann die DLL genauso debuggt werden wie eine ausführbare Datei. Der einzige Unterschied ist, dass bei Debugging starten (F5) erst TVC4 gestartet wird und man das plugin in TVC4 aufrufen muss.
Debug trace
Um das Laufzeitverhalten des plugins zu verfolgen ohne jedesmal den Debugger anzuwerfen, können in den Code Debug-Meldungen integriert werden. Diese werden dann im PVR service tool genauso sichtbar wie die TVC4 eigenen Meldungen. Dazu muss man nur folgende Anweisung an den gewünschten Stellen im Code einbauen:
Debug.WriteLine("meine debug Meldung");
Teil 3
Im Teil 3 geht es um die Erstellung eines Setups zum einfachen Verteilen des Plugins. Dies ist allerdings nicht mit der kostenlosen Express Version, sondern nur mit dem "großen" Visual Studio möglich.
Setup Projekt hinzufügen
Öffnen Sie Ihr Plugin-Projekt und klicken Sie auf "File"->"Add"->"New Project". Im folgenden Dialog erstellen Sie unter "Other Project Types"->"Setup and Deployment" ein neues "Setup Project".
Dateien zum Setup hinzufügen
Als nächstes klicken Sie mit der rechten Maustaste auf Ihr neues Setup-Projekt und wählen "Add"->"Project Output".
Wählen Sie nun Ihr Plugin Projekt, und den Eintrag "Primary Output" aus und klicken Sie auf OK.
Sie haben nun die kompilierte DLL Datei Ihres Plugins so wie die Abhängigkeiten Ihres Plugins (.NET Framework, TVCentral.exe und Interop.TVCentral.dll) zu Ihrem Setup hinzugefügt. Da wir die TVCentral.exe und die Interop.TVCentral.dll allerdings nicht zu unserem Setup hinzufügen wollen (da Sie beim Deinstallieren des Plugins gelöscht werden würden), müssen Sie diese nun aus dem Setup ausschließen. Klicken Sie dazu im Solution Explorer mit rechts auf die beiden Einträge der Dateien und wählen Sie dann "Exclude".
Als nächstes fügen Sie die .tvc Datei des Plugins Ihrem Setup hinzu. Klicken Sie dafür wieder mit Rechts auf Ihr Setup-Projekt, wählen Sie "Add"->"File" und wählen Sie die .tvc Datei Ihres Plugins aus.
Als nächstes müssen Sie die korrekte Ordnerstruktur und den Zielordner definieren. Wählen Sie dazu "View"->"Editor"->"File System". Im Properties Bereich können Sie nun unter "Default Location" den Standard-Installationsordner einstellen. Geben Sie hier "[ProgramFilesFolder]Sceneo\TVcentral-v4" ein.
Die DLL Datei und die .tvc Datei müssen im Unterordner Plugins kopiert werden. Erstellen Sie deshalb Unter "Application Folder" einen neuen Ordner "Plugins" (Rechtsklick->Add->Folder)
und verschieben Sie die beiden Einträge aus dem rechten Teil des Editors in diesen Ordner.
Auf die gleiche Weise können Sie nun auch weitere Dateien (z.B. screens) Ihrem Setup hinzufügen.
Setup-Einstellungen bearbeiten
Nun können Sie noch Namen, Sprache und sonstige Einstellungen des Setups anpassen. Klicken Sie dazu im Solution Explorer auf Ihr Projekt und bearbeiten Sie die gewünschten Einträge im Properties Bereich.
Als letztes müssen Sie noch sicherstellen, dass das Setup ihr Plugin auch als COM Objekt registriert. Klicken Sie dazu mit rechts auf ihr Plugin-Projekt und dann auf "Properties". Hier machen Sie nun unter "Build" ein Häckchen vor "Register for COM interop".
Setup erstellen
Um das Setup nun zu erstellen klicken Sie mit rechts auf Ihr Setup-Projekt und dann auf "Build". Hierbei wird automatisch auch Ihr Plugin kompiliert. Standardmäßig wird das fertige Setup im Unterordner "Release" Ihres Setup-Projektordners gespeichert.
