Kesalahan

Pesan kesalahan digunakan untuk mengomunikasikan informasi kesalahan tentang kegagalan di titik akhir jarak jauh. Pesan kesalahan seperti pesan lainnya, kecuali format isi pesan memiliki format standar. Kesalahan dapat digunakan baik oleh protokol infrastruktur, seperti WS-Addressing, dan oleh protokol aplikasi tingkat yang lebih tinggi.

Gambaran Umum

Konten isi pesan kesalahan diwakili dalam API ini menggunakan struktur WS_FAULT . Meskipun kesalahan memiliki serangkaian bidang tetap yang digunakan untuk memberikan informasi tentang kegagalan (seperti WS_FAULT_CODE yang mengidentifikasi jenis kesalahan, dan WS_FAULT_REASON yang berisi teks yang menjelaskan kesalahan), itu juga berisi bidang detail yang dapat digunakan untuk menentukan konten XML arbitrer yang berkaitan dengan kesalahan.

Menghasilkan kesalahan dalam Layanan

Layanan biasanya akan mengirim kesalahan karena beberapa kesalahan yang ditemui saat memproses permintaan. Model yang digunakan oleh API ini adalah bahwa kode dalam layanan yang mengalami kesalahan pemrosesan akan menangkap informasi kesalahan yang diperlukan di objek WS_ERROR , dan kemudian kode pada tingkat yang lebih tinggi dalam rantai panggilan benar-benar akan mengirim kesalahan menggunakan informasi yang diambil di lapisan bawah. Skema ini memungkinkan kode yang mengirim kesalahan untuk diisolasi dari bagaimana situasi kesalahan dipetakan ke kesalahan sambil tetap memungkinkan informasi kesalahan yang kaya dikirim.

Properti berikut dapat digunakan dengan WsSetFaultErrorProperty untuk mengambil informasi kesalahan untuk objek WS_ERROR :

  • WS_FAULT_ERROR_PROPERTY_ACTION. Ini menentukan tindakan yang akan digunakan untuk pesan kesalahan. Jika ini tidak ditentukan, maka tindakan default disediakan.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Ini berisi struktur WS_FAULT yang dikirim dalam isi pesan kesalahan.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Beberapa kesalahan termasuk header pesan yang ditambahkan ke pesan kesalahan untuk menyampaikan kegagalan pemrosesan yang berkaitan dengan header pesan permintaan. Properti ini dapat digunakan untuk menentukan WS_XML_BUFFER yang berisi header yang akan ditambahkan ke pesan kesalahan.

Setiap string kesalahan yang ditambahkan ke objek WS_ERROR digunakan sebagai teks dalam kesalahan yang dikirim. String kesalahan dapat ditambahkan ke objek kesalahan menggunakan WsAddErrorString.

Fungsi WsSetFaultErrorProperty dapat digunakan untuk mengatur properti objek WS_ERROR ini.

Untuk mengatur detail kesalahan yang disimpan di objek WS_ERROR , gunakan fungsi WsSetFaultErrorDetail . Fungsi ini dapat digunakan untuk mengaitkan konten XML arbitrer dengan kesalahan.

Host Layanan akan secara otomatis mengirim kesalahan dengan menggunakan informasi di atas dalam objek WS_ERROR. Properti WS_SERVICE_PROPERTY_FAULT_DISCLOSURE dapat digunakan untuk mengontrol seberapa rinci kesalahan akan dikirim.

Jika bekerja di lapisan saluran, kesalahan dapat dikirim untuk objek WS_ERROR menggunakan WsSendFaultMessageForError.

Menangani kesalahan pada klien

Jika klien menerima kesalahan saat menggunakan Proksi Layanan atau melalui WsRequestReply atau WsReceiveMessage, kesalahan WS_E_ENDPOINT_FAULT_RECEIVED akan dikembalikan. (Untuk informasi selengkapnya, lihat Nilai Pengembalian Windows Web Services.) Fungsi-fungsi ini juga akan mengisi objek WS_ERROR yang disediakan ke panggilan dengan informasi tentang kesalahan yang diterima.

Properti objek WS_ERROR berikut dapat dikueri menggunakan WsGetFaultErrorProperty untuk mendapatkan informasi tentang kesalahan yang diterima:

Kesalahan mungkin berisi konten XML tambahan arbitrer dalam detail kesalahan. Ini dapat diakses menggunakan fungsi WsGetFaultErrorDetail .

Menggunakan kesalahan dengan pesan

Bagian berikut berlaku saat berhadapan langsung dengan konten isi pesan kesalahan.

Konten isi pesan kesalahan diwakili oleh struktur WS_FAULT standar, yang memiliki dukungan bawaan untuk serialisasi.

Misalnya, kode berikut dapat digunakan untuk menulis kesalahan ke isi pesan:

HRESULT hr;
WS_ELEMENT_DESCRIPTION faultDescription = { NULL, WS_FAULT_TYPE, NULL, NULL };
WS_FAULT fault = { ... };
hr = WsWriteBody(message, &faultDescription, WS_WRITE_REQUIRED_VALUE, &fault, sizeof(fault), error);

Kode berikut dapat digunakan untuk membaca kesalahan dari isi pesan:

HRESULT hr;
WS_ELEMENT_DESCRIPTION faultDescription = { NULL, WS_FAULT_TYPE, NULL, NULL };
WS_FAULT fault;
hr = WsReadBody(message, &faultDescription, WS_READ_REQUIRED_VALUE, &fault, sizeof(fault), error);

Untuk mengetahui apakah pesan yang diterima adalah kesalahan atau tidak, WS_MESSAGE_PROPERTY_IS_FAULT dapat dikonsultasikan. Properti ini diatur berdasarkan apakah elemen pertama dalam isi adalah elemen kesalahan selama WsReadMessageStart atau WsReadEnvelopeStart.

Untuk membuat WS_FAULT yang diberikan WS_ERROR, gunakan fungsi WsCreateFaultFromError .

Enumerasi berikut adalah bagian dari kesalahan:

Fungsi berikut adalah bagian dari kesalahan:

Struktur berikut adalah bagian dari kesalahan: