WCF-ügyfél áttekintése

Ez a szakasz ismerteti az ügyfélalkalmazások működését, a Windows Communication Foundation (WCF) ügyfélalkalmazások konfigurálását, létrehozását és használatát, valamint az ügyfélalkalmazások biztonságossá tételét.

WCF-ügyfélobjektumok használata

Az ügyfélalkalmazások olyan felügyelt alkalmazások, amelyek WCF-ügyfelet használnak egy másik alkalmazással való kommunikációhoz. A WCF-szolgáltatás ügyfélalkalmazásának létrehozásához a következő lépések szükségesek:

1. Szerezze be egy szolgáltatásvégpont szolgáltatási szerződését, kötéseit és címadatait.

2. Hozzon létre egy WCF-ügyfelet ezekkel az információkkal.

3. Hívási műveletek.

4. Zárja be a WCF-ügyfélobjektumot.

A következő szakaszok ezeket a lépéseket ismertetik, és rövid bevezetést nyújtanak a következő problémákba:

• Hibák kezelése.

• Ügyfelek konfigurálása és védelme.

• Visszahívási objektumok létrehozása kétoldalas szolgáltatásokhoz.

• Szolgáltatások aszinkron hívása.

• Szolgáltatások hívása ügyfélcsatornák használatával.

A szolgáltatási szerződés, kötések és címek beszerzése

A WCF-ben a szolgáltatások és az ügyfelek felügyelt attribútumokat, interfészeket és metódusokat használó szerződéseket modelleznek. Egy ügyfélalkalmazás szolgáltatásához való csatlakozáshoz be kell szereznie a szolgáltatási szerződés típusadatait. A szolgáltatásszerződés típusadatait általában a ServiceModel Metadata segédprogrammal (Svcutil.exe) szerezheti be. A segédprogram letölti a metaadatokat a szolgáltatásból, átalakítja egy tetszőleges nyelven felügyelt forráskódfájllá, és létrehoz egy ügyfélalkalmazás-konfigurációs fájlt, amellyel konfigurálhatja a WCF-ügyfélobjektumot. Ha például egy WCF-ügyfélobjektumot hoz létre egy meghíváshoz MyCalculatorService, és tudja, hogy a szolgáltatás metaadatai a következő helyen http://computerName/MyCalculatorService/Service.svc?wsdlvannak közzétéve, akkor az alábbi kód példája bemutatja, hogyan használható Svcutil.exe a szolgáltatásszerződést ClientCode.vb tartalmazó fájl lekérésére a felügyelt kódban.

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

Ezt a szerződéses kódot lefordíthatja az ügyfélalkalmazásba vagy egy másik szerelvénybe, amelyet az ügyfélalkalmazás ezután felhasználhat egy WCF-ügyfélobjektum létrehozásához. A konfigurációs fájl használatával konfigurálhatja az ügyfélobjektumot a szolgáltatáshoz való megfelelő kapcsolódáshoz.

Példa erre a folyamatra: Útmutató: Ügyfél létrehozása. A szerződésekről további információt a Szerződések című témakörben talál.

WCF-ügyfélobjektum létrehozása

A WCF-ügyfél egy helyi objektum, amely egy WCF-szolgáltatást jelöl olyan formában, amellyel az ügyfél kommunikálhat a távoli szolgáltatással. A WCF-ügyféltípusok implementálják a célszolgáltatás-szerződést, így amikor létrehoz egyet, és konfigurálja, az ügyfélobjektumot közvetlenül használhatja a szolgáltatásműveletek meghívásához. A WCF futási ideje üzenetekké alakítja a metódushívásokat, elküldi őket a szolgáltatásnak, figyeli a választ, és visszaadja ezeket az értékeket a WCF-ügyfélobjektumnak visszaadott értékekként vagy outref paraméterekként.

A WCF ügyfélcsatorna-objektumaival is csatlakozhat a szolgáltatásokhoz és használhatja a szolgáltatásokat. További részletekért lásd: WCF-ügyfélarchitektúra.

Új WCF-objektum létrehozása

Az osztály használatának ClientBase<TChannel> szemléltetéséhez tegyük fel, hogy a következő egyszerű szolgáltatási szerződés jött létre egy szolgáltatásalkalmazásból.

Feljegyzés

Ha a Visual Studio használatával hozza létre a WCF-ügyfelet, a rendszer automatikusan betölti az objektumokat az objektumböngészőbe, amikor hozzáad egy szolgáltatáshivatkozást a projekthez.

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

