Fehler

  • Artikel

In diesem Abschnitt werden Fehler beschrieben, die möglicherweise von Funktionen von Windows-Webdiensten ausgegeben werden, wenn der Befehl nicht ausgeführt werden kann.

Ausgabeparameter

In der Regel werden die Werte von Ausgabeparametern nicht geändert, wenn eine Funktion fehlschlägt.

Es gibt einige Fälle, in denen Ausgabeparameter geändert werden, wenn die Funktion fehlschlägt. Diese Fälle werden in der Dokumentation für jeden Parameter ausdrücklich genannt. Wenn in der Dokumentation nichts über die Änderung von Ausgabeparametern im Fall eines Fehlers erwähnt wird, können Sie davon ausgehen, dass die Funktion sie nicht ändert.

Fehlercodes

Alle Fehlerrückgabecodes sind HRESULT-Werte. Diese API definiert eine Reihe von HRESULT-Werten im FACILITY_WEBSERVICES-Bereich, gibt aber auch Fehler zurück, die an anderer Stelle in der Windows-API definiert sind.

In der Dokumentation zu den jeweiligen APIs erfahren Sie, welche Fehlercodes zurückgegeben werden. Die Liste erhebt keinen Anspruch auf Vollständigkeit für jede API, sondern ist vielmehr eine Liste von Fehlercodes, für die es gängige Szenarien für eine explizite Behandlung gibt. Aufrufer sollten immer davon ausgehen, dass andere Fehlercodes von jeder API möglich sind.

Diese API definiert eine relativ kleine Anzahl von Fehlercodes, die Szenarien entsprechen, in denen ein Programm basierend auf dem Fehler Maßnahmen ergreifen sollte. Fehlercodes allein reichen möglicherweise nicht aus, um festzustellen, was schief gelaufen ist, oder um den Benutzer*innen eine gute Problembeschreibung bereitzustellen. Das Problem lässt sich am besten verstehen, wenn umfangreiche Fehler verwendet werden, wie unten beschrieben.

Umfangreiche Fehler

Zusätzlich zur Rückgabe eines Fehlercodes können Aufrufer optional durch die Übergabe eines WS_ERROR-Objekts, das nicht NULL ist, umfangreiche Fehlerinformationen für API-Aufrufe anfordern. Verwenden Sie WsCreateError, um ein Fehlerobjekt zu erstellen. Wenn ein Fehler auftritt, füllt die API, die den Fehler verursacht hat, das Fehlerobjekt mit zusätzlichem Kontext über die Fehlersituation. Wenn kein Fehler auftritt, wird das Fehlerobjekt nicht geändert. Die Übergabe eines NULL-Fehlerobjekts weist darauf hin, dass der Aufrufer nicht an umfangreichen Fehlerinformationen interessiert ist. Angerufene Funktionen (einschließlich Rückrufe) müssen darauf vorbereitet sein, NULL-Fehlerobjekte zu behandeln.

Beachten Sie, dass das gleiche Fehlerobjekt für mehrere API-Aufrufe verwendet werden kann, aber immer nur für einen API-Aufruf gleichzeitig (da es sich um ein Single-Threaded-Objekt handelt). Jedes Mal, wenn ein Fehler auftritt, werden Fehlerinformationen an das Fehlerobjekt angefügt. Wenn die Anrufkette abgearbeitet wird, können mehrere Funktionen dem Fehlerobjekt Informationen hinzufügen, um zusätzlichen Kontext über den Fehler zu liefern. Verwenden Sie WsResetError, um den Inhalt des Fehlerobjekts zu löschen, bevor es erneut verwendet wird (wenn ein Fehler auftritt). Wenn kein Fehler auftritt, ist es nicht erforderlich, das Fehlerobjekt vor seiner erneuten Verwendung zurückzusetzen.

Umfangreiche Fehlerinformationen bestehen aus folgenden Elementen:

  • Eine Reihe von Eigenschaftswerten, die zusätzliche Informationen zum Fehler bereitstellen, sofern vorhanden. Weitere Informationen finden Sie unter WS_ERROR_PROPERTY.
  • Null oder mehr Fehlerzeichenfolgen Die Zeichenfolgen werden mit WsAddErrorString hinzugefügt und können mit WsGetErrorString abgefragt werden. Die Anzahl der Zeichenfolgen kann mithilfe von WS_ERROR_PROPERTY_STRING_COUNT abgefragt werden.

Störungen und Fehler

Informationen dazu, wie Störungen und Fehler zusammenhängen, finden Sie unter Fehler.

Sprachsensitive Fehlerinformationen

Beim Erstellen eines Fehlerobjekts wird die LANGID der gewünschten Sprachübersetzung für Fehlerinformationen angegeben. Dies wird verwendet, wenn dem Fehlerobjekt Fehlerinformationen hinzugefügt werden.

Dieser Sprachwert kann mithilfe von WS_ERROR_PROPERTY_LANGID abgerufen oder festgelegt werden.

Kanonische Fehlercodes

Diese API stellt einen kanonischen Satz von Fehlercodes (WS_E_*) bereit, die es ermöglichen, verschiedene Kommunikationstechnologien zu verwenden, ohne von den spezifischen Fehlercodes der jeweiligen zugrunde liegenden Implementierung abhängig zu sein. Eine vollständige Liste dieser Fehlercodes finden Sie unter Rückgabewerte für Windows-Webdienste.

