Utveckling av tjänster

Utveckling av tjänster Stockholms stad SOA-plattform 1 (22)

Innehållsförteckning 1 Inledning 3 2 Utvecklingsstandard 4 2.1 Namngivningskonventioner... 4 2.1.1 Namespaces... 4 2.1.2 Exempel... 4 2.1.3 Kontrakt... 5 2.1.4 Assemblies... 5 3 Utvecklingsstrategi 6 3.1 Contracts first... 6 3.2 Rekommendationer för datakontrakt... 6 3.3 Dataregler... 7 3.4 Regler för undantagshantering... 8 3.5 Restriktioner... 8 4 Utveckling av en SOA-tjänst 9 4.1 Utvecklingsmiljö... 9 4.2 Visual Studio solution... 9 4.2.1 Referenser till plattformen... 9 4.2.2 Projekt Som skall finnas i en solution... 9 4.3 Skapa en SOA-tjänst...12 4.3.1 Anpassning av SOAServiceTemplate...12 4.3.2 Deployment under utveckling...16 4.3.3 Säkerhet...17 4.3.4 Bindningar...17 5 Exempel på en SOA-tjänst Castle Tour BookingService 18 5.1 Demoprojektet...19 5.2 Kravspecifikationen...19 5.3 Design på implementerade WCF-tjänster...20 5.3.1 HotelManagement...20 5.3.2 TourService...21 5.4 Design av bokningshanteringen...22 2 (22)

1 INLEDNING Detta dokument är en handbok för utveckling av SOA-tjänster för Stockholm Stads SOA-plattform. Plattformen är byggd på Microsofts.Net4-plattform för Windows Communication Framework och BizTalk 2010. 3 (22)

2 UTVECKLINGSSTANDARD Här beskrivs de anvisningar som gäller för utvecklingsprocessen och som ska följas av alla utvecklare eller leverantörer som skapar SOA-tjänster på Stockholm stads SOAplattform. Utöver de anvisningar som beskrivs i detta dokument bör leverantörer även följa de generella anvisningar som fastställts av Microsoft i MSDN-biblioteket: Design Guidelines for Developing Class Libraries 1. 2.1 NAMNGIVNINGSKONVENTIONER Utöver de generella anvisningarna för design som fastställts av Microsoft, gäller även nedanstående regler för namespaces och assemblies. Leverantörsnamn får inte vara synligt i en applikations användargränssnitt eller i den URL-adress där applikationen kan nås. 2.1.1 NAMESPACES Namespaces måste följas enligt nedanstående schema Stockholm.SOA.[Applikation].WCF.[Tjänst][.[Sub-namespace]] Applikation Obligatorisk. Namn eller vedertagen förkortning på applikationen. Teknologi Obligatorisk. Anger typen av tjänst (WCF eller BizTalk) i namespaces. Tjänst Obligatorisk. Namnet på tjänst eller funktionaliteten som implementerats i namespaces, till exempel: UserManagement. Sub-namespace Obligatiorisk. Anger sub-namespace som lämpar sig för gruppering av typer. 2.1.2 EXEMPEL Stockholm.SOA.FileTransfer.WCF.Service.DataContracts Exemplet ovan visar i namespace att det är Filetransfertjänstens datakontrakt, och att det är en WCF-tjänst. För fler anvisningar angående namespaces, se anvisningarna på MSDN: Names of Namespaces 2. I detta dokument avänds Stockholm.SOA.MyService som exempel på flera ställen. MyService är endast ett exempel och avser det namn man kommer att ge sin SOA-tjänst. 1 http://msdn2.microsoft.com/en-gb/library/ms229042(vs.80).aspx 2 http://msdn2.microsoft.com/en-gb/library/ms229026(vs.80).aspx 4 (22)

2.1.3 KONTRAKT Kontraktens namespaces ska var enligt följande schema: Namespace= http://stockholm.se/soa/[applikation]/[tjänst]/[version] Applikation obligatorisk namn eller vedertagen förkortning av applikationen. Tjänst obligatoriskt, anger namnet på den tjänst kontraktet tillhandahåller Version obligatoriskt, anger versionen för kontraktet, detta används vid versionshantering av tjänsten. Ex Namespace= http://stockholm.se/soa/castletour/tourservice/2012/06/ Detta anger att applikationen är CastleTour, tjänsten är TourService och versionen är 2012/06. 2.1.4 ASSEMBLIES Namnet på ett assembly måste vara detsamma som filnamnet, men utan tillägget (DLL eller EXE). Namnet på assemblies måste även vara detsamma som rot-namespaces som definieras i assemblyn. Exempel - filnamnet på en assembly som heter Stockholm.SOA.CastleTours.WCF.DataContracts bör vara Stockholm.SOA.CastleTours.WCF.DataContracts.dll (eller.exe), och får inte definiera typer utanför namespacet Stockholm.SOA.CastleTours.WCF.DataContracts. 5 (22)

