Konsument till Nova Softwares sdk klientbibliotek

NOVA SOFTWARE • KONSUMENT TILL NOVA SOFTWARES SDK

Konsument till Nova Softwares SDK klientbibliotek

Grundläggande dokument som beskriver en klients användande av Nova SDK klientbibliotek.

Konsument till Nova Softwares SDK klientbibliotek

Introduktion

Detta dokument syftar till att ge en beskrivning till hur man via Nova Softwares klientbibliotek kan agera konsument till tjänster som exponeras via Nova Softwares API. Detta dokument är tänkt att användas som ett komplement till bifogad exempelkod (se Exempelkod.zip) för en konsument.

Komponent som krävs för att skapa en konsument

Klientbiblioteket består av ett kompilerat klassbibliotek (.NET 4.5) med filnamnet NovaSoftware.CsbClientLibrary.Consumers.dll. I och med att klassbiblioteket är skrivet för .NET 4.5 är .NET ett krav för att kunna anropa en CSB-tjänst.

Övriga kunskaper som krävs

Förutom informationen som står i detta dokument och den kod som tillhandahålls så är det viss specifik kunskap som behöver tillhandahållas av Nova Software för att kunna producera en körbar konsumerande klient. Dessa saker är:

1. 
   URL till vår tjänstepunkt – Observera att den URL som finns med i exempelkoden stämmer nödvändigtvis inte med den URL som den aktuella klienten ska ansluta emot, den URL som gäller levereras separat.
   
2. 
   Säkerhetsinformation – Beroende på vilken tjänst som den konsumerande klienten skall ansluta emot så krävs det att en specifik mängd säkerhetsartefakter bifogas (se avsnitt Säkerhetsinformation nedan). Den säkerhetsinformation som finns i exempelkoden fungerar endast som exempel för att demonstrera hur man använder de assisterande metoderna i klientbiblioteket.
   
3. 
   Klientid och id på tjänsten som ska konsumeras – Dessa id:n är att betrakta som en delad hemlighet mellan Novasoftware och klientproducerande part och fungerar som en del av mekanismen för att autentisera anropande klient.
   

Skapa en konsument

För att kunna skicka en tjänstebegäran via Nova Softwares klientbibliotek krävs det att en instans av klassen CsbConsumerClient skapas. Denna klass tar ett argument till sin konstruktor i form av en instans av klassen CsbClientConfiguration.
Instansen av CsbClientConfiguration pekar ut namnet på den endpoint-konfiguration som finns angiven i klientens app.config-fil (se kodexempel). Denna innehåller WCF konfiguration som styr klientens kommunikation med Nova Softwares tjänstepunkt. Se [1] för mer information om WCF konfiguration.
När CsbConsumerClient-instansen är skapad kan dess generiska metod InvokeService användas för att skicka en tjänsteförfrågan. Denna metod tar en objektrepresenation av den begärda tjänstens tjänstekontrakt som argument tillsammans med tjänstens id, klientens id samt den säkerhetsinformation som krävs av tjänsten. Metoden returnerar ett tjänstesvar på den begärda tjänsteförfrågan och har ett synkront beteende.
Det är också möjligt att anropa InvokeService med en XML representation av tjänstens kontrakt istället för en objektrepresentation. Metoden tar då XML-dokumentet i form av en sträng tillsammans med tjänstens id, klientens id och tillhörande säkerhetsinformation.

Säkerhetsinformation

Tjänsterna har möjligheten att via en policy avkräva anropande klienter att uppfylla vissa säkerhetskriterier för att få anropa tjänsten. Dessa säkerhetskriterier är via klientbiblioteket utryckta genom ett SecurityInfo-objekt.
Själva policyn identifieras med hjälp av en URI, policyn består i sin tur av ett antal regler. Dessa regler utrycker vilka typer av säkerhetsartefakter som måste finnas angivna av den anropande klienten. Den anropande klienten måste känna till id för policy, id för regler samt vilka typer av regler det rör sig om. Detta är alltså information som den anropande aktören behöver känna till innan det är möjligt att sammanställa ett giltigt serviceanrop och inget som klientbiblioteket har möjlighet att hjälpa till med.
Rent konkret så skapas ett SecurityInfo-objekt genom att policys URI anges i konstruktorn. Därefter används metoden AddPolicyRuleAndPerformer för att realisera uppfyllandet av en regel. Därefter kan instansen av SecurityInfo-objektet användas som argument till InvokeService-metoden.

Kontrakt och datamodell

Tjänsterna som exponeras har sina tjänstekontrakt definierade som XML-scheman. Som konsument av en tjänst behövs kännedom om tjänstekontraktet. Anrop som inte följer tjänsteschemat betraktas som ett ogiltigt anrop och kommer aldrig nå tjänsten.
För att på klientsidan kunna arbeta med den objektrepresentation av tjänstekontraktet som krävs för att använda sig av den generiska InvokeService-metoden behöver den konsumerande klienten kunna generera en objektrepresentation av denna. Det är denna objektrepresentation som används som argument till InvokeService. Det finns ett antal verktyg som kan hjälpa till med detta, t.ex. XSD.exe [2].

Om exempelkoden

Exempelkoden som är bifogad i dokumentationen syftar till att visa på hur en grundläggande struktur kan se ut för att genomföra ett tjänsteanrop via Nova Softwares SDK. Observera dock att exempelkoden inte är exekverbar ur det perspektivet att det genomför ett lyckat tjänsteanrop utan ett antal ändringar. De saker som behöver ändras är följande:

• 
  Korrekt tjänste-id (SERIVCE_ID) och korrekt klient-id (CONSUMER_ID) måste skrivas in, dessa värden finns att hämta i den tjänstespecifika dokumentationen.
  

• 
  Korrekt URL till Nova Softwares tjänstepunkt måste anges, denna ska skrivas in i app.config-filen på angivet ställe. Även detta värde finns i den tjänstespecifika dokumentationen.
  
• 
  
  
• 
  Ett anrop måste skapas enligt tjänstens kontrakt. I exempelkoden finns under katalogen Schemas ett antal exempelscheman enligt den strukturens om majoriteten av Nova Softwares tjänster har. Det finns också exempel på hur man kan använda xsd.exe för att generera en klassrepresentation av dessa xml-scheman (finns som pre-build event på projektet). Efter att klassrepresentationen är gjord så ska metoden CreateServiceInput() anpassas så att den genererar ett objekt av korrekt indatatyp för den tjänsten som ska konsumeras.
  

Referenser

[1] – http://msdn.microsoft.com/en-us/library/ms731745(v=vs.110).aspx
[2] - https://docs.microsoft.com/en-us/dotnet/standard/serialization/xml-schema-definition-tool-xsd-exe

0515–777 888 | [e-mail] | oktober 2014 | /