Auf diese Weise kann beispielsweise ein Programm nach dem Fehlercode WS_E_ENDPOINT_NOT_FOUND suchen, unabhängig davon, ob TCP, UDP oder HTTP verwendet wird, und geeignete Maßnahmen ergreifen (z.B. versuchen, einen anderen Endpunkt zu verwenden).

Wenn ein implementierungsspezifischer Fehlercode einem kanonischen Fehler zugeordnet ist, wird der ursprüngliche Fehlercode im Fehlerobjekt gespeichert und kann zu Diagnosezwecken weiterhin abgerufen werden. Weitere Informationen finden Sie unter WS_ERROR_PROPERTY_ORIGINAL_ERROR_CODE.

Ungültige API-Verwendung

Die folgenden Fehlercodes sind für eine ungültige API-Verwendung reserviert und werden unter anderen Umständen nicht zurückgegeben. Wenn einer dieser Fehler zurückgegeben wird, kann dies ein Hinweis auf einen Anwendungsfehler sein.

  • WS_E_INVALID_OPERATION
  • E_INVALIDARG

Die folgenden Enumerationen sind Teil der Ablaufverfolgung:

Die folgenden Fehlercodes sind Teil der Ablaufverfolgung:

  • CERT_E_CN_NO_MATCH
  • CERT_E_EXPIRED
  • CERT_E_UNTRUSTEDROOT
  • CERT_E_WRONG_USAGE
  • CRYPT_E_REVOCATION_OFFLINE
  • E_INVALIDARG
  • E_OUTOFMEMORY
  • WS_E_ADDRESS_IN_USE
  • WS_E_ADDRESS_NOT_AVAILABLE
  • WS_E_ENDPOINT_ACCESS_DENIED
  • WS_E_ENDPOINT_ACTION_NOT_SUPPORTED
  • WS_E_ENDPOINT_DISCONNECTED
  • WS_E_ENDPOINT_FAILURE
  • WS_E_ENDPOINT_FAULT_RECEIVED
  • WS_E_ENDPOINT_NOT_AVAILABLE
  • WS_E_ENDPOINT_NOT_FOUND
  • WS_E_ENDPOINT_TOO_BUSY
  • WS_E_ENDPOINT_UNREACHABLE
  • WS_E_INVALID_ENDPOINT_URL
  • WS_E_INVALID_FORMAT
  • WS_E_INVALID_OPERATION
  • WS_E_NOT_SUPPORTED
  • WS_E_NO_TRANSLATION_AVAILABLE
  • WS_E_NUMERIC_OVERFLOW
  • WS_E_OBJECT_FAULTED
  • WS_E_OPERATION_ABANDONED
  • WS_E_OPERATION_ABORTED
  • WS_E_OPERATION_TIMED_OUT
  • WS_E_OTHER
  • WS_E_PROXY_ACCESS_DENIED
  • WS_E_PROXY_FAILURE
  • WS_E_PROXY_REQUIRES_BASIC_AUTH
  • WS_E_PROXY_REQUIRES_DIGEST_AUTH
  • WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
  • WS_E_PROXY_REQUIRES_NTLM_AUTH
  • WS_E_QUOTA_EXCEEDED
  • WS_E_SECURITY_SYSTEM_FAILURE
  • WS_E_SECURITY_TOKEN_EXPIRED
  • WS_E_SECURITY_VERIFICATION_FAILURE
  • WS_E_SERVER_REQUIRES_BASIC_AUTH
  • WS_E_SERVER_REQUIRES_DIGEST_AUTH
  • WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
  • WS_E_SERVER_REQUIRES_NTLM_AUTH
  • WS_S_ASYNC
  • WS_S_END

Die folgenden Funktionen sind Teil der Ablaufverfolgung:

Das folgende Handle ist Teil der Ablaufverfolgung:

Die folgende Struktur ist Teil der Ablaufverfolgung:

Sicherheit

Es gibt eine Reihe von Sicherheitsaspekten, die Benutzer*innen des Fehlerobjekts beachten sollten:

  • Das Fehlerobjekt kann nicht vertrauenswürdige Daten enthalten. Beispiele hierfür sind: WS_FAULT und die Fehlerzeichenfolgen, die beide basierend auf Informationen, die über einen nicht vertrauenswürdigen Kanal empfangen wurden, im Fehlerobjekt gespeichert werden können. Benutzer*innen des Fehlerobjekts sollten beim Überprüfen der Informationen im Fehlerobjekt vorsichtig sein und Entscheidungen auf der Grundlage seiner Werte treffen.
  • Benutzer*innen des Fehlerobjekts sollten WsResetError aufrufen, nachdem sie die Informationen zum Fehler überprüft haben. Andernfalls kann dies zu Arbeitsspeicherakkumulation führen.
  • Benutzer*innen des Fehlerobjekts solltensehr vorsichtig sein, wenn sie den WS_FULL_FAULT_DISCLOSURE Wert der WS_FAULT_DISCLOSURE-Enumeration verwenden, da der generierte Fehler private Informationen enthalten kann, die im Rahmen des Fehleraufzeichnungsprozesses gesammelt wurden.