Hilfe bei der Fehleranalyse für List & Label

Dieser Artikel hilft Ihnen, Fehler und Probleme in oder mit List & Label selbständig einzugrenzen oder zu beheben.

Er gibt Ihnen Tipps wie Sie sich am besten bei einem auftretenden Problem verhalten, bei der Suche vorgehen und in welcher Reihenfolge was zu tun ist. Wenn Sie dennoch den Support kontaktieren möchten, hilft der Artikel Ihnen, so viele Informationen wie möglich für die Support-Anfrage bereitzustellen.

Ein großes Augenmerk gilt dem sogenannten Debuggen. Debuggen bedeutet in unserem Fall Ihr Programm bei der Ausführung live auf Fehler zu untersuchen. Dabei wird Ihnen das Programm “Debwin4” hilfreich zur Seite stehen. Sie finden es im List & Label Installationsverzeichnis im Unterordner “Verschiedenes”. Dieses Programm protokolliert alle Vorgänge in einer einzigen Log-Datei. Im Laufe dieses Artikels erhalten Sie einen Einblick über den Aufbau und den Inhalt der Log-Datei. Ebenso wie Sie Fehler in der selbigen schnellstmöglich ausfindig machen können.

Vorgehensweise bei der Fehleranalyse

Wenn ein Problem auftritt empfiehlt es sich eine bestimmte Reihenfolge bei der Fehlersuche einzuhalten. Nachfolgend eine Auflistung der vorzunehmenden Schritte, eine Erklärung der einzelnen Schritte folgt im Laufe des Artikels.

  1. Service Pack-Aktualität prüfen
  2. Service Pack PDF-Dokumentation lesen
  3. Forum und Knowledgebase durchsuchen
  4. Log-Datei mit Debwin4 erstellen
  5. Log-Datei analysieren
  6. Dump-Datei erstellen
  7. Support kontaktieren

Service Pack-Aktualität prüfen

Bitte überprüfen Sie als erstes, ob Sie die aktuellste Version von List & Label nutzen. Viele aufgetretene Probleme, die uns die Benutzer/Entwickler melden, werden nach einer erfolgreichen Lokalisierung und Behebung in den Service Packs korrigiert. Daher empfiehlt es sich List & Label immer auf dem neuesten Stand zu halten.

Der Versionsstand Ihrer List & Label Installation (und damit der Service Pack Stand) auf zwei Arten feststellen. Zum einen über den Designer und zum anderen über die Log-Datei. Auf Letzteres wird im weiteren Verlauf eingegangen.

Führen Sie im geöffneten Designer die Tastenkombination <STRG + UMSCHALT + F12> (CTRL + SHIFT + F12) aus. In dem sich öffnenden Dialog können Sie Informationen über List & Label und Ihr System entnehmen. Entscheidend hierbei ist die Versionsnummer. Unter “Version” sehen Sie Ihre momentane List & Label Version mit Unterversion. Außerdem kann man erkennen, welche Module geladen werden.

Eine Übersicht der aktuellen Service Packs zu Ihren registrierten Produkten finden Sie in unserem Supportbereich.

Service Pack PDF-Dokumentation lesen

Im Supportbereich finden Sie außerdem ein PDF-Dokument, in dem alle Fehlerbehebungen, Features und Verbesserungen des Service Packs in englischer Sprache dokumentiert sind. Lesen Sie sich dieses Dokument zunächst durch, eventuell ist Ihr Problem durch das Herunterladen und Installieren des Service Packs bereits schnell und einfach gelöst.

Forum und Knowledgebase durchsuchen

Wenn Sie bereits erahnen oder gar wissen was die Ursache Ihres Problems ist, empfehlen wir unser Forum und unsere Knowledgebase für Hilfe zu durchsuchen. Hier finden Sie Artikel mit Tipps oder Lösungen zu bekannten und häufig auftretenden Problemen oder möglicherweise auch einen anderen Anwender mit dem gleichen Problem.

Debugging von .NET Anwendungen

Probleme, die auf dem Entwicklerrechner auftreten, können meist leicht gefunden werden – hier kann direkt mit den üblichen Features der Entwicklungsumgebung gearbeitet werden und ein Problem so recht schnell eingegrenzt werden. Der erste Schritt besteht darin, eventuell auftretende Exceptions abzufangen und deren Ursache zu überprüfen (vgl. Abschnitt “Fehlerhandling mit Exceptions” in der Programmierer-Referenz).

