Gambaran umum klien WCF

Artikel
04/07/2023

Bagian ini menjelaskan apa yang dilakukan aplikasi klien, cara mengonfigurasi, membuat, dan menggunakan klien Windows Communication Foundation (WCF), dan cara mengamankan aplikasi klien.

Menggunakan Objek Klien WCF

Aplikasi klien adalah aplikasi terkelola yang menggunakan klien WCF untuk berkomunikasi dengan aplikasi lain. Membuat aplikasi klien untuk layanan WCF memerlukan langkah-langkah berikut:

Dapatkan kontrak layanan, pengikatan, dan informasi alamat untuk titik akhir layanan.
Buat klien WCF menggunakan informasi tersebut.
Operasi panggilan.
Tutup objek klien WCF.

Bagian berikut membahas langkah-langkah ini dan memberikan pengantar singkat tentang masalah berikut:

Menangani kesalahan.
Mengonfigurasi dan mengamankan klien.
Membuat objek panggilan balik untuk layanan dupleks.
Memanggil layanan secara asinkron.
Memanggil layanan menggunakan saluran klien.

Mendapatkan Kontrak Layanan, Pengikatan, dan Alamat

Di WCF, layanan dan klien membuat model kontrak menggunakan atribut, antarmuka, dan metode terkelola. Untuk menyambungkan ke layanan dalam aplikasi klien, Anda perlu mendapatkan informasi jenis untuk kontrak layanan. Biasanya, Anda mendapatkan informasi jenis untuk kontrak layanan menggunakan ServiceModel Metadata Utility Tool (Svcutil.exe). Utilitas mengunduh metadata dari layanan, mengonversinya menjadi file kode sumber terkelola dalam bahasa pilihan Anda, dan membuat file konfigurasi aplikasi klien yang dapat Anda gunakan untuk mengonfigurasi objek klien WCF Anda. Misalnya, jika Anda akan membuat objek klien WCF untuk memanggil MyCalculatorService, dan Anda tahu bahwa metadata untuk layanan tersebut diterbitkan di http://computerName/MyCalculatorService/Service.svc?wsdl, maka contoh kode berikut menunjukkan cara menggunakan Svcutil.exe untuk mendapatkan file ClientCode.vb yang berisi kontrak layanan dalam kode terkelola.

svcutil /language:vb /out:ClientCode.vb /config:app.config http://computerName/MyCalculatorService/Service.svc?wsdl

Anda dapat mengkompilasi kode kontrak ini ke dalam aplikasi klien atau ke rakitan lain yang kemudian dapat digunakan aplikasi klien untuk membuat objek klien WCF. Anda dapat menggunakan file konfigurasi untuk mengonfigurasi objek klien agar tersambung dengan benar ke layanan.

Untuk contoh proses ini, lihat Tutorial: Membuat Klien. Untuk informasi selengkapnya tentang kontrak, lihat Kontrak.

Membuat Objek Klien WCF

Klien WCF adalah objek lokal yang mewakili layanan WCF dalam bentuk yang dapat digunakan klien untuk berkomunikasi dengan layanan jarak jauh. Jenis klien WCF menerapkan kontrak layanan target, jadi ketika Anda membuatnya dan mengonfigurasinya, Anda kemudian dapat menggunakan objek klien secara langsung untuk memanggil operasi layanan. Waktu pelaksanaan WCF mengonversi panggilan metode menjadi pesan, mengirimkannya ke layanan, mendengarkan balasan, dan mengembalikan nilai tersebut ke objek klien WCF sebagai nilai pengembalian atau parameter out atau ref.

Anda juga dapat menggunakan objek saluran klien WCF untuk terhubung dengan dan menggunakan layanan. Untuk detailnya, lihat Arsitektur Klien WCF.

Membuat Objek WCF Baru

Untuk mengilustrasikan penggunaan kelas ClientBase<TChannel>, asumsikan kontrak layanan sederhana berikut telah dihasilkan dari aplikasi layanan.

Catatan

Jika Anda menggunakan Visual Studio untuk membuat klien WCF Anda, objek dimuat secara otomatis ke browser objek saat Anda menambahkan referensi layanan ke proyek Anda.

[System.ServiceModel.ServiceContractAttribute(
  Namespace = "http://microsoft.wcf.documentation"
)]
public interface ISampleService
{
    [System.ServiceModel.OperationContractAttribute(
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethod",
      ReplyAction = "http://microsoft.wcf.documentation/ISampleService/SampleMethodResponse"
    )]
    [System.ServiceModel.FaultContractAttribute(
      typeof(microsoft.wcf.documentation.SampleFault),
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethodSampleFaultFault"
    )]
    string SampleMethod(string msg);
}

