Einleitung
Durch die Unterstützung von C# können Sie beim Programmieren von Automatisierungen die komplette Bandbreite des .NET Frameworks nutzen, inklusive eigener Dialoge, Zugriffe auf Web-Services sowie Assemblies von Drittherstellern oder aus eigener Entwicklung.
Dieser Artikel soll Ihnen dabei helfen Ihr Visual Studio korrekt zu konfigurieren und ein einfaches Beispielscript zu starten bzw. selbstständig zu erstellen. Das im Artikel beschriebene Visual Studio Beispielprojekt befindet sich im Lieferumfang Ihrer cRM-Installation im Ordner Scripts.
Microsoft Visual Studio konfigurieren
Hinzufügen der Dateierweiterung für .csscript-Dateien
Wählen Sie im Visual Studio den Menüpunkt Extras > Optionen > Text-Editor > Dateierweiterung. Tragen Sie nun im Eingabefeld Erweiterung den Wert csscript ein und wählen Sie in der Auswahlliste für den Editor Microsoft Visual C#. Mit einem Klick auf Hinzufügen > OK bestätigen Sie die Auswahl.
Ausführen des mitgelieferten Beispielprojektes
Das mitgelieferte Beispielprojekt können Sie über die nachfolgende Datei öffnen:
...\cRM\Scripts\Examples\C#Script\Visual Studio Example Project\Visual Studio C Sharp Scripting.sln
Um den Quellcode der Anwendung einsehen zu können klicken Sie im Projektmappen-Explorer doppelt auf die Datei Template.csscript.
Das Beispielprojekt kann nach dem Öffnen über die zentrale Starten-Schaltfläche, über die Menüs Debuggen > Debuggen starten oder das Tastenkürzel F5 ausgeführt werden. Zudem können Sie die im Projekt hinterlegte .csscript-Datei direkt in die Anwendung über die bekannten Wege (Schaltfläche, Funktionsdefinitionen, …) integrieren, siehe auch Kapitel Integration in den cRM.
Aufbau des Quellcodes im mitgelieferten Beispielprojekt
Referenzen, Usings und Script-Anweisungen
In diesem Abschnitt finden Sie die essentiellen Referenzen auf DLL-Bibliotheken und deren Usings. Diese Informationen werden für die erfolgreiche Ausführung des C# Scripts im cRM benötigt und müssen an erster Stelle im Quellcode stehen. Bestehende Includes werden automatisch in das richtige Format gewandelt, wenn das C# Script ausgeführt wird. Das Format ist wie folgt aufgebaut:
// <!--#include ref="System.Windows.Forms";-->;
// <!--#include using="System.Windows.Forms"-->;
Folgende Referenzen und Usings werden bereits automatisch verwendet und müssen nicht zusätzlich definiert werden:
System.dll
System.Core.dll
Microsoft.CSharp.dll
In diesem Abschnitt werden zudem weitere Anweisungen für das Script definiert. Diese Anweisungen können wie folgt aussehen:
// <!--#include-once file="%APPDIR%\include.csscript"-->
// <!--#pragma asynchronous-->
// <!--#pragma keepeditmode-->
// <!--#pragma encrypted-->
// <!--#pragma debugmode-->
// <!--#pragma forcelogging-->
#region, Usings, Namespace, Main()-Methode und cRM-Objekt
Anschließend folgen elementare Informationen, um das C# Script aus dem Visual Studio eigenständig starten und IntelliSense nutzen zu können.
#region Visual Studio only
using System.Windows.Forms;
using combit.cRM.COM;
namespace Visual_Studio_Projekt
{
class Template
{
static cRMApplication cRM = new cRMApplication(EApplicationStartType.GetActiveobject);
#endregion Visual Studio only
//-------------------------------------------------------------------------------------------------------
//>> C# Script Code ab hier:
Da der cRM intern mit einem eigenen cRM-Objekt arbeitet, können wir dies von der Kompilierung ausschließen - hierfür werden entsprechende Regions verwendet:
#region Visual Studio Only
und
#endregion Visual Studio Only
Alle innerhalb dieser Region definierten Aktionen/Codezeilen werden vom cRM bei der Ausführung des Scripts ignoriert. Es kann daher ein cRM-Objekt erstellt werden, um die Funktionen des IntelliSense zu nutzen.
Quellcode des Scripts für den cRM
In diesem Abschnitt werden alle relevanten Anweisungen für das C# Script definiert. Als Beispiel dient hierzu die Anzeige mehrerer Hinweismeldungen (Titel des aktuell geöffneten cRM-Projekts, Summierung, Ausgabe des aktuell angemeldeten cRM-Benutzers) und dem Zugriff auf eine kleine Klassenbibliothek sowie eines Objekts. Eigene Anweisungen können in diesem Block definiert werden.
public static void Main()
{
MessageBox.Show(cRM.CurrentProject.Name, cRM.AppTitle, MessageBoxButtons.OK, MessageBoxIcon.Information);
var nested = new NestedTestClass();
nested.ValueA = 15;
nested.ValueB = 25;
var result = nested.AddValues();
MessageBox.Show(result.ToString());
MessageBox.Show(GetCRMUser());
}
Kleine Klassenbibliotheken und eigene Objekte
Kleine Klassenbibliotheken und eigene Objekte können direkt im Script verwendet werden.
class NestedTestClass
{
public int ValueA { get; set; }
public int ValueB { get; set; }
public int AddValues()
{
return ValueA + ValueB;
}
}
public static string GetCRMUser()
{
return cRM.CurrentProject.CurrentUser;
}
Schließen der Anweisungen
In der abschließenden Region werden offene Anweisungen (im Detail: Namespace, Class, Main()-Methode) geschlossen und das Script somit beendet.
//<< C# Script Code bis hier
//-------------------------------------------------------------------------------------------------------
#region Visual Studio only
}
}
#endregion Visual Studio only
Das erste eigene C# Script mit Visual Studio
Anlegen des Projektes
Nach dem Start von Visual Studio wählen Sie in der Menüleiste die Punkte Datei > Neu > Projekt. Im anschließenden Dialog können Sie auswählen welchen Projekttyp Sie verwenden möchten. Wir empfehlen hierbei ein bestehendes Template zu verwenden: Klassenbibliothek (.NET Framework). Wählen Sie zudem im nachfolgenden Dialog eine .NET Framework Version 4.x.
Hinzufügen der cRM COM Assembly als Verweis
Im Anschluss an die Neuanlage des Projektes ist es notwendig die Datei combit.CSharpScript??.Engine.x86.dll zu referenzieren. Dies können Sie über den Projektmappen-Explorer mit einem Rechtsklick auf Verweise und der Auswahl Verweis hinzufügen durchführen. Wählen Sie anschließend im linken Menü die Kategorie Durchsuchen und suchen die Datei im Installationsverzeichnis der Anwendung über die Schaltfläche Durchsuchen im unteren Teil des Dialogs. Nach der Auswahl sollte die Datei in der Liste der verfügbaren Verweise mit einem Haken versehen sein.
Umbenennen der bestehenden Klasse und Anpassungen im Quellcode
Benennen Sie anschließend die Datei Class1.cs im Projektmappen-Explorer in .csscript. Klicken Sie hierfür mit einem Rechtsklick auf die Datei und wählen im Kontextmenü den Eintrag Umbenennen. Nach der Definition der Dateierweiterung .csscript in Visual Studio sollte das Syntax-Highlighting (farbliche Hervorhebung von Objekten, Kommentaren, …) korrekt funktionieren. Falls dies nicht der Fall ist, fügen Sie bitte die Dateierweiterung .csscript für den C# Editor hinzu (siehe auch Kapitel Hinzufügen der Dateierweiterung für .csscript-Dateien)
Passen Sie in der Folge Ihr Visual Studio Projekt so an, wie im nachfolgenden Bildschirmausschnitt gezeigt.
Um anschließend Informationen aus dem combit Relationship Manager über eine MessageBox in Form eines Hinweisfensters anzeigen zu können, ist es notwendig eine weitere Referenz, einen Absatz im Abschnitt using und die ersten Zeilen Script-Code hinzuzufügen.
Das Hinzufügen der Referenz ist wie zuvor mit einem Rechtsklick im Projektmappen-Explorer auf Verweise und Verweis hinzufügen möglich. Wählen Sie anschließend im linken Menü den Menüeintrag Assemblys und markieren Sie Framework. In der nun angezeigten Liste setzen Sie einen Haken vor die Assembly System.Windows.Forms und bestätigen Sie die Auswahl mit OK.
Fügen Sie im Anschluss den Namespace noch im using -Abschnitt im Quellcode hinzu. Bitte beachten Sie, dass Sie bei Assemblys, die nicht der Referenz using combit.cRM.COM; entsprechen, eine Referenz und ein Using für das C# Script definieren müssen. Dies sieht im Fall der Assembly System.Windows.Forms wie folgt aus:
// <!--#include ref="System.Windows.Forms.dll"-->;
// <!--#include using="System.Windows.Forms.dll"-->;
using System.Windows.Forms;
Im nächsten Schritt definieren Sie die Anzeige von Informationen aus dem combit Relationship Manager in einer MessageBox, auch wird hier gezeigt, wie eine kleinere Klassenbibliothek sowie ein weiteres Objekt genutzt werden können. Wählen Sie hierfür den vordefinierten Bereich für das C# Script:
//>> C# Script Code ab hier:
class NestedTestClass
{
public int ValueA { get; set; }
public int ValueB { get; set; }
public int AddValues()
{
return ValueA + ValueB;
}
}
public static void Main()
{
MessageBox.Show(cRM.CurrentProject.Name, cRM.AppTitle, MessageBoxButtons.OK, MessageBoxIcon.Information);
var nested = new NestedTestClass();
nested.ValueA = 15;
nested.ValueB = 25;
var result = nested.AddValues();
MessageBox.Show(result.ToString());
MessageBox.Show(GetCRMUser());
}
public static string GetCRMUser()
{
return cRM.CurrentProject.CurrentUser;
}
//<< C# Script Code bis hier
Ihr fertiges Projekt sollte nun folgenden Inhalt haben:
// <!--#include ref="System.Windows.Forms"-->
// <!--#include using="System.Windows.Forms"-->
#region Visual Studio only
using System.Windows.Forms;
using combit.cRM.COM;
namespace Visual_Studio_Projekt
{
class Template
{
static cRMApplication cRM = new cRMApplication(EApplicationStartType.GetActiveobject);
#endregion Visual Studio only
//-------------------------------------------------------------------------------------------------------
//>> C# Script Code ab hier:
class NestedTestClass
{
public int ValueA { get; set; }
public int ValueB { get; set; }
public int AddValues()
{
return ValueA + ValueB;
}
}
public static void Main()
{
MessageBox.Show(cRM.CurrentProject.Name, cRM.AppTitle, MessageBoxButtons.OK, MessageBoxIcon.Information);
var nested = new NestedTestClass();
nested.ValueA = 15;
nested.ValueB = 25;
var result = nested.AddValues();
MessageBox.Show(result.ToString());
MessageBox.Show(GetCRMUser());
}
public static string GetCRMUser()
{
return cRM.CurrentProject.CurrentUser;
}
//<< C# Script Code bis hier
//-------------------------------------------------------------------------------------------------------
#region Visual Studio only
}
}
#endregion Visual Studio only
Um das Script direkt aus Visual Studio heraus starten zu können befolgen Sie die beiden nachfolgenden Kapitel Konfiguration des Ausgabe-Typs und Definieren der Buildaktion.
Konfiguration des Ausgabetyps
Klicken Sie hierfür mit einem Rechtsklick auf den Namen des Visual Studio Projekts im Projektmappen-Explorer. Im Kontextmenü wählen Sie Eigenschaften. Anschließend finden Sie im Menü Anwendung die Option Ausgabetyp. Stellen Sie sicher, dass hier Windows-Anwendung eingetragen wurde.
Definieren des Buildvorgangs
Nach einem einfachen Klick auf die .csscript-Datei werden die Eigenschaften geöffnet (siehe Optionsmenü im rechten unten Bildschirmausschnitt). Bitte stellen Sie sicher, dass Sie Buildvorgang auf Kompilieren gesetzt haben.
Integration in den combit Relationship Manager
Die Integration von Scripten ist über Schaltflächen innerhalb der Eingabemaske (Scriptdatei ausführen, Scriptzeilen ausführen, Funktionsdefinitionen, Folgeverknüpfungen), im Menüband (Funktionsdefinitionen), über den Befehl Konfigurieren > Scripte > Ausführen oder über Ereignisse möglich.
Eine Beschreibung, wie die Scripte konkret hinterlegt werden, finden Sie innerhalb der mitgelieferten combit Software Development Kit (SDK) Dokumentation. Sie können dabei jeweils entscheiden, ob Sie das Script direkt eingeben oder in Form einer externen Textdatei hinterlegen möchten. Insbesondere bei größeren Scripten ist letzteres die bessere Wahl, da diese eine leichte Wiederverwendbarkeit an anderer Stelle erlaubt.