Utveckling av tjänster

(1)

Utveckling av tjänster

Stockholms stad SOA-plattform

(2)

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 SOA SDK 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

(3)

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.

(4)

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 SOA- plattform.

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¹.

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².

I detta dokument avänds Stockholm.SOA.MyService som exempel på flera ställen.

(5)

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.

(6)

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.

(7)

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 SOA- tjä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.

(8)

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.

(9)

4.1 UTVECKLINGSMILJÖ

Se dokumentet SOA SDK 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

STOCKHOLM.SOA.[MYSERVICE].WCF.SERVICECONTRACTS 4.2.2.1

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)

(10)

ServiceImplementationen måste ange

ServiceBehavior(Namespace=”http://stockholm.se/SOA/[Applikation]/WCF/[Tjänst]/[Ve rsion”,Name=”TemplatedService”)]

STOCKHOLM.SOA.[MYSERVICE].WCF.DATACONTRACTS 4.2.2.3

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;}

}

STOCKHOLM.SOA.[MYSERVICE].WCF.MESSAGECONTRACTS 4.2.2.4

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.

(11)

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;}

}

STOCKHOLM.SOA.[MYSERVICE].WCF.SERVICEIMPLEMENTATION 4.2.2.6

Er implementationen skall läggas in i detta projekt.

(12)

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.

(13)

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

(14)

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.

(15)

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/

(16)

Project Reference

Stockholm.SOA.[MyApplication].WCF.[

MyService].MessageContracts

Stockholm.SOA.[MyApplication].WCF.[MyService].D ataContracts

MyService].ServiceContracts

Stockholm.SOA.[MyApplication].WCF.[MyService].

MessageContracts

Stockholm.SOA.[MyApplication].WCF.[MyService].F aultContracts

MyService].ServiceImplementation

MessageContracts

Stockholm.SOA.[MyApplication].WCF.[MyService].F aultContracts

Stockholm.SOA.[MyApplication].WCF.[MyService].S erviceContracts

WCFResources Stockholm.SOA.[MyApplication].WCF.[

MyService].ConsoleHost

Stockholm.SOA.[MyApplication].WCF.[MyService].s erviceImplementation

MyService].svc

Stockholm.SOA.[MyApplication].WCF.[MyService].s erviceImplementation

4.3.2 DEPLOYMENT UNDER UTVECKLING ANVÄND EN CONSOLEHOST

4.3.2.1

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.

KLIENT 4.3.2.2

Under utvecklingsarbetet kan det vara bra att skapa en testklient som kan hämta och

(17)

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.

(18)

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.

(19)

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 SOA SDK, 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 web- tjä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

(20)

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.

Utveckling av tjänster