Als Entwicklungskomponente wird List & Label aber natürlich unter einer Vielzahl verschiedener Konstellationen bei den Endanwendern ausgeführt. Um Probleme dort möglichst einfach zu finden, steht ein eigenes Debug-Tool zur Verfügung, das bei selten oder nur auf bestimmten Systemen auftretenden Problemen eine Protokollierungsfunktion bietet, mit deren Hilfe Probleme auch auf Systemen ohne Debugger untersucht werden können.

Natürlich kann die Logging-Funktion auch auf dem Entwicklerrechner genutzt werden und bietet auch dort die Möglichkeit, sämtliche Aufrufe und Rückgabewerte schnell auf einen Blick zu prüfen.

Protokolldatei anfertigen

Tritt ein Problem nur auf einem Kundensystem auf, sollte auf diesem zunächst eine Protokolldatei erstellt werden. Hierzu dient das Tool “Debwin4”, welches im “Verschiedenes”-Verzeichnis der List & Label-Installation installiert wird.

Debwin muss vor der Applikation gestartet werden. Wenn anschließend die Applikation gestartet wird, werden sämtliche Aufrufe an die Komponente mit ihren Rückgabewerten sowie einige Zusatzinformationen zu Modulversionen, Betriebssystem etc. protokolliert.

Jede unter .NET geworfene Exception entspricht im Protokoll einem negativen Rückgabewert einer Funktion. Im Protokoll finden sich meist weitere hilfreiche Informationen.

Soll die Anwendung ohne Hilfe von Debwin Debug-Protokolle erstellen, so kann das Debugging auch über den Code aktiviert werden:

...
using(ListLabel LL = new ListLabel())
{
  LL.Debug = LlDebug.Enabled | LlDebug.LogToFile;
  LL.DebugLogFilePath = @"c:\temp\myLLProtocol.log";
}
...

Benutzerdefiniertes Logging & Protokollierung in Webanwendungen

Wie Sie Ihr eigenes benutzerdefiniertes Logging realisieren und was bei der Protokollierung von Webanwendungen, Windows-Diensten und Mehrbenutzersystemen zu beachten ist, finden Sie in unserem separaten Knowledgebase-Artikel Logging bei Verwendung als Service / Web Reporting.

Log-Datei mit Debwin4 erstellen

Der Aufbau von Debwin4 ist sehr einfach gehalten.

Der Debug-Modus muss nicht mehr über LlSetDebug() eingeschaltet werden. Um alle Ausgaben zu erhalten, muss Debwin vor der zu debuggenden Applikation gestartet werden. Sobald Ihre Applikation gestartet ist, werden dann die Debug-Ausgaben von Debwin verwertet und ausgegeben.

Folgende Möglichkeiten stehen Ihnen zur Verfügung:

Capture List & Label Log
Log-Datei für List & Label erstellen.

Capture cRM Log
Log-Datei für combit Relationship Manager erstellen.

Capture Report Server Log
Log-Datei für Report Server erstellen.

Open Log File
Eine vorhandene Log-Datei öffnen.

Open Log From Clipboard
Kopierte Log-Ausgaben aus Zwischenablage öffnen.

Bei der Verwendung von Debwin4 muss die bekannte Vorgehensweise früherer Debwin-Versionen eingehalten werden:

  1. Debwin4 starten.
  2. “Capture List & Label Log” wählen.
  3. Die Applikation starten und das Fehlverhalten erneut provozieren.

Neben den Fehlercodes erhalten Sie weitere Informationen, so dass Sie häufig auf diese Weise die Ursache für ein unerwünschtes Verhalten finden können.

Man erkennt das aufgerufene Modul (CMLL25), den Logger (LL.API), die Thread-ID (3F58), Timing-Informationen (13:14:31.866) und die aufgerufene Funktion (LlDefineFieldExt(…)) mit Parametern sowie – in der Folgezeile – den Rückgabewert der Funktion (LlDefineFieldExt() → 0):

CMLL25                LL.API                3F58                13:14:31.866        >LlDefineFieldExt(2, 'Customers.CustomerID', 'ALFKI', 0x10000000, 0000000)
CMLL25                LL.API                3F58                13:14:31.867        >LlDefineFieldExt() ->  0 (00000000)