Jika Anda tidak menggunakan Visual Studio, periksa kode kontrak yang dihasilkan untuk menemukan jenis yang memperluas ClientBase<TChannel> dan antarmuka ISampleService kontrak layanan. Dalam hal ini, jenis tersebut terlihat seperti kode berikut:

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
public partial class SampleServiceClient : System.ServiceModel.ClientBase<ISampleService>, ISampleService
{

    public SampleServiceClient()
    {
    }

    public SampleServiceClient(string endpointConfigurationName)
        :
            base(endpointConfigurationName)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, string remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(System.ServiceModel.Channels.Binding binding, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(binding, remoteAddress)
    {
    }
    public string SampleMethod(string msg)
    {
        return base.Channel.SampleMethod(msg);
    }
}

Kelas ini dapat dibuat sebagai objek lokal menggunakan salah satu konstruktor, dikonfigurasi, lalu digunakan untuk menyambungkan ke layanan jenis ISampleService.

Disarankan agar Anda membuat objek klien WCF Anda terlebih dahulu, lalu menggunakannya dan menutupnya di dalam satu blok try/catch. Jangan gunakan pernyataan using (Using dalam Visual Basic) karena dapat menutupi pengecualian dalam mode kegagalan tertentu. Untuk informasi selengkapnya, lihat bagian berikut serta Gunakan Tutup dan Batalkan untuk merilis sumber daya klien WCF.

Kontrak, Pengikatan, dan Alamat

Sebelum Anda dapat membuat objek klien WCF, Anda harus mengonfigurasi objek klien. Secara khusus, objek tersebut harus memiliki titik akhir layanan untuk digunakan. Titik akhir adalah kombinasi dari kontrak layanan, pengikatan, dan alamat. (Untuk informasi selengkapnya tentang titik akhir, lihat Titik Akhir: Alamat, Pengikatan, dan Kontrak.) Biasanya, informasi ini terletak di elemen <titik akhir> dalam file konfigurasi aplikasi klien, seperti yang dihasilkan alat Svcutil.exe, dan dimuat secara otomatis saat Anda membuat objek klien Anda. Kedua jenis klien WCF juga memiliki kelebihan beban yang memungkinkan Anda menentukan informasi ini secara terprogram.

Misalnya, file konfigurasi yang dihasilkan untuk ISampleService yang digunakan dalam contoh sebelumnya berisi informasi titik akhir berikut.

<configuration>
    <system.serviceModel>
        <bindings>
            <wsHttpBinding>
                <binding name="WSHttpBinding_ISampleService" closeTimeout="00:01:00"
                    openTimeout="00:01:00" receiveTimeout="00:01:00" sendTimeout="00:01:00"
                    bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard"
                    maxBufferPoolSize="524288" maxReceivedMessageSize="65536"
                    messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true"
                    allowCookies="false">
                    <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384"
                        maxBytesPerRead="4096" maxNameTableCharCount="16384" />
                    <reliableSession ordered="true" inactivityTimeout="00:10:00"
                        enabled="false" />
                    <security mode="Message">
                        <transport clientCredentialType="None" proxyCredentialType="None"
                            realm="" />
                        <message clientCredentialType="Windows" negotiateServiceCredential="true"
                            algorithmSuite="Default" establishSecurityContext="true" />
                    </security>
                </binding>
            </wsHttpBinding>
        </bindings>
        <client>
            <endpoint address="http://localhost:8080/SampleService" binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_ISampleService" contract="ISampleService"
                name="WSHttpBinding_ISampleService">
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

File konfigurasi ini menentukan titik akhir target dalam elemen <client>. Untuk informasi selengkapnya tentang menggunakan beberapa titik akhir target, lihat konstruktor ClientBase<TChannel> atau ChannelFactory<TChannel>.

Operasi Panggilan

Setelah Anda memiliki objek klien yang dibuat dan dikonfigurasi, buat blok try/catch, panggil operasi dengan cara yang sama seperti yang Anda lakukan jika objek lokal, dan tutup objek klien WCF. Ketika aplikasi klien memanggil operasi pertama, WCF secara otomatis membuka saluran yang mendasar, dan saluran yang mendasar ditutup ketika objek didaur ulang. (Atau, Anda juga dapat secara eksplisit membuka dan menutup saluran sebelum atau selanjutnya memanggil operasi lain.)

Misalnya, jika Anda memiliki kontrak layanan berikut:

namespace Microsoft.ServiceModel.Samples  
{  
    using System;  
    using System.ServiceModel;  
  
