[Update 21.12.2020: Das Tutorial wurde anlässlich der Arbeiten am DATEV-Export überarbeitet. Dafür wurde ein Visual Studio 2017 benutzt.]

Die Herausforderung, ein .NET-Plugin zu schreiben, das sich wie ein ActiveX-Control verhält, dürfte dafür verantwortlich sein, dass es bisher noch kein reguläres Plugin gibt, das für diese Plattform geschrieben wurde. Dabei ist .NET für das Handling der EC&T-Objekte geradezu prädestiniert. Vielleicht ändert es sich ja mit diesem Tutorial. Für weitere Literatur siehe z.B. diese Links:

'Create ActiveX in .NET Step by Step' auf CodeProject.com
'Exposing Windows Forms Controls as ActiveX controls' ebenfalls auf CodeProject.com
'Exposing .NET Framework Components to COM' auf MSDN

Hier wird Visual Studio 2008 Standard in der englischen Version verwendet, aber andere VS-Versionen, z.B. 2005, 2010 -- Express sowie Professional -- sollten ganz ähnlich zu handhaben sein.

Schritt 1:(Windows Forms Control Library Projekt erstellen

Bei VS2010 hei&sz;t es auch einfach "Class Library". Auf deutsch dürfte es "Steuerelementbibliothek" bzw. "Klassenbibliothek" heißen. Ich habe als Sprache C# gewählt:

Als Projektnamen ECTPlugJahrAnzeigen angeben und Ok drücken.

Tipp: Es ist eine gute Praxis bei EC&T-Plugins auf die Kompatibilität mit dem Windows-Emulator Wine zu achten. Wine (und das kommerzielle Gegenstück Crossover) ermöglichen es Mac- und Linux-Nutzer*innen EC&T zu installieren. Deshalb wird empfohlen auf das alte .NET Framework (4.6.1 oder 4.7.2) zu setzen statt gleich das neueste .NET 5 zu supporten (Stand: Ende 2020).

Schritt 2: Steuerelemente mit dem Designer anlegen

Für die Funktion des Plugins (es soll das Buchungsjahr angezeigt werden) brauchen wir einen Knopf und ein Textfeld. Die müssen einfach aus der Toolbox in die Form gezogen werden:

Schritt 3: Dokument-Objekt hinzufügen

Um auf die EC&T-Daten zugreifen zu können, wird noch das entsprechende ActiveX Control benötigt (bitte nicht verwechseln mit dem ECTPlugJahrAnzeigen Control, das wir gerade schreiben, und das wiederum von EC&T verwendet wird). Dazu rechte Maustaste im Allgemein-Bereich der Toolbox und 'Choose items...' bzw. das deutsche Pendant dazu (ich werde ab jetzt beim Englischen bleiben -- mit den Screenshots sollte es kein Problem sein, die entspr. Funktionen in der deutschen Version des VS durchzuführen):

Nun zur COM-Registrierkarte wechseln, das Dokument-Control anhaken und auf Ok drücken.

Nun steht das Objekt in der Toolbox zur Verfügung und kann einfach mit Drag&Drop in eine Ecke der Form gezogen werden, wo es nicht stört (das Objekt ist während der Ausführung unsichtbar):

Schritt 4: Aus der Windows Forms Steuerelementbibliothek ein ActiveX machen

Der Schlüssel, um die .NET Bibliothek als ActiveX in EC&T einzubinden liegt darin, die sog. COM Interoperabilität einzuschalten. Dazu mit der rechten Maustaste auf das fettgedruckte ECTPlugJahrAnzeigen links im Solution Explorer klicken und Properties bzw. Eigenschaften wählen:

Dann in der vertikalen Menüleiste die Registrierkarte Build wählen und ein Häkchen bei 'Register COM Interoperability' machen:

Außerdem muss unter 'Signing' ein Häkchen bei 'Sign the assembly' gemacht werden. In der Drop-Down-Box dort dann "" auswählen und das Zertifikat mit einem Passwort sichern. So kannst nur Du eine neue Version des Plugins veröffentlichen. Die .pfx-Datei, die im Solution Explorer erscheint, also bitte gut aufheben.

Beide obige Schritte macht man am Besten gleich für Debug- und Release-Konfigurationen -- so vergisst man es später nicht.

ECTPlugJahrAnzeigen ist jetzt fast ein vollwertiges ActiveX. Es benötigt jetzt nur noch eine Kennung, damit das EC&T-Hauptprogramm es finden kann. Dazu müssen in der Datei 'UserControl1.Designer.cs' vor der Zeile partial class UserControl1 die Zeilen

    using System.Runtime.InteropServices;
    using Microsoft.Win32;
    [ProgId("ECTPlugJahrAnzeigen.UserControl1")]
    [ClassInterface(ClassInterfaceType.AutoDual)]
    [Guid("12fC3E0E-DC1E-A5dc-922B-A631740FA632")]
    [ComVisible(true)]

eingefügt werden. Bei Plugin-Eigenentwicklungen immer schön eine eigene Guid verwenden, sonst gibt es Konflikte zwischen den Plugins! Bei der Guid eine eindeutige Hexadezimalzahl, bei der sichergestellt ist, dass sie auf der ganzen Welt nur ein einziges Mal existiert. In Visual Studio ist im Menü Tools unter Create GUID eine schnelle Möglichkeit dazu vorhanden. (Das Format mit "[GUID(..." wählen.)

Außerdem müssen noch zwei Funktionen zur Registrierung und Deregistrierung des ActiveX in die UserControl1-Klasse eingefügt werden, z.B. nach Dispose():

        ///<summary>
        ///Register the class as a control and set its CodeBase entry
        ///</summary>
        ///<param name="key">The registry key of the control</param>
        [ComRegisterFunction()]
        public static void RegisterClass(string key)
        {
            // System.Windows.Forms.MessageBox.Show("Registriert!");
        }

        ///<summary>
        ///Called to unregister the control
        ///</summary>
        ///<param name="key">The registry key</param>
        [ComUnregisterFunction()]
        public static void UnregisterClass(string key)
        {
            // System.Windows.Forms.MessageBox.Show("Deregistriert!");
        }

Schließlich einmal CTRL-Shift-B drücken, damit das Projekt compiliert & gelinkt wird. Damit ist es vollbracht! Hinweis: Es ist normal, wenn beim Build die Meldung "Cannot register assembly" kommt. Das kommt daher, dass das Registrieren Admin-Rechte benötigt werden. Statt das ganze Visual Studio im Admin-Modus zu betreiben, emfehle ich die dll über eine mit Administrator-Rechten geöffnete CMD-Kommandozeile zu registrieren:

    %SystemRoot%\Microsoft.NET\Framework\v4.0.30319\regasm.exe ECTDatev.dll

(Der Dateipfad kann je nach installiertem .NET-Framework variieren.

Wenn wir vor dem 'Build' in der Datei AssemblyInfo.cs unseres Projekts die Zeile [assembly: ComVisible(false)] in [assembly: ComVisible(true)] geändert hätten, würde das Plugin als ECTPlugJahrAnzeigen.UserControl1 unter 'Choose Items' bei den COM Komponenten auftauchen. Aber da nur EC&T das Plugin gebrauchen kann, lassen wir es unsichtbar, so dass die COM-Liste nicht zugemüllt wird.

Schritt 5: Anlegen des Plugin-Verzeichnisses

Bevor wir irgendeine Funktionalität in das Plugin einbauen, wollen wir erstmal prüfen, ob wir bis hierhin alles richtig gemacht haben und es tatsächlich von EC&T aus aufgerufen werden kann.

Unter C:\Program Files\EasyCash&Tax\Plugins (oder wo immer das EasyCash&Tax-Programmverzeichnis auch liegt) jetzt erst einmal ein Verzeichnis 'JahrAnzeigen' anlegen. Wenn das Plugins-Verzeichnis noch nicht im Programmverzeichnis existiert, muss dieses natürlich zunächst anglegt werden).

Schritt 6: Plugin-Icon ablegen

Im Verzeichnis 'JahrAnzeigen' muss jetzt eine Bilddatei mit 32x32 Pixeln gespeichert werden, um das Icon des Plugins im Plugin-Menü von EC&T zu repräsentieren.

Damit es schnell geht nehmen wir jetzt einfach dieses hier: Einfach mit der rechten Maustaste draufklicken und mit 'Bild speichern unter...' die JPG-Datei im JahrAnzeigen-Verzeichnis abspeichern.

Hinweis: EC&T beherrscht lediglich veraltete Bildformate wie .gif oder .jpg ohne progressive encoding.

Schritt 7: Registry-Einträge mit dem Registrierungseditor machen

Nun den Registrierungseditor im Windows-Startmenü unter 'Ausführen' starten. Im erscheinenden Dialog 'regedit' eingeben und auf OK. Im 'Tree-View' auf der linken Seite des Registrierungseditors nun folgenden Schlüssel aufblättern: HKEY_LOCAL_MACHINE\Software\Tools\EasyCash\Plugins. Plugins mit der linken Maustaste selektieren, dann mit der rechten Maustaste darauf klicken und im Kontext-Menü Neu -> Schlüssel wählen und den Namen des Schlüssels mit 'JahrAnzeigen' angeben. Sollte es noch keinen Schlüssel 'Plugins' geben, diesen bitte zuerst auf gleiche Weise anlegen. Hinweis: Sollte es noch keinen key HKEY_LOCAL_MACHINE\Software\Tools\EasyCash geben, bitte das EasyCash&Tax Hauptprogramm installieren. In der 64-Bit-Version des Registrierungseditors heißt der Key HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Tools\EasyCash\Plugins heißen (Weil EC&T eine 32-Bit-Software ist).

Für den neuen Unterschlüssel 'JahrAnzeigen' müssen nun vier Werte eingetragen werden. Das geschieht wie gehabt mit dem Rechtsklick im Kontext-Menü -> Neu, dann aber auf Zeichenfolge (String).

Die vier Werte bekommen die Namen 'Aufruf', 'Beschreibung', 'Bitmap' und 'Name'.

Während der Wert für Name und Beschreibung egal ist (sollte für die zukünftige Nutzung aber nicht zu willkürlich gesetzt sein) müssen die anderen beiden Werte genau definiert sein. Unter Aufruf wird jetzt die 'ProgID' angegenen, also in unserem Fall ECTPlugJahrAnzeigen.UserControl1.

Im Wert 'Bitmap' steht ein Pfad zu einem 32x32-Punkte Bild, das in der Plugin-Werkzeugleiste eingeblendet wird. Wir haben es bereits in unserem Plugin-Verzeichnis abgelegt. Z.B. 'C:\Program Files\EasyCash&Tax\Plugins\JahrAnzeigen\JahrAnzeigen.jpg' (bzw. C:\Programme\... in manchen deutschen Windows-Installationen). Die Registry-Einträge sollten nun in etwa so aussehen:

Hinweis: Bei einem fertigen Plugin werden die Registry-Werte natürlich vom Installationsscript erzeugt und müssen nicht vom Nutzer manuell eingegeben werden. Gute Programme, um Installationsscrips (Setup.exe) zu erzeugen sind InnoSetup und Nullsoft's NSIS.

Schritt 8: EC&T starten Wenn alles gut gelaufen ist, erscheint das Sanduhr-Icon des Plugins beim Start von EC&T in der Plugin-Werkzeugleiste. Allerdings kommt eine Fehlermeldung, wenn das Plugin über das Icon aktiviert wird:

Das kommt daher, dass wir im Plugin noch keine Init-Funktion eingebaut haben, die ein Handle übernimmt, mit dessen Hilfe die EC&T-Objekte Zugriff auf die Daten erlangen.

Schritt 9: Init-Methode

Um das Handle zu bekommen, muss folgender code in die UserControl1 Klasse eingebaut werden, etwa nach private System.Windows.Forms.Label label1;:

        private long m_dokID;

        [ComVisible(true)]
        public void Init(long dokID) {
            m_dokID = dokID;
        }

Schritt 10: Jahr anzeigen

Das Jahr soll angezeigt werden, wenn der Benutzer auf den Knopf drückt. Wir doppelklicken jetzt auf den Knopf im Form-Designer Fenster, um zum Knopf-Codebereich zu gelangen:

Dort bitte folgenden Code einfügen:

        axDokument1.ID = (int)m_dokID;
        label1.Text = System.String.Format("Buchungsjahr: {0}", axDokument1.Jahr);

Sollte dann so aussehen:

Achtung: Vor neuerlichem Compilen mit CTRL-Shift-B unbedingt EC&T schließen, weil der Linker sonst nicht die erzeugte ECTPlugJahrAnzeigen.dll ersetzen kann! Nach dem EC&T-Neustart auf das Sanduhr-Icon geklickt, dann auf den Knopf und es sollte jetzt folgendes anzeigen:

Quellcode

Ein mit VS2008 erzeugtes Projekt liegt hier zum download bereit. Bei Eigenentwicklungen von Plugins, die potenziell für eine größere Allgemeinheit interessant sein könnten, bin ich gern bereit jede nötige Hilfestellung zu geben. Ich bin immer nur ein Klick auf das Kontaktformular entfernt. ;)