Szolgáltatási szerződések tervezése

Ez a témakör bemutatja, hogy mik a szolgáltatási szerződések, hogyan vannak definiálva, milyen műveletek érhetők el (és milyen következményekkel jár a mögöttes üzenetcserékre), milyen adattípusokat használnak, és egyéb problémákat, amelyek segítenek a forgatókönyv követelményeinek megfelelő műveletek tervezésében.

Szolgáltatási szerződés létrehozása

A szolgáltatások számos műveletet elérhetővé tehetnek. A Windows Communication Foundation (WCF) alkalmazásokban definiálja a műveleteket egy metódus létrehozásával és az OperationContractAttribute attribútummal való megjelölésével. Ezután egy szolgáltatási szerződés létrehozásához csoportosítsa a műveleteket úgy, hogy deklarálja őket egy ServiceContractAttribute attribútummal megjelölt felületen, vagy egy azonos attribútummal megjelölt osztályban definiálja őket. (Alapszintű példáért lásd: Útmutató: Szolgáltatási szerződés definiálása.)

Az attribútummal OperationContractAttribute nem rendelkező metódusok nem szolgáltatásműveletek, és nem érhetők el a WCF-szolgáltatások által.

Ez a témakör a következő döntési pontokat ismerteti egy szolgáltatási szerződés tervezésekor:

• Osztályokat vagy interfészeket használjon.

• Az cserélni kívánt adattípusok megadása.

• A használható csereminták típusai.

• Hogy a szerződés részét képezheti-e explicit biztonsági követelményeknek.

• A műveleti bemenetek és kimenetek korlátozásai.

Osztályok vagy felületek

Az osztályok és a felületek egyaránt a funkciók csoportosítását jelentik, ezért mindkettő használható WCF-szolgáltatási szerződés meghatározására. Javasoljuk azonban, hogy felületeket használjon, mert közvetlenül szolgáltatási szerződéseket modelleznek. Implementáció nélkül a felületek nem több, mint a metódusok bizonyos aláírásokkal való csoportosításának meghatározása. Implementáljon egy szolgáltatási szerződési felületet, és implementált egy WCF-szolgáltatást.

A felügyelt felületek minden előnye a szolgáltatási szerződés felületeire vonatkozik:

• A szolgáltatási szerződés felületei tetszőleges számú egyéb szolgáltatási szerződési felületet bővíthetnek.

• Egyetlen osztály bármilyen számú szolgáltatási szerződést implementálhat ezen szolgáltatási szerződési felületek implementálásával.

• A szolgáltatási szerződés implementációját módosíthatja a felület implementálásának módosításával, míg a szolgáltatási szerződés változatlan marad.

• A szolgáltatás verziószámozásához implementálhatja a régi felületet és az újat. A régi ügyfelek az eredeti verzióhoz csatlakoznak, míg az újabb ügyfelek az újabb verzióhoz csatlakozhatnak.

Ha például egy felületet használ egy szolgáltatási szerződés létrehozásához, olvassa el a How to: Create a Service with a Contract Interface (Szolgáltatás létrehozása szerződési felülettel) című témakört.

Egy osztály használatával azonban meghatározhat egy szolgáltatási szerződést, és egyidejűleg implementálhatja azt. A szolgáltatások létrehozásának előnye a sebesség és OperationContractAttribute az egyszerűség, ha közvetlenül az osztályra és az osztály módszereire alkalmazva ServiceContractAttribute hozza létre a szolgáltatásokat. Hátránya, hogy a felügyelt osztályok nem támogatják a többszörös öröklést, ezért egyszerre csak egy szolgáltatási szerződést tudnak megvalósítani. Ezenkívül az osztály- vagy metódusaadványok módosítása módosítja az adott szolgáltatásra vonatkozó közbeszerzési szerződést, ami megakadályozhatja, hogy a nem módosított ügyfelek használják a szolgáltatást. További információ: Szolgáltatásszerződések implementálása.

Ha például egy osztályt használ egy szolgáltatási szerződés létrehozására és egyidejű megvalósítására, olvassa el a Hogyan lehet: Szolgáltatás létrehozása szerződésosztályokkal című témakört.