3 UTVECKLINGSSTRATEGI 3.1 CONTRACTS FIRST Alla SOA-projekt skall utföras enligt Contracts first principen. Det innebär att Data Contracts, Message Contracts och Service Contracts skapas först för att spegla hur scheman och gränssnitt skall se ut. Därefter kodas genomförandet. 3.2 REKOMMENDATIONER FÖR DATAKONTRAKT Dessa rekommendationer hjälper till att göra SOA-plattformen så löst kopplad och resistent mot förändringar som möjligt. Dessa regler har inte bara skapats för att upprätthålla någon slags estetik utan är till för att säkerställa en lägre TCO för alla ingående tjänster. De tjänster som inte implementerar dessa rekommendationer kommer inte heller att bli godkända i de tester som genomförs i produktionssättningen, och därför inte kunna driftsättas i SOA-plattformen. Alla datakontrakt ska vara document/literal. All tjänsteutveckling ska utföras enligt contract first. Alla operationer ska se ut enligt följande: ResponseMessageType MyOperation(RequestMessageType request). Inga parametrar eller returtyper får vara bastyper. Inga säkerhetsuppgifter får finnas med i datakontraktet. Detta gäller både för autentisering och behörigheter. Inga spårningsuppgifter får finnas med i datakontraktet. Inga uppgifter vad gäller fel får finnas med i kontraktet. Verksamhetsfel kan returneras till klienten som använder felkontrakt. Inga uppgifter som tillhör en klients GUI får finnas med i data- eller operationskontraktet. Datakontrakt som beskriver hierarkiska datastrukturer ska normaliseras. Inga insamlingar får användas på grund av det extra arbete det kommer innebära att lägga till.net-scheman till Mex-endpoints. En array kan användas istället. Inga ADO-objekt får används i datakontrakt. Inga.NET-typer får returneras eller användas. Affärsregler får inte tillämpas i datakontrakt. Det vill säga, restriktioner får inte ställas in på enkla typer i schemat. Alla datakontrakt ska implementera ordning av element. 6 (22)

3.3 DATAREGLER Det finns flera problem som man bör uppmärksamma: 1) Tjänsteanvändarna kan ibland behöva en lista på data som representerar ett val i ett frågemeddelande till en SOA-tjänst. 2) Meddelanden som innehåller referensdata, dvs. databasnycklar, blir hårdkodade mot databasstrukturen. Detta kallas tät koppling och bör undvikas. 3) Konstant behörighetshantering från SOA:s datatjänster kan mycket väl generera en belastning som den ursprungliga databasen helt enkelt inte är byggd för och inte heller kommer att klara av. 4) Om SOA-datatjänster används för en särskild typ av referensdata kan medföra att en mängd tjänster uppstår som i stort sett är lika. Detta kommer att skapa förvirring och slöseri av resurser. 5) Utvecklare är vana vid att skicka databasnycklar för att kunna förbättra prestandan. Detta skapar mindre databastabeller men otydliga meddelanden som är tätt kopplade till ursprungssystemet. I en federerad miljö kan typ och struktur på nycklarna vara många och ofta väldigt svåra att integrera tillsammans och samtidigt behålla originalstrukturen på nycklarna. Argument: textdata är unik, är mer betydelsefull och löst kopplad. Mappning kan göras på den adaptiva nivån. 1) Till exempel; en lista som kallas Kundtyp finns i tre databaser. Flera av SOAtjänsterna använder persontyp för att utföra en operation som återfinns i de tre olika systemen. En stund senare ska statistik tas fram baserat på Kundtyp och informationen från de tre operationerna grupperas. Hur ska då datat länkas? 2) I ett av ovanstående system har transaktionerna lång körtid och kan ta upp till flera månader att bli färdiga. Om referensdata finns i meddelandet och ändras medan transaktionen pågår, så blir data i meddelandet betydelselöst. 3) En ny kundtyp har lagts till i systemen. Om detta inte utförs på exakt samma tidpunkt i alla tre systemen kan data cirkulera runt och till slut hamna hos ett system där data inte har någon betydelse. 7 (22)

