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étirányú szolgáltatásokhoz.

  • Szolgáltatáshívások aszinkron végrehajtása.

  • Szolgáltatások hívása klienscsatornák használatával.

A szolgáltatási szerződés, kötődések és címek megszerzé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ási szerződés típusadatait általában a ServiceModel Metadata Segédprogram (Svcutil.exe) használatával 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-futtatókörnyezet ü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.

Megjegyzé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álható, és ezután használható egy ilyen típusú ISampleService szolgá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 a using utasítást (Using Visual Basicben), mert bizonyos meghibásodási módok esetén 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 a Megszakítás parancsot.

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. (A végpontokról további információt a Végpontok: Címek, Kötések és Szerződések című témakörben talál.) 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 létrehoz, é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. A több célvégpont használatáról további információért tekintse meg a ClientBase<TChannel> vagy a ChannelFactory<TChannel> konstruktort.

Telefonálá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 lehetséges System.TimeoutException és System.ServiceModel.CommunicationException kivételek kezelésére számítsanak, valamint a System.ServiceModel.FaultException objektumok feldolgozására, amelyeket a műveletek által visszaadott SOAP-hibák okoznak. A műveleti szerződésben megadott SOAP-hibák az ügyfélalkalmazások számára úgy jelennek meg, mint System.ServiceModel.FaultException<TDetail>, ahol 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ásszerző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 futtatókörnyezeti 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 duplex szolgáltatásokhoz

A duplex szolgáltatások olyan callback szerződést határoznak meg, amelyet az ügyfélalkalmazásnak végre kell hajtania ahhoz, hogy a szolgáltatás a callback objektumot a szerződés követelményeinek megfelelően hívhassa meg. 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.

  • Készítsen egy példányt a visszahívási szerződés implementációs osztályából, majd ezt az objektumot használja fel a System.ServiceModel.InstanceContext objektum létrehozására, amelyet azután átad a WCF-ügyfél konstruktornak.

  • 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. Teljes mintáért tekintse meg a Duplex-et.

Az Internet Information Services (IIS) 5.1 rendszert futtató Windows XP rendszerű számítógépeken a kéteirányú ügyfeleknek meg kell adniuk egy ügyfélbázis-címet az System.ServiceModel.WSDualHttpBinding osztály használatával, különben kivétel keletkezik. 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./async További információért lásd: Hogyan végezze el a szolgáltatásműveleteket aszinkron módon.

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

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

Lásd még

  • Last updated on