WCF istemcisine genel bakış

Makale
03/12/2024

Bu bölümde istemci uygulamalarının ne yapacağı, Windows Communication Foundation (WCF) istemcisini yapılandırma, oluşturma ve kullanma ve istemci uygulamalarının güvenliğini sağlama işlemleri açıklanmaktadır.

WCF İstemci Nesnelerini Kullanma

İstemci uygulaması, başka bir uygulamayla iletişim kurmak için WCF istemcisi kullanan yönetilen bir uygulamadır. WCF hizmeti için istemci uygulaması oluşturmak için aşağıdaki adımlar gerekir:

Hizmet uç noktası için hizmet sözleşmesini, bağlamaları ve adres bilgilerini alın.
Bu bilgileri kullanarak bir WCF istemcisi oluşturun.
Çağrı işlemleri.
WCF istemci nesnesini kapatın.

Aşağıdaki bölümlerde bu adımlar ele alınıyor ve aşağıdaki sorunlara kısa girişler sağlanmaktadır:

Hataları işleme.
İstemcileri yapılandırma ve güvenliğini sağlama.
Çift yönlü hizmetler için geri çağırma nesneleri oluşturma.
Hizmetleri zaman uyumsuz olarak çağırma.
İstemci kanallarını kullanarak hizmetleri çağırma.

Hizmet Sözleşmesini, Bağlamaları ve Adresleri Alma

WCF'de hizmetler ve istemciler yönetilen öznitelikleri, arabirimleri ve yöntemleri kullanarak sözleşmeleri modeller. İstemci uygulamasındaki bir hizmete bağlanmak için hizmet sözleşmesinin tür bilgilerini almanız gerekir. Genellikle ServiceModel Meta Veri Yardımcı Programı Aracı'nı (Svcutil.exe) kullanarak hizmet sözleşmesi için tür bilgilerini alırsınız. Yardımcı program hizmetten meta verileri indirir, istediğiniz dilde yönetilen bir kaynak kod dosyasına dönüştürür ve WCF istemci nesnenizi yapılandırmak için kullanabileceğiniz bir istemci uygulaması yapılandırma dosyası oluşturur. Örneğin, bir MyCalculatorServiceçağırmak için bir WCF istemci nesnesi oluşturacaksanız ve bu hizmetin meta verilerinin konumunda http://computerName/MyCalculatorService/Service.svc?wsdlyayımlandığını biliyorsanız, aşağıdaki kod örneği yönetilen kodda hizmet sözleşmesini içeren bir ClientCode.vb dosyayı almak için Svcutil.exe nasıl kullanılacağını gösterir.

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

Bu sözleşme kodunu istemci uygulamasına veya istemci uygulamasının bir WCF istemci nesnesi oluşturmak için kullanabileceği başka bir derlemeye derleyebilirsiniz. İstemci nesnesini hizmete düzgün şekilde bağlanacak şekilde yapılandırmak için yapılandırma dosyasını kullanabilirsiniz.

Bu işlemin bir örneği için bkz . Nasıl yapılır: İstemci Oluşturma. Sözleşmeler hakkında daha fazla bilgi için bkz . Sözleşmeler.

WCF İstemci Nesnesi Oluşturma

WCF istemcisi, istemcinin uzak hizmetle iletişim kurmak için kullanabileceği biçimde bir WCF hizmetini temsil eden yerel bir nesnedir. WCF istemci türleri hedef hizmet sözleşmesini uygular, böylece bir tane oluşturup yapılandırdığınızda, hizmet işlemlerini çağırmak için istemci nesnesini doğrudan kullanabilirsiniz. WCF çalışma zamanı, yöntem çağrılarını iletilere dönüştürür, hizmete gönderir, yanıtı dinler ve bu değerleri WCF istemci nesnesine dönüş değerleri veya outref parametreler olarak döndürür.

Hizmetlere bağlanmak ve hizmetleri kullanmak için WCF istemci kanalı nesnelerini de kullanabilirsiniz. Ayrıntılar için bkz . WCF İstemci Mimarisi.

Yeni WCF Nesnesi Oluşturma

Bir ClientBase<TChannel> sınıfın kullanımını göstermek için, bir hizmet uygulamasından aşağıdaki basit hizmet sözleşmesinin oluşturulduğunu varsayalım.

Not

WCF istemcinizi oluşturmak için Visual Studio kullanıyorsanız, projenize bir hizmet başvurusu eklediğinizde nesneler nesne tarayıcısına otomatik olarak yüklenir.

[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);
}

Visual Studio kullanmıyorsanız, genişleten ClientBase<TChannel> türü ve hizmet sözleşmesi arabirimini ISampleServicebulmak için oluşturulan sözleşme kodunu inceleyin. Bu durumda, bu tür aşağıdaki koda benzer:

[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);
    }
}

Bu sınıf, oluşturuculardan biri kullanılarak yerel bir nesne olarak oluşturulabilir, yapılandırılabilir ve ardından türünde ISampleServicebir hizmete bağlanmak için kullanılabilir.

Önce WCF istemci nesnenizi oluşturmanız, ardından bunu kullanmanız ve tek bir try/catch bloğu içinde kapatmanız önerilir. Belirli hata modlarında özel durumları maskeleyebileceğinden deyimini using (Using Visual Basic'te) kullanmayın. Daha fazla bilgi için aşağıdaki bölümlerin yanı sıra WCF istemci kaynaklarını serbest bırakmak için Kapat ve Durdur'u kullanma bölümlerine bakın.

Sözleşmeler, Bağlamalar ve Adresler

WCF istemci nesnesi oluşturabilmeniz için önce istemci nesnesini yapılandırmanız gerekir. Özellikle, kullanılacak bir hizmet uç noktası olmalıdır. Uç nokta, hizmet sözleşmesi, bağlama ve adres birleşimidir. (Uç noktalar hakkında daha fazla bilgi için bkz. Uç Noktalar: Adresler, Bağlamalar ve Sözleşmeler.) Bu bilgiler genellikle, Svcutil.exe aracının <oluşturduğu gibi bir istemci uygulama yapılandırma dosyasındaki endpoint> öğesinde bulunur ve istemci nesnenizi oluşturduğunuzda otomatik olarak yüklenir. Her iki WCF istemci türü de bu bilgileri program aracılığıyla belirtmenize olanak tanıyan aşırı yüklemelere sahiptir.

Örneğin, önceki örneklerde kullanılan için oluşturulan bir ISampleService yapılandırma dosyası aşağıdaki uç nokta bilgilerini içerir.

<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>

Bu yapılandırma dosyası öğesinde <client> bir hedef uç nokta belirtir. Birden çok hedef uç nokta kullanma hakkında daha fazla bilgi için veya oluşturucularına ChannelFactory<TChannel> bakınClientBase<TChannel>.

Çağırma İşlemleri

Bir istemci nesnesi oluşturup yapılandırdıktan sonra bir try/catch bloğu oluşturun, nesne yerel olduğunda yaptığınız gibi işlemleri çağırın ve WCF istemci nesnesini kapatın. İstemci uygulaması ilk işlemi çağırdığında, WCF otomatik olarak temel kanalı açar ve nesne geri dönüştürüldiğinde temel kanal kapatılır. (Alternatif olarak, diğer işlemleri çağırmadan önce veya bundan sonra kanalı açıkça açıp kapatabilirsiniz.)

Örneğin, aşağıdaki hizmet sözleşmeniz varsa:

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

Aşağıdaki kod örneğinde gösterildiği gibi bir WCF istemci nesnesi oluşturup yöntemlerini çağırarak işlemleri çağırabilirsiniz. WCF istemci nesnesinin açılması, çağrılması ve kapatılması tek bir try/catch bloğu içinde gerçekleşir. Daha fazla bilgi için bkz . WCF İstemcisi Kullanarak Hizmetlere Erişme ve WCF istemci kaynaklarını serbest bırakmak için Kapat ve Durdur'u kullanma.

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();
}

Hataları İşleme

Bir istemci uygulamasında, temel alınan istemci kanalı açılırken (bir işlemi açıkça veya otomatik olarak çağırarak), işlemleri çağırmak için istemci veya kanal nesnesi kullanılırken veya temel alınan istemci kanalı kapatıldığında özel durumlar oluşabilir. Uygulamaların, işlemler tarafından döndürülen SOAP hataları sonucunda oluşan nesnelere System.ServiceModel.FaultException ek olarak olası System.TimeoutException ve System.ServiceModel.CommunicationException özel durumları işlemeyi beklemesi en azından önerilir. İşlem sözleşmesinde belirtilen SOAP hataları, istemci uygulamalarına tür parametresinin SOAP hatasının ayrıntı türü olduğu bir System.ServiceModel.FaultException<TDetail> durum olarak yükseltilir. İstemci uygulamasındaki hata koşullarını işleme hakkında daha fazla bilgi için bkz . Gönderme ve Alma Hataları. bir istemcideki hataların nasıl işleneceğini gösteren eksiksiz bir örnek için bkz . Beklenen Özel Durumlar.

İstemcileri Yapılandırma ve Güvenliğini Sağlama

İstemciyi yapılandırma işlemi, genellikle bir yapılandırma dosyasından istemci veya kanal nesnesi için hedef uç nokta bilgilerinin gerekli yüklenmesiyle başlar, ancak bu bilgileri istemci oluşturucularını ve özelliklerini kullanarak program aracılığıyla da yükleyebilirsiniz. Ancak, belirli istemci davranışını etkinleştirmek ve birçok güvenlik senaryosu için ek yapılandırma adımları gerekir.

