C#
Sie können mit Hilfe von C# auf die Funktionalitäten der Application API zugreifen. Zur Erstellung des C#-Code können Sie Visual Studio 2012/2013/2015/2017/2019/2022 verwenden und den Code in einem Visual Studio-Projekt speichern. Erstellen Sie das Projekt folgendermaßen:
1.Fügen Sie in Microsoft Visual Studio mit dem Befehl Datei | Neu | Projekt ein neues Projekt hinzu.
2.Fügen Sie durch Auswahl des Befehls Projekt | Verweis hinzufügen hinzufügen eine Referenz zur Authentic Desktop-Typbibliothek hinzu. Daraufhin wird das Dialogfeld "Verweis hinzufügen" angezeigt. Navigieren Sie zur Authentic Desktop-Typbibliothekkomponente, die sich im Authentic Desktop-Applikationsordner befindet und fügen Sie sie hinzu.
3.Geben Sie den gewünschten Code ein.
4.Kompilieren Sie den Code und führen Sie ihn aus.
C#-Beispielprojekt
Das Authentic Desktop-Paket enthält ein C#-Beispielprojekt, das Sie im Unterordner API\C# des Ordners Examples finden:
Windows 7, Windows 8, Windows 10, Windows 11 | C:\Benutzer\<Benutzername>\Dokumente\ |
Sie können das Projekt innerhalb von Visual Studio 2012/2013/2015/2017/2019/2022 kompilieren und ausführen.
Anhand der unten stehenden Codefragmente wird gezeigt, wie Sie Grundfunktionen der Applikation verwenden können. Der Code ist dem Code im C#-Beispielprojekt im Ordner API Examples Ihres Applikationsordners ähnlich, kann sich aber geringfügig davon unterscheiden.
Platformkonfiguration
Wenn Sie ein 64-Bit-Betriebssystem haben und eine 32-Bit-Installation von Authentic Desktop verwenden, müssen Sie die x86-Plattform im Konfigurationsmanager der Projektmappe hinzufügen und das Beispiel mit dieser Konfiguration erstellen. Im Dialogfeld "Neue Projektmappenplattform" kann eine neue x86-Plattform (für die aktive Projektmappe in Visual Studio) erstellt werden (Build | Konfigurations-Manager | Aktive Projektmappenplattform: | <Neu…>).
Funktionen im Codebeispiel unten
In diesem Beispiel sehen Sie eine einfache Benutzeroberfläche (Abbildung unten) mit Schaltflächen, über die grundlegende Authentic Desktop-Operationen aufgerufen werden:
•Start Authentic Desktop: Startet Authentic Desktop, das als Automation Server registriert ist, oder aktiviert das Programm, wenn Authentic Desktop bereits ausgeführt wird.
•Open OrgChart.pxf: Navigiert zu einem der mit Authentic Desktop installierten Beispieldokumente und öffnet es. Wenn das Dokument bereits offen ist, wird es zum aktiven Dokument.
•Open ExpReport.xml: Öffnet ein weiteres Beispieldokument.
•Toggle View Mode:: Wechselt in der Ansicht aller offenen Dokumente zwischen der Browser- und der Authentic-Ansicht. Im Code wird gezeigt, wie Sie durch offene Dokumente iterieren können.
•Validate: Validiert das aktive Dokument und zeigt das Ergebnis in einem Meldungsfeld an. Im Code wird gezeigt, wie Fehler und COM-Ausgabeparameter behandelt werden.
•Shutdown Authentic Desktop: Beendet Authentic Desktop.
Sie können den Code (des Codefragments unten oder des C#-Beispiels aus dem Ordner API Examples) beliebig modifizieren und ausführen.
Kompilieren und Ausführen des Beispiels
Doppelklicken Sie im Ordner API Examples auf die Datei AutomateAuthenticDesktop_VS2008.sln bzw. auf die Datei AutomateAuthenticDesktop_VS2010.sln (um sie in Visual Studio 2012/2013/2015/2017/2019/2022 zu öffnen). Alternativ dazu können Sie die Datei auch von Visual Studio aus öffnen (mit dem Befehl Datei | Öffnen | Projekt/Projektmappe). Um das Beispiel zu kompilieren und auszuführen wählen Sie Debuggen | Debuggen starten bzw. Debuggen | Starten ohne Debugging.
Code des Beispiels
Nachstehend sehen Sie den C#-Code der Grundfunktionen des im AutomateAuthenticDesktop Beispiel erstellten Formulars (Form1.cs). Beachten Sie, dass ich der unten aufgelistete Code geringfügig von dem Code im Formular unter API Examples unterscheiden kann. Der Code ist zum besseren Verständnis mit Kommentaren versehen. Abhängig davon, welche Application API-Funktionen sie aufrufen, sind Teile dieses Codes auch separat in Unterabschnitten dieses Abschnitts beschrieben.
Der Code besteht im Wesentlichen aus einer Reihe von Handlern für die Schaltflächen der oben gezeigten Benutzeroberfläche.
namespace WindowsFormsApplication2
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
// An instance of AuthenticDesktop is accessed via its automation interface.
XMLSpyLib.Application AuthenticDesktop;
// Location of examples installed with AuthenticDesktop
String strExamplesFolder;
private void Form1_Load(object sender, EventArgs e)
{
// Locate examples installed with AuthenticDesktop.
// REMARK: You might need to adapt this if you have a different major version of the product.
strExamplesFolder = Environment.GetEnvironmentVariable("USERPROFILE") + "\\My Documents\\Altova\\Authentic2012\\AuthenticExamples\\";
}
// Handler for the "Start AuthenticDesktop" button
private void StartAuthenticDesktop_Click(object sender, EventArgs e)
{
if (AuthenticDesktop == null)
{
Cursor.Current = Cursors.WaitCursor;
// If there is no AuthenticDesktop instance, create one and make it visible.
AuthenticDesktop = new XMLSpyLib.Application();
AuthenticDesktop.Visible = true;
Cursor.Current = Cursors.Default;
}
else
{
// If an AuthenticDesktop instance is already running, make sure it's visible.
if (!AuthenticDesktop.Visible)
AuthenticDesktop.Visible = true;
}
}
// Handler for the "Open OrgChart.pxf" button
private void openOrgChart_Click(object sender, EventArgs e)
{
// Make sure there's a running Authentic Desktop instance, and that it's visible
StartAuthenticDesktop_Click(null, null);
// Open a sample file installed with the product.
AuthenticDesktop.Documents.OpenFile(strExamplesFolder + "OrgChart.pxf", false);
}
// Handler for the "Open ExpReport.xml" button
private void openExpReport_Click(object sender, EventArgs e)
{
// Make sure there's a running Authentic Desktop instance, and that it's visible
StartAuthenticDesktop_Click(null, null);
// Open a sample file installed with the product.
AuthenticDesktop.Documents.OpenFile(strExamplesFolder + "ExpReport.xml", false);
}
// Handler for the "Toggle View Mode" button
private void toggleView_Click(object sender, EventArgs e)
{
// Make sure there's a running Authentic Desktop instance, and that it's visible
StartAuthenticDesktop_Click(null, null);
// Iterate through all open documents and toggle the current view between Text View and Authentic View.
foreach (XMLSpyLib.Document doc in AuthenticDesktop.Documents)
if (doc.CurrentViewMode == XMLSpyLib.SPYViewModes.spyViewAuthentic)
doc.SwitchViewMode(XMLSpyLib.SPYViewModes.spyViewBrowser);
else
doc.SwitchViewMode(XMLSpyLib.SPYViewModes.spyViewAuthentic);
}
// Handler for the "Shut down AuthenticDesktop" button
// Shut down application instance by explicitely releasing the COM object.
private void shutdownAuthenticDesktop_Click(object sender, EventArgs e)
{
if (AuthenticDesktop != null)
{
// Allow shut down of AuthenticDesktop by releasing the UI
AuthenticDesktop.Visible = false;
// Explicitly release the COM object
try
{
while (System.Runtime.InteropServices.Marshal.ReleaseComObject(AuthenticDesktop) > 0) ;
}
finally
{
// Avoid subsequent access to this object.
AuthenticDesktop = null;
}
}
}
// Handler for the "Validate" button
private void validate_Click(object sender, EventArgs e)
{
// COM errors get returned to C# as exceptions. Use a try/catch block to handle them.
try
{
// Method 'IsValid' is one of the few functions that use output parameters.
// Use 'object' type for these parameters.
object strErrorText = "";
object nErrorNumber = 0;
object errorData = null;
if (!AuthenticDesktop.ActiveDocument.IsValid(ref strErrorText, ref nErrorNumber, ref errorData))
{
// The COM call succeeds but the document is not valid.
// A detailed description of the problem is returned in strErrorText, nErrorNumber and errorData.
listBoxMessages.Items.Add("Document " + AuthenticDesktop.ActiveDocument.Name + " is not valid.");
listBoxMessages.Items.Add("\tErrorText : " + strErrorText);
listBoxMessages.Items.Add("\tErrorNumber: " + nErrorNumber);
listBoxMessages.Items.Add("\tElement : " + (errorData != null ? ((XMLSpyLib.XMLData)errorData).TextValue : "null"));
}
else
{
// The COM call succeeds and the document is valid.
listBoxMessages.Items.Add("Document " + AuthenticDesktop.ActiveDocument.Name + " is valid.");
}
}
catch (Exception ex)
{
// The COM call was not successful.
// Probably no application instance has been started or no document is open.
listBoxMessages.Items.Add("Error validating active document: " + ex.Message);
}
}
delegate void addListBoxItem_delegate(string sText);
// Called from the UI thread
private void addListBoxItem(string sText)
{
listBoxMessages.Items.Add(sText);
}
// Wrapper method to call UI control methods from a worker thread
void syncWithUIthread(Control ctrl, addListBoxItem_delegate methodToInvoke, String sText)
{
// Control.Invoke: Executes on the UI thread, but calling thread waits for completion before continuing.
// Control.BeginInvoke: Executes on the UI thread, and calling thread doesn't wait for completion.
if (ctrl.InvokeRequired)
ctrl.BeginInvoke(methodToInvoke, new Object[] { sText });
}
// Event handler for OnDocumentOpened event
private void handleOnDocumentOpened(XMLSpyLib.Document i_ipDocument)
{
String sText = "";
if (i_ipDocument.Name.Length > 0)
sText = "Document " + i_ipDocument.Name + " was opened!";
else
sText = "An empty document was created.";
// Synchronize the calling thread with the UI thread because
// COM events are triggered from a working thread
addListBoxItem_delegate methodToInvoke = new addListBoxItem_delegate(addListBoxItem);
// Call syncWithUIthread with the following arguments:
// 1 - listBoxMessages - list box control to display messages from COM events
// 2 - methodToInvoke - a C# delegate which points to the method which will be called from the UI thread
// 3 - sText - the text to be displayed in the list box
syncWithUIthread(listBoxMessages, methodToInvoke, sText);
}
private void checkBoxEventOnOff_CheckedChanged(object sender, EventArgs e)
{
if (AuthenticDesktop != null)
{
if (checkBoxEventOnOff.Checked)
AuthenticDesktop.OnDocumentOpened += new XMLSpyLib._IApplicationEvents_OnDocumentOpenedEventHandler(handleOnDocumentOpened);
else
AuthenticDesktop.OnDocumentOpened -= new XMLSpyLib._IApplicationEvents_OnDocumentOpenedEventHandler(handleOnDocumentOpened);
}
}
}
}