FaultContractAttribute Kelas

Definisi

Ruang nama:

System.ServiceModel

Rakitan:

System.ServiceModel.dll, System.ServiceModel.Primitives.dll

Paket:

System.ServiceModel.Primitives v10.0.652802

Sumber:

FaultContractAttribute.cs

Menentukan satu atau beberapa kesalahan SOAP yang dikembalikan ketika operasi layanan mengalami kesalahan pemrosesan.

public ref class FaultContractAttribute sealed : Attribute

[System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true, Inherited=false)]
public sealed class FaultContractAttribute : Attribute

[<System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true, Inherited=false)>]
type FaultContractAttribute = class
    inherit Attribute

Public NotInheritable Class FaultContractAttribute
Inherits Attribute

Warisan

Object

Attribute

FaultContractAttribute

Atribut

AttributeUsageAttribute

Contoh

Contoh kode berikut menunjukkan penggunaan FaultContractAttribute untuk menentukan bahwa operasi SampleMethod dapat mengembalikan kesalahan SOAP dengan detail jenis GreetingFault.

using System;
using System.Collections.Generic;
using System.Net.Security;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.Text;

namespace Microsoft.WCF.Documentation
{
  [ServiceContract(Namespace="http://microsoft.wcf.documentation")]
  public interface ISampleService{
    [OperationContract]
    [FaultContractAttribute(
      typeof(GreetingFault),
      Action="http://www.contoso.com/GreetingFault",
      ProtectionLevel=ProtectionLevel.EncryptAndSign
      )]
    string SampleMethod(string msg);
  }

  [DataContractAttribute]
  public class GreetingFault
  {
    private string report;

    public GreetingFault(string message)
    {
      this.report = message;
    }

    [DataMemberAttribute]
    public string Message
    {
      get { return this.report; }
      set { this.report = value; }
    }
  }

  class SampleService : ISampleService
  {
  #region ISampleService Members

  public string  SampleMethod(string msg)
  {
    Console.WriteLine("Client said: " + msg);
    // Generate intermittent error behavior.
    Random rnd = new Random(DateTime.Now.Millisecond);
    int test = rnd.Next(5);
    if (test % 2 != 0)
      return "The service greets you: " + msg;
    else
      throw new FaultException<GreetingFault>(new GreetingFault("A Greeting error occurred. You said: " + msg));
  }

  #endregion
  }
}

Imports System.Collections.Generic
Imports System.Net.Security
Imports System.Runtime.Serialization
Imports System.ServiceModel
Imports System.Text

Namespace Microsoft.WCF.Documentation
  <ServiceContract(Namespace:="http://microsoft.wcf.documentation")> _
  Public Interface ISampleService
    <OperationContract, FaultContractAttribute(GetType(GreetingFault), Action:="http://www.contoso.com/GreetingFault", ProtectionLevel:=ProtectionLevel.EncryptAndSign)> _
    Function SampleMethod(ByVal msg As String) As String
  End Interface

  <DataContractAttribute> _
  Public Class GreetingFault
    Private report As String

    Public Sub New(ByVal message As String)
      Me.report = message
    End Sub

    <DataMemberAttribute> _
    Public Property Message() As String
      Get
          Return Me.report
      End Get
      Set(ByVal value As String)
          Me.report = value
      End Set
    End Property
  End Class

  Friend Class SampleService
      Implements ISampleService
  #Region "ISampleService Members"

  Public Function SampleMethod(ByVal msg As String) As String Implements ISampleService.SampleMethod
    Console.WriteLine("Client said: " & msg)
    ' Generate intermittent error behavior.
    Dim rand As New Random(DateTime.Now.Millisecond)
    Dim test As Integer = rand.Next(5)
    If test Mod 2 <> 0 Then
      Return "The service greets you: " & msg
    Else
      Throw New FaultException(Of GreetingFault)(New GreetingFault("A Greeting error occurred. You said: " & msg))
    End If
  End Function

  #End Region
  End Class
End Namespace