Während des Loggings stehen folgende Funktionen in Debwin4 zur Verfügung:

Turn Logging on or off
Hiermit können Sie das Logging pausieren oder fortsetzen.

Clear All Messages
Hiermit werden alle Ausgaben in der aktuellen Ansicht gelöscht.

Auto-Scroll
Ist diese Option aktiviert, dann liegt der Fokus des Ausgabe-Fensters auf den letzten und somit aktuellen Debug-Ausgaben.

Save Log
Speichert die Log-Datei im log4-Format.

Copy Log
Kopiert die Debug-Ausgaben in die Zwischenablage.

Add Custom Message
Fügt eine Notiz/Nachricht in die Log-Datei ein.

Filters
Möglichkeit zum Laden eines gespeicherten Filters.

Clear Filter
Eventuell gesetzte Filter werden zurückgesetzt und alle Log-Ausgaben werden angezeigt.

Previous Issue
Zeigt den vorherigen Fehler in der Log-Datei an.

Next Issue
Zeigt den nächsten Fehler in der Log-Datei an.

Search
Suche in der Log-Datei. Mit Funktionstaste F3 zum nächsten Suchtreffer

Log-Datei filtern

Über das Filter-Fenster haben Sie die Möglichkeit die Log-Datei schnell und unkompliziert nach bestimmten Informationen zu durchsuchen bzw. die Debug-Ausgaben einzugrenzen.

Minimum Level
Bestimmt die Priorität der Ausgabe (Debug-Ausgabe, Information, Warnung und Fehler).

Loggers
Eingrenzung nach Logger (LL.API, LL.DataProvider, LL.Export, LL.Generic, LL.Licensing, LL.NetFX, LL.Notification, LL.Printer).

Thread
Eingrenzung nach einem bestimmten Thread.

Date/Time (From)
Debug-Ausgaben ab einem bestimmten Datum/Zeit.

Date/Time (To)
Debug-Ausgaben bis einem bestimmten Datum/Zeit.

Message
Bestimmte Debug-Ausgabe.

Die Filter erlauben die Verwendung mehrerer semikolon-separierter Werte. Zusätzlich lassen sich die Filterkriterien, z.B. nach einem bestimmten Thread oder verschiedene Logger bequem über das Kontextmenü des Ausgabefensters selbst zusammenstellen. Klicken Sie einfach die jeweilige Zeile und wählen Sie den einzuschließenden Thread oder den auszuschließenden Logger aus:

Tipp: Die Suche (Search) und die Filter-Message erlauben die Verwendung von Regular Expressions.

Erstellen einer Log-Datei bei Server/Webapplikationen

Zur Erstellung von Log-Dateien für Server/Webapplikationen ist es notwendig Debwin4 als Administrator auszuführen (Kontextmenü “Als Administrator ausführen”) und “Capture List & Label Log” zu wählen. Das Logging in Diensten und Webapplikationen wird dann automatisch gestartet.

Log-Datei analysieren

Allgemeiner Aufbau einer Log-Datei

Die mit Debwin4 erstellten Log-Dateien haben generell den gleichen Aufbau. Als erstes wird der sogenannte “Header” erstellt. Diesem folgen die eigentlichen Debug-Ausgaben, welche die Funktionsaufrufe, Rückgabewerte und eventuelle Fehlercodes enthalten.

Header

Der Header liefert verschiedene Informationen über das System, z.B. List & Label Version, Unter-Version (Service Pack Level), Sprache, Betriebssystem:

Version                        : 25.2.2020.9400 (20-04-01 00:57)F
SysInfo of                     : 02.04.2020 13:14:22
Application                    : C:\PROGRAM FILES (X86)\COMBIT\LL25\BEISPIELANWENDUNG\DEMOAPPLICATION25.EXE [25.1.0.0]
List & Label                   : C:\PROGRAM FILES (X86)\COMBIT\LL25\REDISTRIBUTION\X86\CMLL25.DLL [25.2.2020.9400 (20-04-01 00:57)F]
Caller                         : 
Serial number                  : ********
LL flags                       : DD(0), Debug=DBG: (TMP), INF: (TMP), WRN: (TMP), ERR: (TMP)+LS+IDP
User and system name           : ******** on ********
User Domain                    : ********\********
Keyboard                       : 00000407
Country/Language               : Germany/German (user)
                               : Germany/German (system)