Ezen a ponton meg kell értenie a szolgáltatási szerződés definiálása közötti különbséget egy felület és egy osztály használatával. A következő lépés annak eldöntése, hogy milyen adatok továbbíthatók oda-vissza egy szolgáltatás és ügyfelei között.

Paraméterek és visszatérési értékek

Minden műveletnek van egy visszatérési értéke és egy paramétere, még akkor is, ha ezek .void A helyi módszerekkel ellentétben azonban, ahol az objektumokra mutató hivatkozásokat továbbíthat egyik objektumról a másikra, a szolgáltatásműveletek nem adnak át hivatkozásokat objektumoknak. Ehelyett átadják az objektumok másolatait.

Ez azért jelentős, mert a paraméterben vagy a visszatérési értékben használt összes típusnak szerializálhatónak kell lennie; vagyis egy ilyen típusú objektumot bájtok adatfolyamává kell alakítani, és egy bájtos adatfolyamból objektummá kell alakítani.

A primitív típusok alapértelmezés szerint szerializálhatók, ahogyan a .NET-keretrendszer számos típusa is.

Adatszerződések

A szolgáltatásorientált alkalmazások, például a Windows Communication Foundation (WCF) alkalmazásokat úgy tervezték, hogy együttműködjenek a lehető legszélesebb számú ügyfélalkalmazással a Microsoft és a nem Microsoft platformokon. A lehető legszélesebb körű együttműködés érdekében ajánlott megjelölni a típusokat az adatszerződés létrehozásához használt DataContractAttribute attribútumokkal és DataMemberAttribute attribútumokkal, amely a szolgáltatási szerződés azon része, amely leírja a szolgáltatásműveletek által kicserélt adatokat.

Az adatszerződések engedélyezési stílusú szerződések: Nincs típus vagy adattag szerializálva, kivéve, ha kifejezetten alkalmazza az adatszerződés attribútumot. Az adatszerződések nem kapcsolódnak a felügyelt kód hozzáférési hatóköréhez: a privát adattagok szerializálhatók, és máshová is elküldhetők, hogy nyilvánosan elérhetők legyenek. (Az adatszerződés alapszintű példáját lásd: Útmutató: Alapszintű adatszerződés létrehozása osztályhoz vagy struktúrához.) A WCF kezeli a mögöttes SOAP-üzenetek definícióját, amelyek lehetővé teszik a művelet működését, valamint az adattípusok szerializálását az üzenetek törzsébe és azon kívülre. Mindaddig, amíg az adattípusok szerializálhatók, nem kell a mögöttes üzenetcsere-infrastruktúrára gondolnia a műveletek tervezésekor.

Bár a tipikus WCF-alkalmazás azokat és DataMemberAttribute attribútumokat használ a DataContractAttribute műveletekhez szükséges adatszerződések létrehozásához, más szerializálási mechanizmusokat is használhat. A standard ISerializable, SerializableAttributeés IXmlSerializable a mechanizmusok mind azon dolgoznak, hogy kezelje az adattípusok szerializálását a mögöttes SOAP-üzenetekbe, amelyek azokat az egyik alkalmazásból a másikba viszik. További szerializálási stratégiákat is alkalmazhat, ha az adattípusok különleges támogatást igényelnek. Az adattípusok WCF-alkalmazásokban való szerializálásával kapcsolatos további információkért lásd : Adatátvitel megadása a szolgáltatási szerződésekben.

Paraméterek leképezése és értékek visszaadása üzenetcserékbe

A szolgáltatásműveleteket olyan SOAP-üzenetek mögöttes cseréje támogatja, amelyek oda-vissza továbbítják az alkalmazás adatait, valamint az alkalmazás által bizonyos szabványos biztonsági, tranzakciós és munkamenetekkel kapcsolatos funkciók támogatásához szükséges adatokat. Mivel ez a helyzet, egy szolgáltatásművelet aláírása olyan mögöttes üzenetcsere-mintát (MEP) diktál, amely támogatja az adatátvitelt és a művelet által igényelt funkciókat. A WCF programozási modellben három mintát adhat meg: kérés-válasz, egyirányú és kétirányú üzenetminták.

Kérés/válasz