Ha nem a Visual Studiót használja, vizsgálja meg a létrehozott szerződéskódot, és keresse meg a kiterjesztett típust ClientBase<TChannel> és a szolgáltatási szerződés felületét ISampleService. Ebben az esetben ez a típus a következő kódhoz hasonlóan néz ki:

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

Ez az osztály létrehozható helyi objektumként az egyik konstruktor használatával, konfigurálva, majd egy ilyen típusú ISampleServiceszolgáltatáshoz való csatlakozáshoz.

Javasoljuk, hogy először hozza létre a WCF-ügyfélobjektumot, majd használja, majd zárja be egyetlen próba-/fogási blokkban. Ne használja az utasítást (Usinga using Visual Basicben), mert bizonyos meghibásodási módban elfedheti a kivételeket. További információkért tekintse meg a következő szakaszokat, valamint a WCF-ügyfélerőforrások kiadásához használja a Bezárás és megszakítás lehetőséget.

Szerződések, kötések és címek

A WCF-ügyfélobjektum létrehozása előtt konfigurálnia kell az ügyfélobjektumot. Pontosabban egy szolgáltatásvégponttal kell rendelkeznie. A végpont egy szolgáltatási szerződés, egy kötés és egy cím kombinációja. (További információ a végpontokról: Végpontok: Címek, kötések és szerződések.) Ez az információ általában egy <ügyfélalkalmazás konfigurációs fájljának végpontelemében> található, például az, amelyet az Svcutil.exe eszköz generál, és az ügyfélobjektum létrehozásakor automatikusan betöltődik. Mindkét WCF-ügyféltípus túlterhelésekkel is rendelkezik, amelyek lehetővé teszik az információk programozott megadását.

Az előző példákban használt konfigurációs fájl ISampleService például a következő végpontinformációkat tartalmazza.

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

Ez a konfigurációs fájl egy célvégpontot határoz meg az <client> elemben. További információ a több célvégpont használatáról: a konstruktorok vagy a ClientBase<TChannel>ChannelFactory<TChannel> konstruktorok.

Hívási műveletek

Miután létrehozta és konfigurálta az ügyfélobjektumot, hozzon létre egy próba-/fogási blokkot, hívja meg a műveleteket ugyanúgy, mint ha az objektum helyi lenne, és zárja be a WCF-ügyfélobjektumot. Amikor az ügyfélalkalmazás meghívja az első műveletet, a WCF automatikusan megnyitja az alapul szolgáló csatornát, és az alapul szolgáló csatorna bezárul az objektum újrahasznosításakor. (Másik lehetőségként explicit módon is megnyithatja és bezárhatja a csatornát más műveletek meghívása előtt vagy azt követően.)

Ha például a következő szolgáltatási szerződése van:

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 műveletek meghívásához hozzon létre egy WCF-ügyfélobjektumot, és hívja meg a metódusait, ahogyan azt az alábbi kód példája szemlélteti. A WCF-ügyfélobjektum megnyitása, hívása és bezárása egyetlen kipróbálási/fogási blokkon belül történik. További információ: Szolgáltatások elérése WCF-ügyfél használatával, valamint a WCF-ügyfélerőforrások felszabadítása a Bezárás és megszakítás használatával.

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

Hibák kezelése

Kivételek léphetnek fel az ügyfélalkalmazásokban a mögöttes ügyfélcsatorna megnyitásakor (akár explicit módon, akár automatikusan egy művelet meghívásával), az ügyfél vagy a csatorna objektum használatával a műveletek meghívásához, vagy a mögöttes ügyfélcsatorna bezárásakor. Javasoljuk, hogy az alkalmazások legalább a műveletek által visszaadott SOAP-hibák miatt keletkező objektumokon kívül a lehetséges System.TimeoutException és System.ServiceModel.CommunicationException kivételeket is System.ServiceModel.FaultException kezeljék. A műveleti szerződésben megadott SOAP-hibák az ügyfélalkalmazások számára keletkeznek, mivel System.ServiceModel.FaultException<TDetail> a típusparaméter a SOAP-hiba részlettípusa. Az ügyfélalkalmazások hibafeltételeinek kezeléséről további információt a Hibák küldése és fogadása című témakörben talál. A teljes minta azt mutatja be, hogyan kezelhetők az ügyfél hibái, lásd : Várt kivételek.

Ügyfelek konfigurálása és védelme

Az ügyfél konfigurálása az ügyfél vagy csatornaobjektum célvégpont-adatainak szükséges betöltésével kezdődik, általában egy konfigurációs fájlból, bár ezt az információt programozott módon is betöltheti az ügyfélkonstruktorok és -tulajdonságok használatával. Azonban további konfigurációs lépésekre van szükség az ügyfél bizonyos viselkedésének engedélyezéséhez és számos biztonsági forgatókönyv esetében.