OS version                     : Windows 6.2 (WIN_10 1909 32 bit APP on 64 bit OS) Multiprocessor Free
                               : Emulated OS: Windows 8 (Enterprise), (x86 Processor) v6.2 Build:9200
                               : Underlying OS: Windows 10 (Enterprise), (x64 Processor) v10.0 Build:18363.720, ProductType:0x00000004, (Terminal Services in Remote Admin Mode), (64 Bit Edition), (Multiprocessor Free)

Des Weiteren Informationen über die verwendeten Verzeichnisse der TEMP-Dateien, z.B. Speicherort für temporäre Dateien beim Druck, verfügbarer Speicherplatz auf dem Speicherpfad und eine Überpürfung der Lese-/Schreibrechte (R/W check OK):

Drives available               : C:\;D:\;E:\;H:\;I:\;K:\;N:\;R:\;S:\;U:\;V:\
Temporaries                    : 
 GetTempPath()                 : C:\Users\********\AppData\Local\Temp\combit\ (hard disk, 223557.0 MB free), R/W check OK
 env(TEMP)                     : C:\Users\********\AppData\Local\Temp (hard disk, 223557.0 MB free)
 env(TMP)                      : C:\Users\********\AppData\Local\Temp (hard disk, 223557.0 MB free) 

Zusätzliche werden alle im Netzwerk verfügbaren Drucker sowie der Standarddrucker aufgelistet:

Printers                    : 15
                            : 'Send To OneNote 2016': 'Send to Microsoft OneNote 16 Driver' on 'nul:'
							[...]
							: 'PDF-XChange Lite V6': 'PDF-XChange V6 Printer Driver (Lite)' on 'PXC5L'
							[...]
Default printer             : 'Microsoft XPS Document Writer'

Anhand dieser Header-Informationen können Sie nun auch Ihre aktuelle List & Label-Version in Erfahrung bringen. Dieser Header sollte bei Log-Dateien für den Support immer enthalten sein.

Debug-Ausgaben

Wie bereits erwähnt folgen dem Header die eigentlichen Ausgaben. Eine solche Zeile könnte zum Beispiel so aussehen:

Module
Kennzeichnet das verantwortliche List & Label Modul, in diesem Fall cmLL25.dll.

Logger
Kennzeichnet den ausgebenden Logger (LL.API, LL.DataProvider, LL.Export, LL.Generic, LL.Licensing, LL.NetFX, LL.Notification, LL.Printer). In diesem Fall LL.API

Thread
Kennzeichnet den Thread und hilft bei der Unterscheidung von verschiedenen Threads, in diesem Fall der Thread 3F58.

Date/Time

  • Gibt die Uhrzeit der Ausführung des Druckjobs zurück.
  • Ist von Bedeutung, wenn bei der Ausführung des Druckjobs zum Beispiel eine unerklärliche Pause von ca. 30 Sekunden gemacht wird, in denen nichts geschieht.
  • D.h. um die Ursache zu finden, müssten Sie zuerst die Zeile ausfindig machen, bei der ein Zeitsprung von 30 Sekunden ersichtlich ist.
  • Tipp Über den Menüpunkt Options > Date/Time Format können Sie sich die direkt die Differenz der einzelnen Debug-Ausgabe zur vorherigen Debug-Ausgabe anzeigen lassen.

Message
Kennzeichnet den aktuell ausgeführten Vorgang, hier ist es die Anmeldung LlDefineFieldExt des Feldes Customers.CustomerID mit Inhalt ALFKI mit dem Feldtyp LL_TEXT 0x10000000.

Fehlererkennung

Aufgetretene Fehler sind in der Log-Datei relativ einfach aufzuspüren. Fehler werden in Debwin4 rot hervorgehoben und lassen sich über die Schaltfläche “Next Issue” direkt anzeigen. Mittels “Previous Issue” springen Sie zum vorherigen Fehler zurück.

In diesem Fall ist es ein Syntax-Fehler. Die verwendete Formel hat einen Fehler und kann nicht interpretiert werden. Der String schließt nicht mit einem " ab.

Überprüfen von Rückgabewerten

Nach jedem Aufruf einer Funktion empfiehlt es sich die Rückgabewerte zu überprüfen, um eine korrekte Ausführung sicherstellen zu können.

