Adatátvitel megadása a szolgáltatási szerződésekben
A Windows Communication Foundation (WCF) üzenetkezelési infrastruktúraként is felfogható. A szolgáltatásműveletek üzeneteket fogadhatnak, feldolgozhatnak és üzeneteket küldhetnek nekik. Az üzenetek leírása műveleti szerződések használatával történik. Vegyük például a következő szerződést.
[ServiceContract]
public interface IAirfareQuoteService
{
[OperationContract]
float GetAirfare(string fromCity, string toCity);
}
<ServiceContract()>
Public Interface IAirfareQuoteService
<OperationContract()>
Function GetAirfare(fromCity As String, toCity As String) As Double
End Interface
Itt a GetAirfare művelet elfogad egy üzenetet, amelyről fromCitytoCityinformációt tartalmaz, majd egy számot tartalmazó üzenetet ad vissza.
Ez a témakör azt ismerteti, hogy a műveleti szerződés hogyan írhatja le az üzeneteket.
Üzenetek leírása paraméterek használatával
Az üzenet leírásának legegyszerűbb módja egy paraméterlista és a visszatérési érték használata. Az előző példában a kérési üzenet leírásához a fromCitytoCity sztringparamétereket használták, a lebegőpontos visszatérési értéket pedig a válaszüzenet leírására. Ha önmagában a visszatérési érték nem elegendő egy válaszüzenet leírásához, akkor a kiugró paraméterek használhatók. Az alábbi művelet fromCity például a kérelemüzenetben és toCity a válaszüzenetben szereplő pénznemmel együtt tartalmaz egy számot:
[OperationContract]
float GetAirfare(string fromCity, string toCity, out string currency);
<OperationContract()>
Function GetAirfare(fromCity As String, toCity As String) As Double
Emellett referenciaparaméterek használatával is a kérés és a válaszüzenet részét képezheti egy paraméter. A paramétereknek szerializálható (XML-gé konvertálható) típusúaknak kell lenniük. Alapértelmezés szerint a WCF egy osztály nevű DataContractSerializer összetevőt használ az átalakítás végrehajtásához. A legtöbb primitív típus (például int, string, floatés DateTime.) támogatott. A felhasználó által definiált típusoknak általában adatszerződéssel kell rendelkezniük. További információ: Adatszerződések használata.
public interface IAirfareQuoteService
{
[OperationContract]
float GetAirfare(Itinerary itinerary, DateTime date);
[DataContract]
public class Itinerary
{
[DataMember]
public string fromCity;
[DataMember]
public string toCity;
}
}
Public Interface IAirfareQuoteService
<OperationContract()>
GetAirfare(itinerary as Itinerary, date as DateTime) as Double
<DataContract()>
Class Itinerary
<DataMember()>
Public fromCity As String
<DataMember()>
Public toCity As String
End Class
End Interface
Időnként a DataContractSerializer típusok szerializálásához nem megfelelő. A WCF támogatja az alternatív szerializálási motort, XmlSerializera paraméterek szerializálására is használható. Ez XmlSerializer lehetővé teszi, hogy az eredményül kapott XML-hez több vezérlést használjon olyan attribútumok használatával, mint például a XmlAttributeAttribute. Ha az adott művelet vagy a XmlSerializer teljes szolgáltatás használatára szeretne váltani, alkalmazza az XmlSerializerFormatAttribute attribútumot egy műveletre vagy szolgáltatásra. Példa:
[ServiceContract]
public interface IAirfareQuoteService
{
[OperationContract]
[XmlSerializerFormat]
float GetAirfare(Itinerary itinerary, DateTime date);
}
public class Itinerary
{
public string fromCity;
public string toCity;
[XmlAttribute]
public bool isFirstClass;
}
<ServiceContract()>
Public Interface IAirfareQuoteService
<OperationContract()>
<XmlSerializerFormat>
GetAirfare(itinerary as Itinerary, date as DateTime) as Double
End Interface
Class Itinerary
Public fromCity As String
Public toCity As String
<XmlSerializerFormat()>
Public isFirstClass As Boolean
End Class
További információ: Az XmlSerializer osztály használata. Ne feledje, hogy az XmlSerializer itt látható módon történő manuális váltás nem ajánlott, kivéve, ha erre a témakörben részletezett konkrét indokai vannak.
Ha el szeretné különíteni a .NET-paraméterneveket a szerződésnevektől, használhatja az MessageParameterAttribute attribútumot, és a Name tulajdonság használatával beállíthatja a szerződés nevét. Az alábbi műveleti szerződés például egyenértékű a jelen témakörben szereplő első példával.
[OperationContract]
public float GetAirfare(
[MessageParameter(Name="fromCity")] string originCity,
[MessageParameter(Name="toCity")] string destinationCity);
<OperationContract()>
Function GetAirfare(<MessageParameter(Name := "fromCity")> fromCity As String, <MessageParameter(Name := "toCity")> toCity As String) As Double
Üres üzenetek leírása
Egy üres kérésüzenetet úgy lehet leírni, hogy nincsenek bemeneti vagy hivatkozási paraméterek. Például a C#-ban:
[OperationContract]
public int GetCurrentTemperature();
Például a Visual Basicben:
<OperationContract()>
Function GetCurrentTemperature() as Integer
Az üres válaszüzenetek leírása egy visszatérési típussal void és kimeneti vagy referenciaparaméterek nélkül írható le. Például:
[OperationContract]
public void SetTemperature(int temperature);
<OperationContract()>
Sub SetTemperature(temperature As Integer)
Ez eltér egy egyirányú művelettől, például:
[OperationContract(IsOneWay=true)]
public void SetLightbulbStatus(bool isOn);
<OperationContract(IsOneWay:=True)>
Sub SetLightbulbStatus(isOne As Boolean)
A SetTemperatureStatus művelet üres üzenetet ad vissza. Ha probléma merül fel a bemeneti üzenet feldolgozása során, hiba fordulhat elő. A SetLightbulbStatus művelet nem ad vissza semmit. Ebből a műveletből nem lehet hibafeltételt közölni.
Üzenetek leírása üzenetszerződések használatával
Érdemes lehet egyetlen típust használni a teljes üzenet megjelenítéséhez. Bár erre a célra adatszerződést is használhat, ennek ajánlott módja egy üzenetszerződés használata – ez elkerüli a felesleges sortörési szinteket az eredményül kapott XML-fájlban. Emellett az üzenetszerződések lehetővé teszik az eredményül kapott üzenetek nagyobb mértékű vezérlését. Eldöntheti például, hogy mely információk jelenjenek meg az üzenet törzsében, és melyek legyenek az üzenetfejlécekben. Az alábbi példa az üzenetszerződések használatát mutatja be.
[ServiceContract]
public interface IAirfareQuoteService
{
[OperationContract]
GetAirfareResponse GetAirfare(GetAirfareRequest request);
}
[MessageContract]
public class GetAirfareRequest
{
[MessageHeader] public DateTime date;
[MessageBodyMember] public Itinerary itinerary;
}
[MessageContract]
public class GetAirfareResponse
{
[MessageBodyMember] public float airfare;
[MessageBodyMember] public string currency;
}
[DataContract]
public class Itinerary
{
[DataMember] public string fromCity;
[DataMember] public string toCity;
}
<ServiceContract()>
Public Interface IAirfareQuoteService
<OperationContract()>
Function GetAirfare(request As GetAirfareRequest) As GetAirfareResponse
End Interface
<MessageContract()>
Public Class GetAirfareRequest
<MessageHeader()>
Public Property date as DateTime
<MessageBodyMember()>
Public Property itinerary As Itinerary
End Class
<MessageContract()>
Public Class GetAirfareResponse
<MessageBodyMember()>
Public Property airfare As Double
<MessageBodyMember()> Public Property currency As String
End Class
<DataContract()>
Public Class Itinerary
<DataMember()> Public Property fromCity As String
<DataMember()> Public Property toCity As String
End Class
További információ: Üzenetszerződések használata.
Az előző példában a DataContractSerializer rendszer alapértelmezés szerint továbbra is használja az osztályt. Az XmlSerializer osztály üzenetszerződésekkel is használható. Ehhez alkalmazza az XmlSerializerFormatAttribute attribútumot a műveletre vagy a szerződésre, és használja az XmlSerializer üzenetfejlécek és a törzstagok osztályával kompatibilis típusokat.
Üzenetek leírása adatfolyamok használatával
A műveletekben lévő üzenetek leírásának másik módja, ha az Stream osztályt vagy annak egyik származtatott osztályát használja egy műveleti szerződésben, vagy üzenetszerződés törzstagjaként (ebben az esetben az egyetlen tagnak kell lennie). Bejövő üzenetek esetében a típusnak kell lennie Stream– származtatott osztályokat nem használhat.
A szerializáló meghívása helyett a WCF lekéri az adatokat egy streamből, és közvetlenül egy kimenő üzenetbe helyezi, vagy adatokat kér le egy bejövő üzenetből, és közvetlenül egy streambe helyezi. Az alábbi minta a streamek használatát mutatja be.
[OperationContract]
public Stream DownloadFile(string fileName);
<OperationContract()>
Function DownloadFile(fileName As String) As String
Egyetlen üzenettörzsben nem kombinálhat Stream és nem továbbíthat adatokat. A további adatok üzenetfejlécekbe való elhelyezéséhez használjon üzenetszerződést. Az alábbi példa a streamek helytelen használatát mutatja be a műveleti szerződés meghatározásakor.
//Incorrect:
// [OperationContract]
// public void UploadFile (string fileName, Stream fileData);
'Incorrect:
'<OperationContract()>
Public Sub UploadFile(fileName As String, fileData As StreamingContext)
Az alábbi minta a streamek helyes használatát mutatja be egy műveleti szerződés meghatározásakor.
[OperationContract]
public void UploadFile (UploadFileMessage message);
//code omitted
[MessageContract]
public class UploadFileMessage
{
[MessageHeader] public string fileName;
[MessageBodyMember] public Stream fileData;
}
<OperationContract()>
Public Sub UploadFile(fileName As String, fileData As StreamingContext)
'Code Omitted
<MessageContract()>
Public Class UploadFileMessage
<MessageHeader()>
Public Property fileName As String
<MessageBodyMember()>
Public Property fileData As Stream
End Class
További információ: Nagyméretű adatok és streamelés.
Az üzenetosztály használata
Ha teljes programozott módon szeretné szabályozni az elküldött vagy fogadott üzeneteket, közvetlenül használhatja az Message osztályt az alábbi példakódban látható módon.
[OperationContract]
public void LogMessage(Message m);
<OperationContract()>
Sub LogMessage(m As Message)
Ez egy speciális forgatókönyv, amelyet részletesen ismertetünk az Üzenetosztály használatával.
A hibaüzenetek leírása
A visszatérési érték és a kimeneti vagy referenciaparaméterek által leírt üzeneteken kívül minden olyan művelet, amely nem egyirányú, legalább két lehetséges üzenetet küldhet vissza: a normál válaszüzenetet és egy hibaüzenetet. Vegye figyelembe a következő üzemeltetési szerződést.
[OperationContract]
float GetAirfare(string fromCity, string toCity, DateTime date);
<OperationContract()>
Function GetAirfare(fromCity As String, toCity As String, date as DateTime)
Ez a művelet vagy egy számot tartalmazó float normál üzenetet, vagy egy hibakódot és leírást tartalmazó hibaüzenetet ad vissza. Ezt úgy teheti meg, hogy bedobja FaultException a szolgáltatás implementációját.
Az attribútum használatával FaultContractAttribute további lehetséges hibaüzeneteket is megadhat. A további hibáknak szerializálhatónak kell lenniük a DataContractSerializerkövetkező példakódban látható módon.
[OperationContract]
[FaultContract(typeof(ItineraryNotAvailableFault))]
float GetAirfare(string fromCity, string toCity, DateTime date);
//code omitted
[DataContract]
public class ItineraryNotAvailableFault
{
[DataMember]
public bool IsAlternativeDateAvailable;
[DataMember]
public DateTime alternativeSuggestedDate;
}
<OperationContract()>
<FaultContract(GetType(ItineraryNotAvailableFault))>
Function GetAirfare(fromCity As String, toCity As String, date as DateTime) As Double
'Code Omitted
<DataContract()>
Public Class
<DataMember()>
Public Property IsAlternativeDateAvailable As Boolean
<DataMember()>
Public Property alternativeSuggestedDate As DateTime
End Class
Ezek a további hibák a megfelelő adatszerződés-típus beírásával FaultException<TDetail> hozhatók létre. További információ: Kivételek és hibák kezelése.
Az osztály nem használható a XmlSerializer hibák leírására. Ez XmlSerializerFormatAttribute nincs hatással a tartalék szerződésekre.
Származtatott típusok használata
Érdemes lehet alaptípust használni egy műveletben vagy üzenetszerződésben, majd származtatott típust használni a művelet tényleges meghívásakor. Ebben az esetben az ServiceKnownTypeAttribute attribútumot vagy valamilyen alternatív mechanizmust kell használnia a származtatott típusok használatának engedélyezéséhez. Fontolja meg a következő műveletet.
[OperationContract]
public bool IsLibraryItemAvailable(LibraryItem item);
<OperationContract()>
Function IsLibraryItemAvailable(item As LibraryItem) As Boolean
Tegyük fel, hogy két típus, Book és Magazinea LibraryItem. Az alábbi típusok a műveletben IsLibraryItemAvailable való használatához az alábbiak szerint módosíthatja a műveletet:
[OperationContract]
[ServiceKnownType(typeof(Book))]
[ServiceKnownType(typeof(Magazine))]
public bool IsLibraryItemAvailable(LibraryItem item);
Másik lehetőségként használhatja az KnownTypeAttribute attribútumot, ha az alapértelmezett DataContractSerializer használatban van, ahogyan az az alábbi példakódban is látható.
[OperationContract]
public bool IsLibraryItemAvailable(LibraryItem item);
// code omitted
[DataContract]
[KnownType(typeof(Book))]
[KnownType(typeof(Magazine))]
public class LibraryItem
{
//code omitted
}
<OperationContract()>
Function IsLibraryItemAvailable(item As LibraryItem) As Boolean
'Code Omitted
<DataContract()>
<KnownType(GetType(Book))>
<KnownType(GetType(Magazine))>
Public Class LibraryItem
'Code Omitted
End Class
Az attribútumot XmlSerializera XmlIncludeAttribute .
Az ServiceKnownTypeAttribute attribútumot alkalmazhatja egy műveletre vagy a teljes szolgáltatásra. Az attribútumhoz hasonlóan KnownTypeAttribute elfogadja a meghívandó metódus típusát vagy nevét az ismert típusok listájának lekéréséhez. További információ: Adatszerződés ismert típusai.
A használat és a stílus megadása
A webszolgáltatások leírási nyelvével (WSDL) végzett szolgáltatások leírásakor a két gyakran használt stílus a dokumentum- és távoli eljáráshívás (RPC). A Dokumentum stílusban a rendszer a teljes üzenettörzset a sémával írja le, a WSDL pedig a séma elemeire hivatkozva írja le a különböző üzenettörzsrészeket. Az RPC stílusban a WSDL az egyes üzenetrészek sématípusára hivatkozik, nem pedig elemre. Bizonyos esetekben manuálisan kell kiválasztania az alábbi stílusok egyikét. Ezt megteheti az DataContractFormatAttribute attribútum alkalmazásával és a Style tulajdonság beállításával (ha a DataContractSerializer használatban van), vagy az XmlSerializerFormatAttribute attribútum beállításával Style (a XmlSerializerhasználata során).
Emellett a XmlSerializer szerializált XML két formáját is támogatja: Literal és Encoded. Literala leggyakrabban elfogadott űrlap, és az egyetlen űrlap, amely támogatja.DataContractSerializer Encoded a SOAP-specifikáció 5. szakaszában leírt örökölt űrlap, és nem ajánlott új szolgáltatásokhoz. Üzemmódra váltáshoz Encoded állítsa az Use attribútum tulajdonságát a XmlSerializerFormatAttribute következőre Encoded: .
A legtöbb esetben nem szabad módosítani a tulajdonságok alapértelmezett Use beállításaitStyle.
A szerializálási folyamat szabályozása
Az adatok szerializálási módjának testreszabásához számos dolgot elvégezhet.
Kiszolgálószerializálási Gépház módosítása
Ha az alapértelmezett DataContractSerializer érték használatban van, az attribútum szolgáltatásra való alkalmazásával ServiceBehaviorAttribute szabályozhatja a szolgáltatás szerializálási folyamatának bizonyos aspektusait. A tulajdonság használatával beállíthatja azt a MaxItemsInObjectGraph kvótát, amely korlátozza a deszerializálandó objektumok DataContractSerializer maximális számát. A tulajdonság használatával kikapcsolhatja a IgnoreExtensionDataObject ciklikusan lecsúszó verziószámozási funkciót. A kvótákkal kapcsolatos további információkért lásd az adatok biztonsági szempontjait. A ciklikus lecsatolásról további információt a Továbbítással kompatibilis adatszerződések című témakörben talál.
[ServiceBehavior(MaxItemsInObjectGraph=100000)]
public class MyDataService:IDataService
{
public DataPoint[] GetData()
{
// Implementation omitted
}
}
<ServiceBehavior(MaxItemsInObjectGraph:=100000)>
Public Class MyDataService Implements IDataService
Function GetData() As DataPoint()
‘ Implementation omitted
End Function
End Interface
Szerializálási viselkedések
A WCF-ben két viselkedés érhető el, amelyek DataContractSerializerOperationBehaviorXmlSerializerOperationBehavior automatikusan csatlakoztatva vannak attól függően, hogy melyik szerializálót használják egy adott művelethez. Mivel a rendszer automatikusan alkalmazza ezeket a viselkedéseket, általában nem kell tisztában lennie velük.
Azonban a DataContractSerializerOperationBehaviorMaxItemsInObjectGraphszerializálási folyamat testreszabásához használhatja a , IgnoreExtensionDataObjectés DataContractSurrogate a tulajdonságokat. Az első két tulajdonság jelentése megegyezik az előző szakaszban ismertetett jelentéssel. A tulajdonság segítségével engedélyezheti az DataContractSurrogate adatszerződés-helyettesítőket, amelyek hatékony mechanizmust jelentenek a szerializálási folyamat testreszabásához és kiterjesztéséhez. További információ: Adatszerződés-helyettesítők.
Ezzel testre szabhatja az DataContractSerializerOperationBehavior ügyfél- és kiszolgálószerializálást is. Az alábbi példa bemutatja, hogyan növelhető a kvóta az MaxItemsInObjectGraph ügyfélen.
ChannelFactory<IDataService> factory = new ChannelFactory<IDataService>(binding, address);
foreach (OperationDescription op in factory.Endpoint.Contract.Operations)
{
DataContractSerializerOperationBehavior dataContractBehavior =
op.Behaviors.Find<DataContractSerializerOperationBehavior>()
as DataContractSerializerOperationBehavior;
if (dataContractBehavior != null)
{
dataContractBehavior.MaxItemsInObjectGraph = 100000;
}
}
IDataService client = factory.CreateChannel();
Dim factory As ChannelFactory(Of IDataService) = New ChannelFactory(Of IDataService)(binding, address)
For Each op As OperationDescription In factory.Endpoint.Contract.Operations
Dim dataContractBehavior As DataContractSerializerOperationBehavior = op.Behaviors.Find(Of DataContractSerializerOperationBehavior)()
If dataContractBehavior IsNot Nothing Then
dataContractBehavior.MaxItemsInObjectGraph = 100000
End If
Next
Dim client As IDataService = factory.CreateChannel
A saját üzemeltetésű esetben a szolgáltatás egyenértékű kódja a következő:
ServiceHost serviceHost = new ServiceHost(typeof(IDataService))
foreach (ServiceEndpoint ep in serviceHost.Description.Endpoints)
{
foreach (OperationDescription op in ep.Contract.Operations)
{
DataContractSerializerOperationBehavior dataContractBehavior =
op.Behaviors.Find<DataContractSerializerOperationBehavior>()
as DataContractSerializerOperationBehavior;
if (dataContractBehavior != null)
{
dataContractBehavior.MaxItemsInObjectGraph = 100000;
}
}
}
serviceHost.Open();
Dim serviceHost As ServiceHost = New ServiceHost(GetType(IDataService))
For Each ep As ServiceEndpoint In serviceHost.Description.Endpoints
For Each op As OperationDescription In ep.Contract.Operations
Dim dataContractBehavior As DataContractSerializerOperationBehavior = op.Behaviors.Find(Of DataContractSerializerOperationBehavior)()
If dataContractBehavior IsNot Nothing Then
dataContractBehavior.MaxItemsInObjectGraph = 100000
End If
Next
Next
serviceHost.Open()
A webüzemelt esetben létre kell hoznia egy új ServiceHost származtatott osztályt, és egy szolgáltatásgazda-előállítót kell használnia a beépülő modulhoz.
Szerializálási Gépház szabályozása a konfigurációban
Az MaxItemsInObjectGraph alábbi IgnoreExtensionDataObject példában látható módon a végpont vagy a dataContractSerializer szolgáltatás viselkedésével konfigurálható és szabályozható.
<configuration>
<system.serviceModel>
<behaviors>
<endpointBehaviors>
<behavior name="LargeQuotaBehavior">
<dataContractSerializer
maxItemsInObjectGraph="100000" />
</behavior>
</endpointBehaviors>
</behaviors>
<client>
<endpoint address="http://example.com/myservice"
behaviorConfiguration="LargeQuotaBehavior"
binding="basicHttpBinding" bindingConfiguration=""
contract="IDataService"
name="" />
</client>
</system.serviceModel>
</configuration>
Megosztott típusú szerializálás, objektumdiagram-megőrzés és egyéni szerializálók
A DataContractSerializer szerializálás adatszerződések neveivel történik, nem pedig .NET-típusnevekkel. Ez összhangban van a szolgáltatásorientált architektúra elveivel, és nagy rugalmasságot tesz lehetővé – a .NET-típusok a vezetékszerződés befolyásolása nélkül változhatnak. Ritkán érdemes lehet a tényleges .NET-típusneveket szerializálni, ezáltal szoros kapcsolatot kell létrehoznia az ügyfél és a kiszolgáló között, hasonlóan az .NET-keretrendszer újraírási technológiához. Ez nem ajánlott eljárás, kivéve azokat a ritka eseteket, amelyek általában akkor fordulnak elő, amikor .NET-keretrendszer újratelepítésből a WCF-re migrálnak. Ebben az esetben az osztály helyett az NetDataContractSerializer osztályt kell használnia DataContractSerializer .
A DataContractSerializer normál módon objektumfaként szerializálja az objektumdiagramokat. Vagyis ha ugyanarra az objektumra többször hivatkoznak, akkor többször is szerializálódik. Vegyük például azt a példányt PurchaseOrder , amelynek két cím típusú mezője van meghívva billTo és shipTo. Ha mindkét mező ugyanarra a címpéldányra van állítva, két azonos címpéldány van a szerializálás és a deszerializálás után. Ez azért van így, mert az XML-beli objektumgráfok nem szabványos, interoperábilis módon ábrázolhatók (kivéve a régi SOAP kódolású szabványt, amely az XmlSerializerelőző szakaszban és a ).StyleUse Az objektumdiagramok fákként való szerializálásának bizonyos hátrányai vannak, például a körkörös hivatkozásokat tartalmazó gráfok nem szerializálhatók. Időnként valódi objektumdiagram-szerializálásra kell váltani, még akkor is, ha az nem interoperábilis. Ezt úgy teheti meg, hogy a DataContractSerializer létrehozott paramétert a preserveObjectReferences következőre trueállítja be: .
Esetenként a beépített szerializálók nem elegendőek a forgatókönyvhöz. A legtöbb esetben továbbra is használhatja azt az XmlObjectSerializer absztrakciót, amelyből mind a DataContractSerializerNetDataContractSerializer kettő származik.
Az előző három esetben (.NET-típus megőrzése, objektumdiagram megőrzése és teljesen egyéni XmlObjectSerializer-alapú szerializálás) mind egyéni szerializálót kell csatlakoztatni. Ehhez hajtsa végre az alábbi lépéseket:
Írja meg a saját viselkedését, amely a DataContractSerializerOperationBehavior.
Bírálja felül a két
CreateSerializermetódust, hogy saját szerializálót adjon vissza (vagy azNetDataContractSerializer, a DataContractSerializer beállítotttrueértékrepreserveObjectReferences, vagy a saját egyénireXmlObjectSerializer).A szolgáltatásgazda megnyitása vagy ügyfélcsatorna létrehozása előtt távolítsa el a meglévő DataContractSerializerOperationBehavior viselkedést, és csatlakoztassa az előző lépésekben létrehozott egyéni származtatott osztályt.
A speciális szerializálási fogalmakkal kapcsolatos további információkért lásd a szerializálást és a deszerializálást.