Örneğin, hizmet sözleşmeleri için güvenlik gereksinimleri hizmet sözleşmesi arabiriminde bildirilir ve Svcutil.exe bir yapılandırma dosyası oluşturduysanız, bu dosya genellikle hizmetin güvenlik gereksinimlerini destekleyebilecek bir bağlama içerir. Ancak bazı durumlarda istemci kimlik bilgilerini yapılandırma gibi daha fazla güvenlik yapılandırması gerekebilir. WCF istemcileri için güvenlik yapılandırması hakkında tam bilgi için bkz . İstemcilerin Güvenliğini Sağlama.

Ayrıca, özel çalışma zamanı davranışları gibi bazı özel değişiklikler istemci uygulamalarında etkinleştirilebilir. Özel istemci davranışını yapılandırma hakkında daha fazla bilgi için bkz . İstemci Davranışlarını Yapılandırma.

Çift Yönlü Hizmetler için Geri Çağırma Nesneleri Oluşturma

Çift yönlü hizmetler, hizmetin sözleşmenin gereksinimlerine göre çağırması için bir geri çağırma nesnesi sağlamak üzere istemci uygulamasının uygulaması gereken bir geri çağırma sözleşmesi belirtir. Geri çağırma nesneleri tam hizmetler olmasa da (örneğin, bir geri çağırma nesnesiyle kanal başlatamazsınız), uygulama ve yapılandırma amacıyla bunlar bir hizmet türü olarak düşünülebilir.

Çift yönlü hizmetlerin istemcileri:

Geri çağırma sözleşmesi sınıfı uygulayın.
Geri çağırma sözleşmesi uygulama sınıfının bir örneğini oluşturun ve WCF istemci oluşturucusna geçirdiğiniz nesneyi oluşturmak System.ServiceModel.InstanceContext için kullanın.
İşlemleri çağırıp işlem geri çağrılarını işleyin.

Çift yönlü WCF istemci nesneleri, geri çağırma hizmetinin yapılandırması da dahil olmak üzere geri çağırmaları desteklemek için gereken işlevselliği kullanıma sunmaları dışında, çift yönlü wcf istemci nesneleri, çift yönlü olmayan karşılıkları gibi çalışır.

Örneğin, geri çağırma sınıfındaki özniteliğin özelliklerini kullanarak geri çağırma nesnesi çalışma zamanı davranışının System.ServiceModel.CallbackBehaviorAttribute çeşitli yönlerini denetleyebilirsiniz. Başka bir örnek, geri çağırma nesnesini çağıran hizmetlere özel durum bilgilerinin döndürülmesi için sınıfının kullanılmasıdır System.ServiceModel.Description.CallbackDebugBehavior . Daha fazla bilgi için bkz . Çift Yönlü Hizmetler. Tam örnek için bkz . Çift yönlü.

Internet Information Services (IIS) 5.1 çalıştıran Windows XP bilgisayarlarında, çift yönlü istemcilerin sınıfını kullanarak bir istemci temel adresi belirtmesi System.ServiceModel.WSDualHttpBinding gerekir veya bir özel durum oluşturulur. Aşağıdaki kod örneği, bunun kodda nasıl yapılacağını gösterir.

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/")

Aşağıdaki kod, bunun bir yapılandırma dosyasında nasıl yapılacağını gösterir

<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>

Hizmetleri Zaman Uyumsuz Olarak Çağırma

İşlemlerin nasıl çağrıldığı tamamen istemci geliştiriciye bağlı. Bunun nedeni, bir işlemi oluşturan iletilerin yönetilen kodda ifade edildiğinde zaman uyumlu veya zaman uyumsuz yöntemlerle eşlenebileceğidir. Bu nedenle, işlemleri zaman uyumsuz olarak çağıran bir istemci oluşturmak istiyorsanız, seçeneğini kullanarak /async zaman uyumsuz istemci kodu oluşturmak için Svcutil.exe kullanabilirsiniz. Daha fazla bilgi için bkz . Nasıl yapılır: Hizmet İşlemlerini Zaman Uyumsuz Olarak Çağırma.

WCF İstemci Kanallarını Kullanarak Hizmetleri Çağırma

WCF istemci türleri, temel kanal sistemini kullanıma açmak için arabiriminden System.ServiceModel.IClientChannel türetilen öğesini genişletirClientBase<TChannel>. Sınıfıyla System.ServiceModel.ChannelFactory<TChannel> hedef hizmet sözleşmesini kullanarak hizmetleri çağırabilirsiniz. Ayrıntılar için bkz . WCF İstemci Mimarisi.

Share via