Korrekte Funktionsausführungen liefern einen Wert von “0” zurück. Alle Rückgabewerte kleiner Null “-??” deuten auf Fehler bzw. Hinweise hin.

Unter .NET werden statt der negativen Rückgabewerte Exceptions geworfen. Dies ermöglicht es Ihnen, alle möglichen Fehler bequem in einem catch-Block abzufangen.

Dump-Datei erstellen

Sie können die Dump-Datei mit zwei verschiedenen Tools erstellen, entweder ProcDump oder WinDbg.

ProcDump

Mit diesem Hilfsprogramm von Microsoft können Sie ganz einfach Process Dumps (Prozesssicherungen) von CPU-Spitzen in Applikationen überwachen. Das Tool hilft Ihnen außerdem dabei, Prozessabbilder zu erzeugen, wenn sich Prozesse aufhängen oder unbehandelte Ausnahmen auftreten. Sie können das Programm direkt bei Microsoft herunterladen.

So erstellen Sie Prozessabbilder:

  • Starten Sie Ihre Anwendung.
  • Führen Sie ProcDump mit folgenden Befehl in der Kommandozeile aus:
procdump -accepteula –e –ma <Anwendung>.exe –o %TEMP%\dump.dmp
  • Es werden nun verschiedene Informationen über den Prozess in der Kommandozeile angezeigt.
  • Führen Sie bitte die Schritte bis zu dem Fehlverhalten erneut aus.
  • ProcDump erzeugt automatisch eine Dump-Datei, sobald das Problem auftritt.

Windows Debugger WinDbg

Mit dem Windows Debugger WinDbg können Sie Dump-Dateien erstellen. Sie können das Programm direkt bei Microsoft herunterladen. Entweder als eigenständiges Programm oder als Bestandteil des Windows Software Development Kit (SDK), setzen Sie dort bei der Installation lediglich den Haken für “Debugging Tools for Windows”.

So erstellen Sie Ihre Dump-Datei:

  • Starten Sie WinDbg über den erstellten Startmenüeintrag.
  • Starten Sie den betroffenen Prozess unter dem Debugger über File > Open Executable.
  • Starten Sie das Debugging über Debug > Go oder über die Funktionstaste F5.
  • Falls das Problem auftritt, geben Sie bitte den folgenden Befehl in die Debugger-Kommandozeile ein:
.dump /ma c:\temp\combit.dmp
  • Bestätigen Sie die Eingabe. WinDbg erzeugt nun die Dump-Datei in dem angegeben Pfad.

Eine ausführliche Anleitung zur Erstellung von Dump-Dateien, z.B. wenn die Anwendung “hängen” sollte, finden Sie in unserem separaten Knowledgebase-Artikel Erstellung von Speicherabbilddateien.

Support kontaktieren

Wenn Sie den Fehler selbst nicht ausfindig machen können und den Support kontaktieren müssen, ist es im Sinne einer raschen Problemlösung ratsam, dem Support-Team so viele Informationen wie nur möglich zur Verfügung zu stellen. Im Normalfall werden folgende Informationen (Dateien) benötigt:

  1. Genaue Fehlerbeschreibung (Wo tritt der Fehler auf? Bei welchem Arbeitsschritt?). Unser Online-Formular unterstützt Sie bei der Bereitstellung der wichtigsten Informationen. Zusätzlich kann noch die Projektdatei (*.lst, *.lsr etc.) + Vorschau-Datei (*.ll) mitgeschickt werden, sofern das Problem dort sichtbar ist.

und

  1. Wenn Sie das Problem mit unserer “Beispielanwendung” (DemoApplication??.exe) reproduzieren können, genügt die dort verwendete Druckvorlage (Projektdatei), damit der Support das Problem auch nachvollziehen kann. Ansonsten ist ein lauffähiges und minimiertes Source Code Beispiel notwendig. Sie können hierzu eines unserer vielen mitgelieferten Beispiele nutzen oder aber Sie reduzieren Ihre Anwendung soweit, dass diese problemlos vom Support ausführbar ist.

Sollte dies nicht möglich sein, kann in manchen Fällen auch eine Log-Datei helfen:

  1. Vollständige Log-Datei, die den Druckverlauf bis hin zum eigentlichen Problem zeigt (inkl. vollständigem Header).

Bei Abstürzen oder Exceptions kann auch Folgendes helfen:

  1. Dump-Datei