A kérés-/válaszminta olyan, amelyben a kérés feladója (egy ügyfélalkalmazás) olyan választ kap, amellyel a kérés korrelál. Ez az alapértelmezett európai parlamenti képviselő, mert olyan műveletet támogat, amelyben egy vagy több paramétert adnak át a műveletnek, és a rendszer visszaad egy visszatérési értéket a hívónak. Az alábbi C#-kód például egy alapszintű szolgáltatásműveletet mutat be, amely egy sztringet vesz fel, és egy sztringet ad vissza.

[OperationContractAttribute]  
string Hello(string greeting);  

Az alábbiakban az egyenértékű Visual Basic-kód látható.

<OperationContractAttribute()>  
Function Hello (ByVal greeting As String) As String  

Ez a műveleti aláírás határozza meg a mögöttes üzenetcsere formáját. Ha nem áll fenn korreláció, a WCF nem tudja meghatározni, hogy a visszatérési érték melyik műveletre vonatkozik.

Vegye figyelembe, hogy ha nem ad meg egy másik mögöttes üzenetmintát, még a (Visual Basicben) visszaadott voidNothing szolgáltatásműveletek is kérés-válaszüzenet-csereként szolgálnak. A művelet eredménye az, hogy ha egy ügyfél aszinkron módon nem hívja meg a műveletet, az ügyfél a visszatérési üzenet fogadásáig leáll a feldolgozással, annak ellenére, hogy az üzenet normál esetben üres. Az alábbi C#-kód példa egy olyan műveletet mutat be, amely addig nem ad vissza, amíg az ügyfél nem kapott üres üzenetet válaszként.

[OperationContractAttribute]  
void Hello(string greeting);  

Az alábbiakban az egyenértékű Visual Basic-kód látható.

<OperationContractAttribute()>  
Sub Hello (ByVal greeting As String)  

Az előző példa lelassíthatja az ügyfél teljesítményét és válaszképességét, ha a művelet végrehajtása hosszú időt vesz igénybe, de a kérési/válaszműveletek akkor is előnyösek, ha visszatérnek void. A legnyilvánvalóbb az, hogy a SOAP-hibák visszaadhatók a válaszüzenetben, ami azt jelzi, hogy valamilyen szolgáltatással kapcsolatos hibaállapot történt, akár a kommunikációban, akár a feldolgozásban. A szolgáltatási szerződésben megadott SOAP-hibák objektumként FaultException<TDetail> kerülnek átadásra az ügyfélalkalmazásnak, ahol a típusparaméter a szolgáltatási szerződésben megadott típus. Ez megkönnyíti az ügyfelek értesítését a WCF-szolgáltatások hibaállapotairól. A kivételekről, a SOAP-hibákról és a hibakezelésről további információt a Szerződések és szolgáltatások hibáinak megadása és kezelése című témakörben talál. A kérelem-válasz szolgáltatásra és az ügyfélre vonatkozó példa a Következő: Kérés-válasz szerződés létrehozása című témakörben olvasható. A kérés-válasz mintával kapcsolatos problémákról további információt a Request-Reply Services című témakörben talál.

Egyirányú

Ha egy WCF-szolgáltatásalkalmazás ügyfele nem várja meg a művelet befejezését, és nem dolgozza fel a SOAP-hibákat, a művelet megadhat egy egyirányú üzenetmintát. Az egyirányú művelet olyan művelet, amelyben az ügyfél meghív egy műveletet, és folytatja a feldolgozást, miután a WCF megírja az üzenetet a hálózatnak. Ez általában azt jelenti, hogy ha a kimenő üzenetben küldött adatok nem túl nagyok, az ügyfél szinte azonnal fut (kivéve, ha hiba történt az adatok küldésekor). Az ilyen típusú üzenetcsere-minta támogatja az eseményszerű viselkedést egy ügyféltől egy szolgáltatásalkalmazásig.

Az üzenetcserék, amelyekben egyetlen üzenet is el lett küldve, és egyik sem érkezik, nem támogathatók olyan szolgáltatásműveletek, amelyek a visszatérési értéken kívül voidmás értéket adnak meg; ebben az esetben InvalidOperationException kivétel történik.