A szolgáltatási szerződések biztonsági követelményei például a szolgáltatási szerződés felületén vannak deklarálva, és ha Svcutil.exe létrehozott egy konfigurációs fájlt, ez a fájl általában tartalmaz egy kötést, amely képes támogatni a szolgáltatás biztonsági követelményeit. Bizonyos esetekben azonban több biztonsági konfigurációra lehet szükség, például az ügyfél hitelesítő adatainak konfigurálására. A WCF-ügyfelek biztonságának konfigurálásával kapcsolatos teljes információkért tekintse meg az ügyfelek biztonságossá tételét ismertető cikket.

Emellett néhány egyéni módosítás engedélyezhető az ügyfélalkalmazásokban, például az egyéni futásidejű viselkedésekben. Az egyéni ügyfélviselkedés konfigurálásáról további információt az Ügyfél viselkedésének konfigurálása című témakörben talál.

Visszahívási objektumok létrehozása Kétoldalas szolgáltatásokhoz

A kétoldalas szolgáltatások olyan visszahívási szerződést határoznak meg, amelyet az ügyfélalkalmazásnak végre kell hajtania ahhoz, hogy a szolgáltatás a szerződés követelményeinek megfelelően visszahívási objektumot biztosíthasson a híváshoz. Bár a visszahívási objektumok nem teljes körű szolgáltatások (például visszahívási objektummal nem lehet csatornát kezdeményezni), a megvalósítás és a konfiguráció szempontjából ezek egyfajta szolgáltatásnak tekinthetők.

A kétoldalas szolgáltatások ügyfeleinek:

• Visszahívási szerződés osztály implementálása.

• Hozza létre a visszahívási szerződés implementálási osztályának egy példányát, és hozza létre a System.ServiceModel.InstanceContext WCF-ügyfélkonstruktornak átadott objektumot.

• Műveletek meghívása és műveleti visszahívások kezelése.

A kétoldalas WCF-ügyfélobjektumok a nemduplex társaikhoz hasonlóan működnek, azzal a kivétellel, hogy elérhetővé teszik a visszahívások támogatásához szükséges funkciókat, beleértve a visszahívási szolgáltatás konfigurációját is.

A visszahívási objektum futtatókörnyezeti viselkedésének különböző aspektusait például a visszahívási osztály attribútumának System.ServiceModel.CallbackBehaviorAttribute tulajdonságaival szabályozhatja. Egy másik példa az osztály használata a System.ServiceModel.Description.CallbackDebugBehavior kivételadatok visszaadásához a visszahívási objektumot meghívó szolgáltatásoknak. További információ: Duplex Services. A teljes minta : Duplex.

Az Internet Information Services (IIS) 5.1 rendszert futtató Windows XP rendszerű számítógépeken a kétoldalas ügyfeleknek meg kell adniuk egy ügyfélbázis-címet az System.ServiceModel.WSDualHttpBinding osztály használatával, vagy kivételt kell eredményezniük. Az alábbi példakód bemutatja, hogyan teheti ezt meg a kódban.

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

Az alábbi kód bemutatja, hogyan teheti ezt meg egy konfigurációs fájlban

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

Szolgáltatások aszinkron hívása

A műveletek meghívása kizárólag az ügyfélfejlesztőn múlik. Ennek az az oka, hogy a műveletet alkotó üzenetek szinkronizált vagy aszinkron metódusra képezhetők le felügyelt kódban kifejezve. Ezért ha olyan ügyfelet szeretne létrehozni, amely aszinkron módon hívja meg a műveleteket, a Svcutil.exe használatával aszinkron ügyfélkódot hozhat létre a /async beállítással. További információ : A szolgáltatásműveletek aszinkron meghívása.

Szolgáltatások hívása WCF-ügyfélcsatornák használatával

A WCF-ügyféltípusok kiterjednek ClientBase<TChannel>, amely maga az interfészből System.ServiceModel.IClientChannel származik, hogy elérhetővé tegye a mögöttes csatornarendszert. A szolgáltatásokat az osztályhoz tartozó célszolgáltatás-szerződéssel System.ServiceModel.ChannelFactory<TChannel> hívhatja meg. További részletekért lásd: WCF-ügyfélarchitektúra.

Lásd még

• System.ServiceModel.ClientBase<TChannel>
• System.ServiceModel.ChannelFactory<TChannel>