Contoh kode berikut menunjukkan bahwa klien ISampleService WCF mengalami kesalahan SOAP ini sebagai FaultException<TDetail> jenis GreetingFault.

using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
using Microsoft.WCF.Documentation;

public class Client
{
  public static void Main()
  {
    // Picks up configuration from the config file.
    SampleServiceClient wcfClient = new SampleServiceClient();
    try
    {
      // Making calls.
      Console.WriteLine("Enter the greeting to send: ");
      string greeting = Console.ReadLine();
      Console.WriteLine("The service responded: " + wcfClient.SampleMethod(greeting));

      Console.WriteLine("Press ENTER to exit:");
      Console.ReadLine();

      // Done with service.
      wcfClient.Close();
      Console.WriteLine("Done!");
    }
    catch (TimeoutException timeProblem)
    {
      Console.WriteLine("The service operation timed out. " + timeProblem.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException<GreetingFault> greetingFault)
    {
      Console.WriteLine(greetingFault.Detail.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException unknownFault)
    {
      Console.WriteLine("An unknown exception was received. " + unknownFault.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (CommunicationException commProblem)
    {
      Console.WriteLine("There was a communication problem. " + commProblem.Message + commProblem.StackTrace);
      Console.ReadLine();
      wcfClient.Abort();
    }
  }
}

Imports System.ServiceModel
Imports System.ServiceModel.Channels
Imports Microsoft.WCF.Documentation

Public Class Client
  Public Shared Sub Main()
    ' Picks up configuration from the config file.
    Dim wcfClient As New SampleServiceClient()
    Try
      ' Making calls.
      Console.WriteLine("Enter the greeting to send: ")
      Dim greeting As String = Console.ReadLine()
      Console.WriteLine("The service responded: " & wcfClient.SampleMethod(greeting))

      Console.WriteLine("Press ENTER to exit:")
      Console.ReadLine()

      ' Done with service. 
      wcfClient.Close()
      Console.WriteLine("Done!")
    Catch timeProblem As TimeoutException
      Console.WriteLine("The service operation timed out. " & timeProblem.Message)
      Console.ReadLine()
      wcfClient.Abort()
    Catch greetingFault As FaultException(Of GreetingFault)
      Console.WriteLine(greetingFault.Detail.Message)
      Console.ReadLine()
      wcfClient.Abort()
    Catch unknownFault As FaultException
      Console.WriteLine("An unknown exception was received. " & unknownFault.Message)
      Console.ReadLine()
      wcfClient.Abort()
    Catch commProblem As CommunicationException
      Console.WriteLine("There was a communication problem. " & commProblem.Message + commProblem.StackTrace)
      Console.ReadLine()
      wcfClient.Abort()
    End Try
  End Sub
End Class

Keterangan

Tandai operasi dengan FaultContractAttribute atribut untuk mendeklarasikan satu atau beberapa kondisi pengecualian spesifik yang ditambahkan ke deskripsi Web Service Description Language (WSDL) dari operasi layanan sebagai pesan kesalahan SOAP eksplisit yang dikembalikan oleh operasi.

Di semua aplikasi terkelola, kesalahan pemrosesan diwakili oleh Exception objek. Dalam aplikasi berbasis SOAP seperti aplikasi Windows Communication Foundation (WCF), metode layanan mengkomunikasikan pemrosesan informasi kesalahan menggunakan pesan kesalahan SOAP. Karena aplikasi WCF dijalankan di bawah kedua jenis sistem kesalahan, informasi pengecualian terkelola apa pun yang harus dikirim ke klien harus dikonversi dari pengecualian menjadi kesalahan SOAP. Anda dapat menggunakan perilaku pengecualian layanan default, atau Anda dapat secara eksplisit mengontrol apakah -- dan bagaimana -- pengecualian dipetakan ke pesan kesalahan. Untuk gambaran umum pengecualian dan kesalahan SOAP dalam aplikasi WCF, lihat Menentukan dan Menangani Kesalahan dalam Kontrak dan Layanan.

Disarankan agar operasi layanan menggunakan FaultContractAttribute untuk secara resmi menentukan semua kesalahan SOAP yang dapat diterima klien dalam operasi normal. Disarankan juga bahwa hanya informasi yang harus diketahui klien yang dikembalikan dalam kesalahan SOAP untuk meminimalkan pengungkapan informasi.

• Properti Action mengontrol tindakan pesan kesalahan.

• Properti DetailType mendapatkan jenis objek detail yang diserialisasikan dalam pesan kesalahan.

• Properti Name dan Namespace mengontrol nama dan namespace, masing-masing, dari pesan kesalahan.

• menunjukkan HasProtectionLevel apakah pesan kesalahan memiliki tingkat perlindungan yang ditentukan, dan jika demikian, properti mengontrol tingkat perlindungan tersebut ProtectionLevel .

Perhatian

Jika pesan kesalahan membawa informasi yang sensitif atau dapat menyebabkan masalah keamanan, sangat disarankan agar ProtectionLevel properti diatur.

• Jika Anda mengatur ProtectionLevel secara eksplisit ke atau ProtectionLevel.SignProtectionLevel.EncryptAndSign, maka Anda harus menggunakan pengikatan dengan keamanan yang diaktifkan menggunakan System.ServiceModel.SecurityMode properti pada pengikatan atau pengecualian dilemparkan.

• Jika Anda memilih pengikatan yang memungkinkan keamanan dan Anda tidak mengatur ProtectionLevel properti di mana pun pada kontrak, semua data aplikasi akan dienkripsi dan ditandatangani.

• Jika Anda memilih pengikatan yang tidak mengaktifkan keamanan (misalnya, System.ServiceModel.BasicHttpBinding keamanan telah dinonaktifkan secara default), dan ProtectionLevel tidak diatur secara eksplisit, maka tidak ada data aplikasi yang akan dilindungi.

Untuk banyak skenario ProtectionLevel pengaturan ke EncryptAndSign untuk pesan kesalahan sudah cukup. Untuk detail selengkapnya, lihat Memahami Tingkat Perlindungan.

Untuk mengembalikan kesalahan tertentu dari operasi yang ditandai dengan FaultContractAttribute, lemparkan FaultException<TDetail> (di mana parameter jenis adalah informasi kesalahan yang dapat diserialisasikan) ketika pengecualian terkelola terjadi selama operasi. Aplikasi klien WCF memunculkan kesalahan SOAP dengan jenis yang sama seperti yang dilemparkan dalam implementasi klien -- yaitu, sebagai FaultException<TDetail> (di mana typeparameter adalah informasi kesalahan yang dapat diserialisasikan). FaultContractAttribute dapat digunakan hanya untuk menentukan kesalahan SOAP untuk operasi layanan dua arah dan untuk pasangan operasi asinkron; operasi satu arah tidak mendukung kesalahan SOAP dan oleh karena itu tidak mendukung FaultContractAttribute.

Nota

Anda dapat menggunakan jenis yang dapat diserialisasikan untuk menyampaikan informasi kesalahan. Satu-satunya batasan dalam versi WCF ini adalah jenis yang ditentukan dalam harus dapat diserialisasikan FaultContractAttribute oleh System.Runtime.Serialization.DataContractSerializer. Untuk dukungan serialisasi yang DataContractSerializer disediakan, lihat Serializer Kontrak Data.

Misalnya, untuk menentukan bahwa klien dapat mengharapkan kesalahan SOAP yang berisi Int32, tempatkan parameter jenis tersebut FaultContractAttribute dalam pada metode layanan Anda.

Nota

Contoh kode berikut tidak mengatur ProtectionLevelproperti , , Nameatau Namespace .

[OperationContractAttribute]
[FaultContractAttribute(typeof(int))]
int Divide(int arg1, int arg2);

  <OperationContractAttribute(), FaultContractAttribute(GetType(Integer))> _
    Function Divide(ByVal arg1 As Integer, ByVal arg2 As Integer) As Integer
End Interface 'FCADemonstration

Kemudian, dalam metode layanan Anda, lemparkan yang baru FaultException<TDetail> di mana parameter jenis adalah jenis yang berisi informasi kesalahan (dalam kasus di atas, a Int32). Contohnya:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

Contoh sebelumnya sangat mendasar; hampir semua informasi dapat diteruskan menggunakan System.Int32 kode, sehingga jenis detail ini bukan yang paling berguna. Biasanya, aplikasi WCF menentukan kesalahan SOAP dengan jenis detail khusus untuk persyaratan informasi kesalahan klien. Untuk contoh yang lebih lengkap, lihat bagian Contoh.

Nota

Jika Anda menentukan FaultException<TDetail> di mana parameter jenis adalah System.String, nilai string ditetapkan ke properti Detail di aplikasi klien; klien tidak dapat mengambil string tersebut FaultException<TDetail>.ToString dengan memanggil metode . Agar nilai string dikembalikan saat aplikasi klien memanggil Exception.ToString, berikan System.ServiceModel.FaultException pengecualian di dalam operasi dan teruskan string ke konstruktor.

Untuk secara eksplisit mengontrol perilaku aplikasi saat pengecualian atau FaultException<TDetail> dilemparkan, terapkan System.ServiceModel.Dispatcher.IErrorHandler antarmuka pada System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior atau System.ServiceModel.Description.IEndpointBehavior dan tetapkan ke ChannelDispatcher.ErrorHandlers properti . IErrorHandler memungkinkan Anda untuk secara eksplisit mengontrol kesalahan SOAP yang dihasilkan dan apakah akan mengirimkannya kembali ke klien.

Untuk memfasilitasi penelusuran kesalahan, atur ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ke true dalam kode atau Anda dapat menggunakan ServiceDebugBehavior.IncludeExceptionDetailInFaults dalam file konfigurasi aplikasi. Saat diaktifkan, layanan secara otomatis mengembalikan informasi pengecualian ke pemanggil. Kesalahan ini muncul kepada klien sebagai FaultException pengecualian.

Penting

Karena pengecualian terkelola dapat mengekspos informasi aplikasi internal, pengaturan ServiceBehaviorAttribute.IncludeExceptionDetailInFaults atau ServiceDebugBehavior.IncludeExceptionDetailInFaults untuk true dapat mengizinkan klien WCF untuk mendapatkan informasi tentang pengecualian operasi layanan internal, termasuk informasi yang dapat diidentifikasi secara pribadi atau sensitif lainnya.

Oleh karena itu, pengaturan ServiceBehaviorAttribute.IncludeExceptionDetailInFaults atau ServiceDebugBehavior.IncludeExceptionDetailInFaults ke true hanya disarankan sebagai cara untuk men-debug sementara aplikasi layanan. Selain itu, WSDL untuk suatu metode yang mengembalikan pengecualian terkelola yang tidak tertangani dengan cara ini tidak mencakup kontrak untuk FaultException<TDetail> dari tipe String. Klien harus bersiap menghadapi kemungkinan kesalahan SOAP yang tidak diketahui (dikembalikan ke klien WCF sebagai objek System.ServiceModel.FaultException) untuk mendapatkan informasi debugging dengan benar.

Konstruktor

Nama	Deskripsi
FaultContractAttribute(Type)	Menginisialisasi instans baru dari kelas FaultContractAttribute.

Properti

Nama	Deskripsi
Action	Mendapatkan atau menetapkan tindakan pesan kesalahan SOAP yang ditentukan sebagai bagian dari kontrak operasi.
DetailType	Memperoleh tipe dari objek yang dapat diserialisasikan dan berisi informasi kesalahan.
Name	Mendapatkan atau mengatur nama pesan kesalahan dalam Bahasa Deskripsi Layanan Web (WSDL).
Namespace	Mendapatkan atau mengatur namespace layanan kesalahan SOAP.