A visszaküldött üzenet azt is jelenti, hogy a SOAP-hiba nem jelezheti a feldolgozás vagy a kommunikáció hibáit. (Ha egyirányú műveletekről van szükség, hibainformációk közlése kétirányú üzenetcserét igényel.)

Ha egy egyirányú üzenetcserét szeretne megadni egy visszaadott voidművelethez, állítsa a IsOneWay tulajdonságot truea következő C#-kód példában látható módon.

[OperationContractAttribute(IsOneWay=true)]  
void Hello(string greeting);  

Az alábbiakban az egyenértékű Visual Basic-kód látható.

<OperationContractAttribute(IsOneWay := True)>  
Sub Hello (ByVal greeting As String)  

Ez a módszer megegyezik az előző kérés/válasz példával, de a IsOneWay tulajdonság true beállítása azt jelenti, hogy bár a metódus azonos, a szolgáltatásművelet nem küld vissza üzenetet, és az ügyfelek azonnal visszatérnek, miután a kimenő üzenetet átadták a csatornarétegnek. Példa: Útmutató: Egyirányú szerződés létrehozása. Az egyirányú mintával kapcsolatos további információkért lásd : One-Way Services.

Duplex

A kétoldalas mintára jellemző, hogy a szolgáltatás és az ügyfél egymástól függetlenül is küldhet üzeneteket egymásnak, akár egyirányú, akár kérés-válasz típusú üzenetküldést használ. A kétirányú kommunikáció ezen formája olyan szolgáltatások esetében hasznos, amelyeknek közvetlenül kell kommunikálniuk az ügyfélrel, vagy aszinkron élményt nyújtanak az üzenetcsere mindkét oldalára, beleértve az eseményszerű viselkedést is.

A kétoldalas minta valamivel összetettebb, mint a kérés/válasz vagy az egyirányú minták az ügyféllel való kommunikáció további mechanizmusa miatt.

Kétoldalas szerződés kialakításához visszahívási szerződést is kell terveznie, és a visszahívási szerződés CallbackContract típusát a szolgáltatási szerződést jelző attribútum tulajdonságához ServiceContractAttribute kell rendelnie.

Kétoldalas minta implementálásához létre kell hoznia egy második felületet, amely tartalmazza az ügyfélen meghívott metódusdeklarációkat.

Egy szolgáltatás és egy szolgáltatáshoz hozzáférő ügyfél létrehozására példa: Útmutató: Kétoldalas szerződés létrehozása és útmutató: Szolgáltatások elérése kétoldalas szerződéssel. Működő minta : Kétoldalas. A kétoldalas szerződések használatával kapcsolatos problémákról további információt a Duplex Servicesben talál.

Kimenő és újrafedő paraméterek

A legtöbb esetben használhat in paramétereket (ByVala Visual Basicben) és refout paramétereket (ByRefa Visual Basicben). Mivel mind a ref paraméterek, mind out a paraméterek azt jelzik, hogy az adatok egy műveletből származnak, a művelet aláírása, például az alábbi, azt határozza meg, hogy szükség van-e egy kérési/válaszműveletre annak ellenére, hogy a művelet aláírása visszaadjavoid.

[ServiceContractAttribute]  
public interface IMyContract  
{  
  [OperationContractAttribute]  
  public void PopulateData(ref CustomDataType data);  
}  

Az alábbiakban az egyenértékű Visual Basic-kód látható.

<ServiceContractAttribute()> _  
Public Interface IMyContract  
  <OperationContractAttribute()> _  
  Public Sub PopulateData(ByRef data As CustomDataType)  
End Interface  

Az egyetlen kivétel azok az esetek, amikor az aláírásnak egy adott struktúrája van. A kötéssel NetMsmqBinding például csak akkor kommunikálhat az ügyfelekkel, ha a művelet deklarálásához használt módszer visszaad void; nem lehet kimeneti érték, legyen szó visszatérési értékről refvagy out paraméterről.

Emellett a használathoz out vagy ref paraméterekhez szükség van arra, hogy a művelet mögöttes válaszüzenettel rendelkezzen a módosított objektum visszatartásához. Ha a művelet egyirányú művelet, a rendszer kivételt InvalidOperationException jelez futásidőben.

