Gambaran umum klien WCF

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.
Pengoperasian panggilan.
Tutup objek klien WCF.

Bagian berikut membahas langkah-langkah ini dan memberikan pengenalan 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.

Dapatkan Kontrak Layanan, Ikatan, dan Alamat

Di WCF, layanan dan klien membuat kontrak model menggunakan atribut, antarmuka, dan metode terkelola. Untuk menyambungkan ke layanan di aplikasi klien, Anda perlu mendapatkan informasi jenis untuk kontrak layanan. Biasanya, Anda mendapatkan informasi jenis untuk kontrak layanan dengan menggunakan ServiceModel Metadata Utility Tool (Svcutil.exe). Utilitas mengunduh metadata dari layanan, mengonversinya ke 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 ClientCode.vb file 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 terhubung dengan benar ke layanan .

Untuk contoh proses ini, lihat Cara: 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. Runtime WCF mengonversi panggilan metode menjadi pesan, mengirimkannya ke layanan, mendengarkan balasan, dan mengembalikan nilai tersebut ke objek klien WCF sebagai nilai yang dikembalikan 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 ClientBase<TChannel> kelas, asumsikan kontrak layanan sederhana berikut telah dihasilkan dari aplikasi layanan.

Nota

Jika Anda menggunakan Visual Studio untuk membuat klien WCF, 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 kontrak layanan ISampleService. 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 coba/tangkap. Jangan gunakan using pernyataan (Using di Visual Basic) karena dapat menutupi pengecualian dalam mode kegagalan tertentu. Untuk informasi lebih lanjut, lihat bagian berikut serta Gunakan opsi Tutup dan Batalkan untuk melepaskan sumber daya klien WCF.

Kontrak, Pengikatan, dan Alamat

Sebelum dapat membuat objek klien WCF, Anda harus mengonfigurasi objek klien. Secara khusus, harus memiliki titik akhir layanan untuk digunakan. Titik akhir adalah kombinasi 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 yang ISampleService 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 <client> elemen . Untuk informasi selengkapnya tentang penggunaan beberapa endpoint target, lihat konstruktor ClientBase<TChannel> atau ChannelFactory<TChannel>.

Operasi Pemanggilan

Setelah Anda membuat dan mengonfigurasi objek klien, buat blok coba/tangkap, panggil operasi dengan cara yang sama seperti yang Anda lakukan jika objek tersebut 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 sesudah melakukan panggilan 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 contoh kode berikut. Pembukaan, pemanggilan, dan penutupan objek klien WCF terjadi dalam satu blok coba/tangkap tunggal. 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 di 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 aplikasi menangani kemungkinan pengecualian System.TimeoutException dan System.ServiceModel.CommunicationException, di samping objek System.ServiceModel.FaultException yang mungkin dilemparkan akibat dari kesalahan SOAP yang dikembalikan oleh operasi. Kesalahan SOAP yang ditentukan dalam kontrak operasi diteruskan ke aplikasi klien sebagai System.ServiceModel.FaultException<TDetail> di mana parameter jenis menentukan jenis detail dari kesalahan SOAP tersebut. Untuk informasi selengkapnya tentang menangani kondisi kesalahan dalam aplikasi klien, lihat Kesalahan Pengiriman dan Penerimaan. Lihat Pengecualian yang Diharapkan untuk sampel lengkap yang memperlihatkan cara menangani kesalahan di klien.

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 dideklarasikan 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 di aplikasi klien, seperti perilaku runtime kustom. Untuk informasi selengkapnya tentang cara mengonfigurasi perilaku klien kustom, lihat Mengonfigurasi Perilaku Klien.

Membuat Objek Panggilan Balik untuk Layanan Dupleks

Layanan Duplex 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 sebagai semacam layanan.

Klien layanan dupleks harus:

Menerapkan kelas kontrak panggilan balik.
Buat instans kelas implementasi kontrak panggilan balik dan gunakan untuk membuat objek System.ServiceModel.InstanceContext yang Anda berikan ke konstruktor klien WCF.
Panggil operasi dan tangani umpan balik operasi.

Objek klien Duplex WCF 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 System.ServiceModel.CallbackBehaviorAttribute atribut pada kelas panggilan balik. Contoh lain adalah penggunaan System.ServiceModel.Description.CallbackDebugBehavior kelas untuk mengaktifkan pengembalian informasi pengecualian ke layanan yang memanggil objek panggilan balik. Untuk informasi selengkapnya, lihat Layanan Duplex. Untuk sampel lengkap, lihat Dupleks.

Pada komputer Windows XP yang menjalankan Internet Information Services (IIS) 5.1, klien dupleks harus menentukan alamat dasar klien menggunakan kelas System.ServiceModel.WSDualHttpBinding atau pengecualian akan dilemparkan. Contoh kode berikut menunjukkan cara melakukan ini 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>

Layanan Panggilan 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: Memanggil Operasi Layanan Secara Asinkron.

Layanan Panggilan Menggunakan Saluran Klien WCF

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

Lihat juga

Last updated on 2023-04-07

Bagikan melalui