    [ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")]  
    public interface ICalculator  
   {  
        [OperationContract]  
        double Add(double n1, double n2);  
        [OperationContract]  
        double Subtract(double n1, double n2);  
        [OperationContract]  
        double Multiply(double n1, double n2);  
        [OperationContract]  
        double Divide(double n1, double n2);  
    }  
}

Namespace Microsoft.ServiceModel.Samples  
  
    Imports System  
    Imports System.ServiceModel  
  
    <ServiceContract(Namespace:= _  
    "http://Microsoft.ServiceModel.Samples")> _
   Public Interface ICalculator  
        <OperationContract> _
        Function Add(n1 As Double, n2 As Double) As Double  
        <OperationContract> _
        Function Subtract(n1 As Double, n2 As Double) As Double  
        <OperationContract> _
        Function Multiply(n1 As Double, n2 As Double) As Double  
        <OperationContract> _
     Function Divide(n1 As Double, n2 As Double) As Double  
End Interface

Anda dapat memanggil operasi dengan membuat objek klien WCF dan memanggil metodenya, seperti yang ditunjukkan oleh contoh kode berikut. Pembukaan, panggilan, dan penutupan objek klien WCF terjadi dalam satu blok try/catch. Untuk informasi selengkapnya, lihat Mengakses Layanan Menggunakan Klien WCF dan Menggunakan Tutup dan Batalkan untuk merilis sumber daya klien WCF.

CalculatorClient wcfClient = new CalculatorClient();
try
{
    Console.WriteLine(wcfClient.Add(4, 6));
    wcfClient.Close();
}
catch (TimeoutException timeout)
{
    // Handle the timeout exception.
    wcfClient.Abort();
}
catch (CommunicationException commException)
{
    // Handle the communication exception.
    wcfClient.Abort();
}

Menangani Kesalahan

Pengecualian dapat terjadi dalam aplikasi klien saat membuka saluran klien yang mendasar (baik secara eksplisit atau otomatis dengan memanggil operasi), menggunakan objek klien atau saluran untuk memanggil operasi, atau saat menutup saluran klien yang mendasar. Disarankan setidaknya bahwa aplikasi mengharapkan untuk menangani kemungkinan pengecualian System.TimeoutException dan System.ServiceModel.CommunicationException selain objek System.ServiceModel.FaultException apa pun yang dimunculkan sebagai akibat dari kesalahan SOAP yang dikembalikan oleh operasi. Kesalahan SOAP yang ditentukan dalam kontrak operasi dinaikkan ke aplikasi klien sebagai System.ServiceModel.FaultException<TDetail> di mana parameter jenis adalah jenis detail kesalahan SOAP. Untuk informasi selengkapnya tentang penanganan kondisi kesalahan dalam aplikasi klien, lihat Kesalahan Pengiriman dan Penerimaan. Untuk sampel lengkap menunjukkan cara menangani kesalahan di klien, lihat Pengecualian yang Diharapkan.

Mengonfigurasi dan Mengamankan Klien

Mengonfigurasi klien dimulai dengan pemuatan informasi titik akhir target yang diperlukan untuk klien atau objek saluran, biasanya dari file konfigurasi, meskipun Anda juga dapat memuat informasi ini secara terprogram menggunakan konstruktor dan properti klien. Namun, langkah-langkah konfigurasi tambahan diperlukan untuk mengaktifkan perilaku klien tertentu dan untuk banyak skenario keamanan.

Misalnya, persyaratan keamanan untuk kontrak layanan dinyatakan dalam antarmuka kontrak layanan, dan jika Svcutil.exe membuat file konfigurasi, file tersebut biasanya berisi pengikatan yang mampu mendukung persyaratan keamanan layanan. Namun, dalam beberapa kasus, mungkin diperlukan lebih banyak konfigurasi keamanan, seperti mengonfigurasi kredensial klien. Untuk informasi lengkap tentang konfigurasi keamanan untuk klien WCF, lihat Mengamankan Klien.

Selain itu, beberapa modifikasi kustom dapat diaktifkan dalam aplikasi klien, seperti perilaku waktu pelaksanaan kustom. Untuk informasi selengkapnya tentang cara mengonfigurasi perilaku klien kustom, lihat Mengonfigurasi Perilaku Klien.

Membuat Objek Panggilan Balik untuk Layanan Dupleks

Layanan dupleks menentukan kontrak panggilan balik yang harus diterapkan aplikasi klien untuk menyediakan objek panggilan balik agar layanan dapat memanggil sesuai dengan persyaratan kontrak. Meskipun objek panggilan balik bukan layanan penuh (misalnya, Anda tidak dapat memulai saluran dengan objek panggilan balik), untuk tujuan implementasi dan konfigurasi yang dapat dianggap semacam layanan.

Klien layanan dupleks harus:

Menerapkan kelas kontrak panggilan balik.
Membuat instans kelas implementasi kontrak panggilan balik dan gunakan untuk membuat objek System.ServiceModel.InstanceContext yang Anda berikan ke konstruktor klien WCF.
Memanggil operasi dan menangani panggilan balik operasi.

Objek klien WCF dupleks berfungsi seperti rekan nondupleks mereka, dengan pengecualian bahwa mereka mengekspos fungsionalitas yang diperlukan untuk mendukung panggilan balik, termasuk konfigurasi layanan panggilan balik.

Misalnya, Anda dapat mengontrol berbagai aspek perilaku runtime objek panggilan balik dengan menggunakan properti atribut System.ServiceModel.CallbackBehaviorAttribute pada kelas panggilan balik. Contoh lain adalah penggunaan kelas System.ServiceModel.Description.CallbackDebugBehavior untuk mengaktifkan pengembalian informasi pengecualian ke layanan yang memanggil objek panggilan balik. Untuk informasi selengkapnya, lihat Layanan Dupleks. Untuk sampel lengkap, lihat Dupleks.

Pada komputer Windows XP yang menjalankan Layanan Informasi Internet (IIS) 5.1, klien dupleks harus menentukan alamat dasar klien menggunakan kelas System.ServiceModel.WSDualHttpBinding atau pengecualian dimunculkan. Contoh kode berikut menunjukkan cara melakukan hal ini di dalam kode.

WSDualHttpBinding dualBinding = new WSDualHttpBinding();
EndpointAddress endptadr = new EndpointAddress("http://localhost:12000/DuplexTestUsingCode/Server");
dualBinding.ClientBaseAddress = new Uri("http://localhost:8000/DuplexTestUsingCode/Client/");

Dim dualBinding As New WSDualHttpBinding()
Dim endptadr As New EndpointAddress("http://localhost:12000/DuplexTestUsingCode/Server")
dualBinding.ClientBaseAddress = New Uri("http://localhost:8000/DuplexTestUsingCode/Client/")

Kode berikut menunjukkan cara melakukan ini dalam file konfigurasi

<client>
  <endpoint
    name ="ServerEndpoint"
    address="http://localhost:12000/DuplexUsingConfig/Server"
    bindingConfiguration="WSDualHttpBinding_IDuplex"
    binding="wsDualHttpBinding"
    contract="IDuplex"
/>
</client>
<bindings>
  <wsDualHttpBinding>
    <binding
      name="WSDualHttpBinding_IDuplex"
      clientBaseAddress="http://localhost:8000/myClient/"
    />
  </wsDualHttpBinding>
</bindings>

Memanggil Layanan Secara Asinkron

Bagaimana operasi dipanggil sepenuhnya terserah pengembang klien. Ini karena pesan yang membentuk operasi dapat dipetakan ke metode sinkron atau asinkron ketika dinyatakan dalam kode terkelola. Oleh karena itu, jika Anda ingin membangun klien yang memanggil operasi secara asinkron, Anda dapat menggunakan Svcutil.exe untuk menghasilkan kode klien asinkron menggunakan opsi /async. Untuk informasi selengkapnya, lihat Cara: Operasi Layanan Panggilan Secara Asinkron.

Memanggil Layanan Menggunakan Saluran Klien WCF

Jenis klien WCF memperluas ClientBase<TChannel>, yang sendiri berasal dari antarmuka System.ServiceModel.IClientChannel untuk mengekspos sistem saluran yang mendasar. Anda dapat memanggil layanan dengan menggunakan kontrak layanan target dengan kelas System.ServiceModel.ChannelFactory<TChannel>. Untuk detailnya, lihat Arsitektur Klien WCF.

Bagikan melalui