3.4 REGLER FÖR UNDANTAGSHANTERING WCF-tjänster ska returnera verksamhetsfel i felkontrakt. Verksamhetsfel ska som regel inte returneras som undantag. Alla undantag i BizTalk ska hanteras internt av ESB Exception Management Framework, ESB ramverk för undantagshantering. Alla undantag i tjänster utanför plattformen måste rapporteras genom webbtjänsten ESB Exception Management Framework. Om ett fel skulle uppstå i webbtjänsten måste undantaget loggas och rapporteras när tjänsten är tillgänglig igen. 3.5 RESTRIKTIONER SOA plattformen är uppbyggd på Microsoft.Net teknik, med stöd av Biztalk för transaktionskritiska och sammansatta tjänster. 8 (22)

4 UTVECKLING AV EN SOA-TJÄNST 4.1 UTVECKLINGSMILJÖ Se dokumentet Installation av utvecklingsmiljö 1.0. 4.2 VISUAL STUDIO SOLUTION Den Visual Studio-solution som används för utveckling består av flera projekt och referenser. Nedan följer en beskrivning av dessa referenser samt av varje projekt som ingår i solutionen. 4.2.1 REFERENSER TILL PLATTFORMEN SOA-tjänster behöver ha referenser till ESB.ExceptionHandling.WCF Dessa referenser ligger med i projektets mapp Stockholm.SOA.Template.WCF.TemplateService.WCFResources. Användningen av ESB Exception Handling finns beskriven i ServiceImplementation. 4.2.2 PROJEKT SOM SKALL FINNAS I EN SOLUTION 4.2.2.1 STOCKHOLM.SOA.[MYSERVICE].WCF.SERVICECONTRACTS Detta projekt skall innehålla de.net klasser som krävs för att kunna skapa ett servicekontrakt för en tjänst. Tjänstekontraktet definierar de funktioner och processer som publiceras. Namngivning av metoderna måste ske med ett prefix som hänvisar till den applikationen tjänsten byggs för. Annars kan det uppstå namnkonflikter vid virtualisering av tjänster. Om detta inte följs kommer tjänsten inte att godkännas för driftsättning i plattformen. [ServiceOperation(Namespace= http://stockholm.se/soa/[applikation] /[Tjänst]/[Version],Name= Tjänst )] Alla operationer skall följa konventionen [OperationContract(Action= http://stockholm.se/soa/[application]/wcf/[feature]/[ Version]/TemplateMyOperation,ReplyAction= http://stockholm.se/soa/[application]/wcf/[feature]/[version]/templatemyoperati on,name= TemplateMyOperation )] [FaultContractAttribute(typeof(FaultContracts.[FaultContractName]),Action= http://stockholm.se/soa/[application]/wcf/[feature]/[version]/[faultcontractnam e] )] ResponseMessageType TemplateMyOperation(RequestMessageType request) 9 (22)

4.2.2.2 STOCKHOLM.SOA.[MYSERVICE].WCF.SERVICEIMPLEMENTATION ServiceImplementationen måste ange ServiceBehavior(Namespace= http://stockholm.se/soa/[applikation]/wcf/[tjänst]/[ve rsion,name= TemplatedService )] 4.2.2.3 STOCKHOLM.SOA.[MYSERVICE].WCF.DATACONTRACTS Detta projekt skall innehålla de datakontrakt som används i lösningen. Alla attribut skall vara ordnade. [DataContract(Namespace= http://stockholm.se/soa/[applikation]/ [Tjänst]/[Version] name= MyDataContract )] Public class MyDataContract { [DataMember(Order=0,IsRequired=true,Name= MyDataMember1 )] public string MyDataMember1{get;set;} [DataMember(Order=1,IsReqired=false,Name= MyDataMember2 )] public string MyDataMember2{get;set;} } 4.2.2.4 STOCKHOLM.SOA.[MYSERVICE].WCF.MESSAGECONTRACTS Meddelande kontrakt skall också inta ett ordnat förhållande. [MessageContrac] public class MyMessageContract { [MessageHeader] Public string MessageIdentifier{get;set;} [MessageHeader] public string MyMessageHeader{get;set;} [MessageBodyMember(Order=0)] public string MyMessageBodyMember1{get;set;} [MessageBodyMember(Order=1)] public MyDataContract MyMessageBodyMember2{get;set;} För spårbarhetens skull kan det vara bra att ange ett meddelande-id i headern. 10 (22)

4.2.2.5 STOCKHOLM.SOA.[MYSERVICE].WCF.FAULTCONTRACTS Felkontrakt [DataContract(Namespace= http://stockholm.se/soa/[applikation] /[Tjänst]/[Version],Name= MyFault )] public class MyFault { [DataMember(Order=0)] public string Fault{get;set;} [DataMember(Order=1)] public string FaultMessage{get;set;} } 4.2.2.6 STOCKHOLM.SOA.[MYSERVICE].WCF.SERVICEIMPLEMENTATION Er implementationen skall läggas in i detta projekt. 11 (22)

4.3 SKAPA EN SOA-TJÄNST I SDK medföljer ett mallprojekt som är ett tomt skal för hur en solution för en SOA-tjänst ska se ut. För att skapa en e-tjänste-lösning, utgå från mallprojektet Stockholm.SOA.Template.WCF.Template 4.3.1 ANPASSNING AV SOASERVICETEMPLATE 1. Kopiera hela mappen Template SOA Service 2. Öppna Stockholm.SOA.Template.WCF.Template.sln 3. Ändra namespaces i alla projekt enligt kapitel 2, exempelvis från Stockholm.SOA.Template.WCF.TemplateService.DataContracts till Stockholm.SOA.MyApplication.WCF.MyService, genom att högerklicka på projekten och välja Properties > Application. OBS: Se till att inte använda ett för långt namn på servicen, då det kan göra att sökvägarna i projektet blir för långa. Detta kanske inte upptäcks förrän vid kompilering. En max längd på 60 tecken rekommenderas för Stockholm.SOA.MyApplication.WCF.MyService. Detta kan variera något beroende på strukturen för den katalog där projektet placeras. 12 (22)

4. Ändra namn på samtliga projekt så att de följer alla namespaces, genom att högerklicka på projektet och välja Rename 5. Ta bort samtliga projekt från lösningen, genom att högerklicka på projekten och välja Remove 13 (22)

6. Ändra namn på samtliga projektmappar i katalogen 7. När man ändrat alla mappnamn, lägg tillbaks samtliga projekt i lösningen, genom att högerklicka på Solution och välj Add > Existing Project. Lägg till samtliga projekt i katalogen. 14 (22)

8. När alla projekt/namespaces och kataloger har döpts om, gör en global sökning och ersätt Stockholm.SOA.Template.WCF.TemplateService med namnet på din etjänst, exempelvis Stockholm.SOA.[MyApplication].WCF.[MyService] 9. Ändra tjänstens namespace genom att göra en global sökning och ersätt http://stockholm.se/soa/template/templateservice/ med http://stockholm.se/soa/[myapplication].myservice/ 15 (22)

10. Säkerställ att nedanstående referenser ser rätt ut i följande projekt Project Reference Stockholm.SOA.[MyApplication].WCF.[ MyService].MessageContracts Stockholm.SOA.[MyApplication].WCF.[MyService].D atacontracts Stockholm.SOA.[MyApplication].WCF.[ MyService].ServiceContracts Stockholm.SOA.[MyApplication].WCF.[ MyService].ServiceImplementation Stockholm.SOA.[MyApplication].WCF.[ MyService].ConsoleHost Stockholm.SOA.[MyApplication].WCF.[ MyService].svc Stockholm.SOA.[MyApplication].WCF.[MyService]. MessageContracts Stockholm.SOA.[MyApplication].WCF.[MyService].F aultcontracts Stockholm.SOA.[MyApplication].WCF.[MyService]. MessageContracts Stockholm.SOA.[MyApplication].WCF.[MyService].F aultcontracts Stockholm.SOA.[MyApplication].WCF.[MyService].S ervicecontracts Stockholm.SOA.[MyApplication].WCF.[MyService]. WCFResources Stockholm.SOA.[MyApplication].WCF.[MyService].s erviceimplementation Stockholm.SOA.[MyApplication].WCF.[MyService].s erviceimplementation 4.3.2 DEPLOYMENT UNDER UTVECKLING 4.3.2.1 ANVÄND EN CONSOLEHOST Under utvecklingsprojektet använder du ett consolehost-projekt för att kunna felsöka koden. I template-projektet finns kod både för att skapa en körbar consolehost samt en IIS-tjänst som kan användas för att bygga ett deploymentpaket. 4.3.2.2 KLIENT Under utvecklingsarbetet kan det vara bra att skapa en testklient som kan hämta och leverera data på korrekt sätt. För att ställa enkla frågor så finns det en wcftestclient.exe installerad tillsammans med Visual Studio, se %program files%\microsoft Visual Studio 2010\Common7\IDE\WCFTestClient.exe. 16 (22)

4.3.3 SÄKERHET Skall sättas upp i enlighet med dokumentation avseende informationsklassning från Stockholm Stad. I övrigt används WCF security guidelines vid granskning av SOA-projekten. 4.3.4 BINDNINGAR Se till att rätt bindingar används mellan klient och service. Använd inte endast default, utan testa den bindning som verkligen kommer att användas vid ett produktionsläge. 17 (22)

5 EXEMPEL PÅ EN SOA-TJÄNST CASTLE TOUR BOOKINGSERVICE Projektet Stockholm.SOA.CastleTour.WCF.Booking är exempel på en SOA-tjänst som är utvecklad på plattformen. Den innehåller exempel på mycket av det som beskrivs i nästa kapitel och kan med fördel användas som hjälpmedel vid utveckling av e-tjänster. Öppna solutionfilen i Visual Studio för att titta på koden och bygga en consolehost för att stega igenom den. 18 (22)

5.1 DEMOPROJEKTET CastleTour har två befintliga Web-tjänster för att hantera dels bokning av turer, dels för bokning av hotellrum. Dessa används ifrån varsin användarimplementation. Dessa tjänster är utvecklade innan framtageandet av denna, och har därför litet olika namnrymder(namespace) och namn. Uppdraget är att utforma en SOA-lösning för att generellt hantera bokningar för CastleTours. Lösningen kräver att det är löst kopplade tjänster som kan utföra ett sammankopplat arbetsflöde. De befintliga verksamhetssystemen är byggda som webtjänster och kan var för sig sköta en bokning. Men hanteringen kräver en manuell kontroll av betalning i en betalningslista som kommer ifrån fakturaavdelningen. När kontrollen är gjord skickas manuellt en bokningsbekräftelse via e-post till den person som har initierat bokningen. För bokning av turer med lunch finns en E-tjänst uppsatt där gäster kan boka in sig till guidade turer på de olika slotten. Bokningen skickas i nuläget med e-post till personal som manuellt lägger till en bokning i verksamhetssystemet. Tjänsten lägger upp ett signerat dokument som innehåller information om gästerna i sällskapet i E-tjänstens mapp FormDataAttachmentTransfer med de metadata som används för filetransfertjänsten. Denna plockar upp filen och lämnar den på en filarea där personalen kan hämta upp den. 5.2 KRAVSPECIFIKATIONEN Efter en förstudie kommer ni gemensamt fram till att de befintliga tjänsterna CastleTours.TourService och CastleTours.HotelMgmt går att använda för bokningar. Dock innehåller bägge varsin lista med gäster och med slott/hotell, men detta är inget som ni kommer att ta hänsyn till i det första genomförandet. E-tjänsteutvecklarna vill kunna få upp en lista på slott med bilder på slotten för att gäster skall kunna välja slott i en lista. Den informationen finns tillgänglig i CastleTours.TourService och kommer att användas därifrån. Eftersom listorna på slott och gäster har olika id för respektive slott kommer ni bara att använda text när ni letar upp slotten/gästen. För att hantera bokningarnas relationer, skapas en ny databas, där relationerna läggs till med pekare mot det bokningsnummer som fås från vardera tjänst. Den tjänsten kommer att ha två metoder. En för att spara bokningsrelationen, och en för att hämta upp relationen. Dessutom skall en ny tjänst utvecklas, som kontrollerar om reservationen är betald i fakturasystemet. Denna funktion läggs in som en BizTalk orkestrering, vilken bevakar en 19 (22)

folder efter en fil som levereras dagligen. För enkelhetens skull använder vi Bokningsnummer => Fakturanummer i demoexemplet. När en fil som innehåller ett aktuellt bokningsnummer kommer in, startar BizTalk en ny orkestrering som skickar ett betalningsmeddelande till respektive bokningtjänst. När betalningen är slutförd kommer användaren att få ett notifierings-mail med bokningsbekräftelsen, dessutom skall bekräftelsen läggas upp på användarens sida i E- tjänsten. 5.3 DESIGN PÅ IMPLEMENTERADE WCF-TJÄNSTER 5.3.1 HOTELMANAGEMENT 20 (22)

5.3.2 TOURSERVICE 21 (22)

5.4 DESIGN AV BOKNINGSHANTERINGEN 22 (22)