Üzenetvédelmi szint megadása a szerződésen

A szerződés tervezésekor a szerződést megvalósító szolgáltatások üzenetvédelmi szintjét is el kell döntenie. Erre csak akkor van szükség, ha az üzenetbiztonságot a szerződés végpontján lévő kötésre alkalmazza a rendszer. Ha a kötés biztonsági állapota ki van kapcsolva (vagyis ha a rendszer által biztosított kötés az értéket SecurityMode.Noneállítja beSystem.ServiceModel.SecurityMode), akkor nem kell a szerződés üzenetvédelmi szintjét választania. A legtöbb esetben az üzenetszintű biztonsággal rendelkező rendszer által biztosított kötések megfelelő védelmi szintet biztosítanak, és nem kell figyelembe vennie az egyes műveletek vagy üzenetek védelmi szintjét.

A védelmi szint egy érték, amely meghatározza, hogy a szolgáltatást támogató üzenetek (vagy üzenetrészek) aláírással, aláírással és titkosítással vannak-e aláírva, aláírva és titkosítva, illetve aláírás vagy titkosítás nélkül küldve. A védelmi szint különböző hatókörökben állítható be: szolgáltatásszinten, egy adott művelethez, egy adott műveleten belüli üzenethez vagy üzenetrészhez. Az egy hatókörben beállított értékek lesznek a kisebb hatókörök alapértelmezett értékei, kivéve, ha explicit módon felül van bírálva. Ha egy kötéskonfiguráció nem tudja biztosítani a szerződéshez szükséges minimális védelmi szintet, kivételt jelent. Ha a szerződés nem állít be kifejezetten védelmi szintű értékeket, a kötéskonfiguráció szabályozza az összes üzenet védelmi szintjét, ha a kötés üzenetbiztonságot biztosít. Ez az alapértelmezett viselkedés.

Az alábbi példakód például nem állítja be sem a ProtectionLevel szerződést, sem a ProtectionLevel tulajdonságot.

[ServiceContract]  
public interface ISampleService  
{  
  [OperationContractAttribute]  
  public string GetString();  
  
  [OperationContractAttribute]  
  public int GetInt();
}  

Az alábbiakban az egyenértékű Visual Basic-kód látható.

<ServiceContractAttribute()> _  
Public Interface ISampleService  
  
  <OperationContractAttribute()> _  
  Public Function GetString()As String  
  
  <OperationContractAttribute()> _  
  Public Function GetData() As Integer  
  
End Interface  

Ha egy végpont implementációjával ISampleService kommunikál egy alapértelmezett WSHttpBinding (alapértelmezett System.ServiceModel.SecurityMode) végponton, Messageaz összes üzenet titkosítva és aláírva lesz, mert ez az alapértelmezett védelmi szint. Ha azonban egy ISampleService szolgáltatást alapértelmezettként BasicHttpBinding használ (ez az alapértelmezett SecurityModeérték None), a rendszer minden üzenetet szövegként küld el, mert nincs biztonság a kötéshez, ezért a védelmi szint figyelmen kívül lesz hagyva (vagyis az üzenetek nem titkosítottak és nem aláírtak). Ha a SecurityMode módosítás Messagemegtörtént, akkor ezek az üzenetek titkosítva és aláírva lesznek (mivel ez lenne a kötés alapértelmezett védelmi szintje).

Ha kifejezetten meg szeretné adni vagy módosítani szeretné a szerződés védelmi követelményeit, állítsa a ProtectionLevel tulajdonságot (vagy a kisebb hatókörű tulajdonságok bármelyikét ProtectionLevel ) a szolgáltatási szerződés által megkövetelt szintre. Ebben az esetben az explicit beállítás használatához a kötésnek támogatnia kell a megadott beállítást a használt hatókörhöz minimálisan. Az alábbi példakód például explicit ProtectionLevel módon egy értéket határoz meg a GetGuid művelethez.

[ServiceContract]  
public interface IExplicitProtectionLevelSampleService  
{  
  [OperationContractAttribute]  
  public string GetString();  
  
  [OperationContractAttribute(ProtectionLevel=ProtectionLevel.None)]  
  public int GetInt();
  [OperationContractAttribute(ProtectionLevel=ProtectionLevel.EncryptAndSign)]  
  public int GetGuid();
}  

