Kontrakt først - metoden i .NET
Web Services bliver brugt mere og mere indenfor programkommunikation mellem forskellige parter i det offentlige. Kontrakten mellem de involverede parter - både de rent juridiske og programmæssige - er vigtige for at få parternes samarbejde til at fungere. Videnskabsministeriet og IT- og Telestyrelsen har en standardaftale om XML-baserede webservices i uformel høring, som kan anvendes som udgangspunkt for den juridiske kontrakt. Til trods for at den juridiske kontrakt er meget vigtig i forholdet mellem en serviceaftager og en serviceudbyder, vil vi i det følgende udelukkende se på den programtekniske kontrakt. For at få den programtekniske kontrakt så præcis som mulig er det vigtigt at der i udviklingen af Web Services tages udgangspunkt i denne kontrakt. Problemstillingen beskrives i artiklen WSDL First. Nærværende tekst beskriver en skitse til en metode til udvikling af Web Services i Microsoft .NET Framework som tager udgangspunkt i den programtekniske kontrakt mellem serviceaftager og -udbyder. Baggrunden for at skrive metoden er, at der ikke findes udviklingsværktøjer, der understøtter Kontrak først - metoden. De nuværende værktøjer tager ikke udgangspunkt i kontrakten, men i implementationen af Web Servicen og generer herfra en kontrakt.
Udover det vigtige i at der fokuseres på at frembringe en præcis kontrakt mellem serviceaftager og -udbyder er der også mere praktiske årsager til at det er en god ide. OIO XML skemaer er en af byggestenene indenfor kommunikation mellem offentlige instanser og spiller derfor en rolle i de Web Service som bliver og vil blive udviklet i det offentlige. Hvis OIO XML skemaerne skal være med til at definere kontrakten mellem serviceaftager og -udbyder er det nødvendigt, at der tages udgangspunkt i kontrakten og ikke i Web Service implementationen.
Metoden er defineret ved nedenstående fem punkter, som umiddelbart ikke ser ud af meget, men kræver viden om XML. XML skemaer, OIO XML skemaer, WSDL samt Microsoft .NET Framework. Da der endvidere ikke er den store værktøjssupport er det besværligt - men ikke umuligt, som det kan ses af dette eksempel på brug af metoden.
- Udarbejd WSDL beskrivelsen af Web Servicen udfra skabelonen.
- Indsæt de i WSDL beskrivelsen refererede XML skemaer i WSDL beskrivelsen vha. Indsæt XML skemaer.
- Brug wsdl.exe til at generere en abstrakt klasse/interface som definerer Web Servicens interface i .NET.
- Implementer Web servicen med udgangspunkt i den abstrakte klasse.
- Valider Soap Message vha. Wsdl beskrivelsen
Nedenfor beskrives de ovenstående punkter i detaljer. Desuden kan du se et eksempel på anvendelsen af Kontrakt først - metoden her.
1. Udarbejd WSDL beskrivelsen af Web Servicen udfra skabelon
WSDL beskrivelsen danner kontrakten mellem klient og Web Service. Det vigtigeste i kontrakten er XML Skema beskrivelsen af de soap messages som Web Servicen kommunikerer. Start derfor med beskrive disse. Hvis de datatyper du anvender findes beskrevet i InfoStructureBase, så husk at brug og importer dem i WSDL'en. Herefter modeleres de operationer der ønskes tilbudt serviceaftageren. Udarbejdelsen af WSDL beskrivelsen kan tage udgangspunkt i skabelonen, som udover selve skabelonteksten indeholder en række trin som skal udføres for at danne kontrakten.
2. Indsæt de i WSDL beskrivelsen refererede XML skemaer
OIO XML skemaer er hyppigt fordelt over flere filer. .NETs XML skemaværktøjer, som xsd.exe og wsdl.exe, fungerer ikke, når et XML namespace er fordelt over flere XML skema filer. Derfor må de enkelte XML namespace samles i et XML skema dokument for at vi kan anvende wsdl.exe, som vi skal i næste trin af metoden. Til dette anvendes Indsæt XML skemaer, som samler hver enkelt XML namespace i et XML skema og indsætter disse XML skemaerne i WSDL filen.
Denne facilitet kan også anvendes til at tage et statisk billede af de anvendte XML skemaer på udviklingstidspunktet.
3. Brug wsdl.exe til at genere en abstrakt klasse som definerer Web Servicens interface i .NET
Programmet wsdl.exe bruges til at frembringe en abstrakt klasse i .NET, som danner basis for implementationen af Web Service'n. wsdl.exe aktiveres fra en commandprompt på følgende måde:
.NET Framework 1.1
wsdl.exe /server /out:fil.cs kontrakt.wsdl
.NET Framework 2.0
wsdl.exe /serverInterface /out:fil.cs kontrakt.wsdl
Hvor kontrakt.wsdl er den WSDL beskrivelse med de indsatte XML skemaer og fil.cs er den fil som den abstrakte klasse/interface skrives i.
4. Implementer Web servicen med udgangspunkt i den abstrakte klasse
Visual Studio 2003
Brug Visual Studio.NET 2003 til at lave et tomt Web Site projekt. Tilføj den ovenfor dannede abstrakte klasse. Lad VS.NET 2003 tilføje en Web Service til projektet, og lad denne Web Service klasse nedarve fra den abstrakte klasse. Kopier den abstrakte klasses attributterne til subklassen.
Overskriv de enkelte metoder. Kopier attributerne fra den tilsvarende abstrakte metode til den overskrevne metode. Implementer de enkelte metoder.
Visual Studio 2005
Brug Visual Studio.NET 2005 til at lave et tomt Web Site projekt. Tilføj det ovenfor dannede interface. Lad VS.NET 2005 tilføje en Web Service til projektet, og lad denne Web Service klasse nedarve fra interfacet. Namespace i WebService attributen ændres til targetnamespace fra wsdl beskrivelsen.
Overskriv de enkelte metoder.
Fjern den autogenerede wsdl beskrivelse
For at undgå at den autogenerede wsdl beskrivelse bliver anvendt kan du konfigurere din ASP.NET applikation til ikke at gøre det:
<webServices>
<protocols>
<remove name="Documentation" />
</protocols>
</webServices>
Læs mere om fjernelsen af den autogenerede dokumentation og wsdl beskrivelse her.
5. Valider Soap Message vha. Wsdl beskrivelsen
For at sikre at de Soap Message, som Web Servicen modtager, er valide i forhold til Soap og de i Wsdl beskrivelsen anvendte Xml skemaer valideres enhver Soap message som Web Servicen modtager. Til dette anvendes ASP.NET's SoapExtensions, som giver mulighed for at analyserere Soap Message'n før den deserialiseres. En artikel om validering vha. SoapExtensions findes her. I forbindelse med eksemplet har jeg lavet en assembly indeholdende en SoapExtension, som foretager validreringen op i mod Wsdl beskrivelsen. Enhver skal WebMethod som ønskes forsynet med validering skal markeres med attributten Validation med wsdl beskrivelsens navn som parameter, som f.eks. [Validation("Addressexpanded.wsdl")], hvor AddressExpanded.wsdl er navnet på Wsdl beskrivelsen.
Kommentarer
Alle former for kommentarer er velkomne til finn@jordal.dk.
Referencer
Using XML schemas effectively in WSDL design
Place XML Message Design Ahead of Schema Planning to Improve Web Service Interoperability
The Xml Files: WebMethod Validation, SOAP Validation, XmlSerializer, One-way Operations, and More