Az alábbiakban az egyenértékű Visual Basic-kód látható.

<ServiceContract()> _
Public Interface IExplicitProtectionLevelSampleService
    <OperationContract()> _
    Public Function GetString() As String
    End Function
  
    <OperationContract(ProtectionLevel := ProtectionLevel.None)> _
    Public Function GetInt() As Integer
    End Function
  
    <OperationContractAttribute(ProtectionLevel := ProtectionLevel.EncryptAndSign)> _
    Public Function GetGuid() As Integer
    End Function
  
End Interface  

A szerződést megvalósító IExplicitProtectionLevelSampleService és az alapértelmezett WSHttpBinding (alapértelmezett System.ServiceModel.SecurityMode) végpontot használó szolgáltatás a következő viselkedéssel rendelkezik Message:

• A GetString műveleti üzenetek titkosítva és aláírva vannak.

• A GetInt műveletüzenetek titkosítatlan és aláíratlan (azaz egyszerű) szövegként lesznek elküldve.

• A GetGuid művelet System.Guid egy titkosított és aláírt üzenetben lesz visszaadva.

A védelmi szintekről és azok használatáról további információt a Védelmi szint ismertetése című témakörben talál. További információ a biztonságról: Securing Services.

Egyéb műveleti aláírási követelmények

Egyes alkalmazásfunkciókhoz bizonyos típusú műveleti aláírás szükséges. A kötés például támogatja a NetMsmqBinding tartós szolgáltatásokat és az ügyfeleket, amelyekben egy alkalmazás a kommunikáció közepén újraindulhat, és ott folytathatja, ahol abbahagyta anélkül, hogy üzeneteket hiányoznak. (További információ: Üzenetsorok a WCF-ben.) A tartós műveleteknek azonban csak egy in paramétert kell igénybe venniük, és nincs visszatérési értékük.

Egy másik példa a típusok használata Stream a műveletekben. Mivel a Stream paraméter tartalmazza a teljes üzenettörzset, ha egy bemenet vagy kimenet (azaz paraméter, refout paraméter vagy visszatérési érték) típusú Stream, akkor a műveletben megadott egyetlen bemenetnek vagy kimenetnek kell lennie. Emellett a paraméternek vagy a visszatérési típusnak vagy Streama paraméternek System.ServiceModel.Channels.Messagevagy System.Xml.Serialization.IXmlSerializablea visszatérési típusnak kell lennie. A streamekről további információt a Nagyméretű adatok és a Streamelés című témakörben talál.

Nevek, névterek és elfedések

A szerződések és műveletek definíciójában szereplő .NET-típusok nevei és névterei jelentősek a szerződések WSDL-vé alakításakor, valamint a szerződésüzenetek létrehozásakor és küldésekor. Ezért erősen ajánlott, hogy a szolgáltatásszerződések nevei és névterei explicit módon legyenek beállítva az NameNamespace összes támogató szerződésattribútum, például a ServiceContractAttribute, , OperationContractAttribute, DataContractAttributeDataMemberAttribute, és egyéb szerződésattribútumok tulajdonságaival.

Ennek egyik eredménye, hogy ha a nevek és a névterek nincsenek explicit módon beállítva, az IL-obfuscation használata a szerelvényen megváltoztatja a szerződéstípus-neveket és névtereket, és módosított WSDL- és vezetékcseréket eredményez, amelyek általában sikertelenek. Ha nem állítja be explicit módon a szerződésneveket és névtereket, de obfuscation-t kíván használni, használja az ObfuscationAttribute és ObfuscateAssemblyAttribute az attribútumokat a szerződéstípusnevek és névterek módosításának megakadályozására.

Lásd még

• Útmutató: Kérelem-válasz szerződés létrehozása
• Útmutató: Egyirányú szerződés létrehozása
• Útmutató: Kétoldalas szerződés létrehozása
• Adatátvitel megadása a szolgáltatási szerződésekben
• Szerződések és szolgáltatások hibáinak megadása és kezelése
• Munkamenetek használata
• Szinkron és aszinkron műveletek
• Reliable Services
• Szolgáltatások és tranzakciók