Eksempel på kall
Det er bare tre kall du kan gjøre mot oppslagstjenesten;
- hente endringer
- hente personer
- hente printsertifikat.
Først må du sette opp OppslagstjenesteKonfigurasjon
med virksomhetssertifikat og Miljø
som skal brukes.
Sett opp klientkonfigurasjon
Med sertifikat fra thumbprint:
const string avsendersertifikatThumbprint = "fe14593dd66b2...";
var konfigurasjon = new OppslagstjenesteKonfigurasjon(
Miljø.FunksjoneltTestmiljøVerifikasjon1,
avsendersertifikatThumbprint
);
Vi anbefaler å laste sertifikatet fra thumbprint fordi passordet ikke er i koden. Sertifikat kan installeres i
Personal
forCurrentUser
ellerLocalMachine
. Se hvordan du installerer sertifikatet her.
Med sertifikat fra fil:
const string avsendersertifikatSti = @"C:\Sti\Til\Sertifikat\Sertifikat.pfx";
var sertifikat = new X509Certificate2(
File.ReadAllBytes(avsendersertifikatSti),
"Passord",
X509KeyStorageFlags.Exportable
);
var konfigurasjon = new OppslagstjenesteKonfigurasjon(
Miljø.FunksjoneltTestmiljøVerifikasjon1,
sertifikat
);
Hent endringer
string avsendersertifikatThumbprint = null; //Som initiert tidligere
OppslagstjenesteKonfigurasjon konfigurasjon = null; //Som initiert tidligere
var oppslagstjenesteKlient = new OppslagstjenesteKlient(konfigurasjon);
var personidentifikator = new[] { "08077000292" };
var personer = oppslagstjenesteKlient.HentPersoner(personidentifikator,
Informasjonsbehov.Kontaktinfo,
Informasjonsbehov.Sertifikat,
Informasjonsbehov.SikkerDigitalPost,
Informasjonsbehov.VarslingsStatus
);
Hent personer
string avsendersertifikatThumbprint = null; //Som initiert tidligere
OppslagstjenesteKonfigurasjon konfigurasjon = null; //Som initiert tidligere
var oppslagstjenesteKlient = new OppslagstjenesteKlient(konfigurasjon);
var personidentifikator = new[] { "08077000292" };
var personer = oppslagstjenesteKlient.HentPersoner(personidentifikator,
Informasjonsbehov.Kontaktinfo,
Informasjonsbehov.Sertifikat,
Informasjonsbehov.SikkerDigitalPost,
Informasjonsbehov.VarslingsStatus
);
Hent printsertifikat
string avsendersertifikatThumbprint = null; //Som initiert tidligere
OppslagstjenesteKonfigurasjon konfigurasjon = null; //Som initiert tidligere
var oppslagstjenesteKlient = new OppslagstjenesteKlient(konfigurasjon);
var printSertifikat = oppslagstjenesteKlient.HentPrintSertifikat();
Hvordan komme i gang
Klienten er tilgjengelig som en NuGet-pakke. Denne vil oppdateres jevnlig etter hvert som ny funksjonalitet legges til.
For å installere NuGet-pakken, gjør følgende:
- Velg TOOLS -> NuGet Package Manager -> Manage Nuget Packages for Solution…
- Søk etter oppslagstjeneste.
- Ønsker du pre-release, må du sørge for at det står Include Prerelease i drop-down menyen rett over søkeresuløtatene (der det står Stable Only).
- Velg oppslagstjeneste og trykk Install.
Konfigurasjon
OppslagstjenesteKonfigurasjon initieres med hvilket miljø man ønsker å kjøre mot, FunksjoneltTestmiljø eller Produksjonsmiljø, samt tilhørende sertifikat til gitt miljø.
Proxy
For å bruke proxy setter man ProxyHost
,ProxyPort
og ProxyScheme
i konfigurasjonen:
På vegne av
For å gjøre oppslag på vegne av en annen virksomhet settes organisasjonsnummeret til gitt bedrift i OppslagstjenesteKonfigurasjon.SendPåVegneAv
:
Installere sertifikater
For å kunne bruke dette biblioteket så trenger du et sertifikat for å kunne autentisere deg mot Oppslagstjenesten. Dette bør installeres på maskinen som skal bruke klientbiblioteket. Grunnen til at vi ønsker å installere det er for å ikke ha passord i klartekst i koden.
Alle sertifikater har en unik identifikator som kalles thumbprint. Hvis du ikke ønsker å håndtere selv i koden hvordan sertifikatene skal lastes, så kan du følge guiden under, steg for steg. Til slutt gjennomgås det hvordan du kan finne thumbprint til det installerte sertifikatet.
Installere virksomhetssertifikat
Virksomhetssertifikatet brukes av virksomheten for å signere forespørsler som går til Oppslagstjenesten.
- Dobbeltklikk på sertifikatet (Sertifikatnavn.p12)
- Velg at sertifikatet skal lagres i Current User eller Local Machine og trykk Next
- Filnavn skal nå være utfylt. Trykk Next
- Skriv inn passord for privatnøkkel og velg Mark this key as exportable …, trykk Next
- Velg Automatically select the certificate store based on the type of certificate
- Klikk Next og Finish
- Får du spørsmål om å godta sertifikatkjeden så du gjør det.
- Du skal da få en dialog som sier at importeringen var vellykket. Trykk OK.
Finne thumbprint til installert sertifikat
OppslagstjenesteKlient
tar inn OppslagstjenesteKonfigurasjon
, som igjen tar inn thumbprint
direkte:
Det er enklest å finne thumbprint gjennom Microsoft Management Console (mmc.exe).
- Velg File -> Add/Remove Snap-in…
- Merk Certificates og trykk Add >
- Hvis sertifikatet ble installert i Current User velges My user account, hvis det er installert på Local Machine velges Computer Account. Klikk Finish og OK
- Ekspander Certificates-noden, velg Personal og åpne Certificates
- Dobbeltklikk på sertifikatet du installerte
- Velg Details, scroll ned til Thumbprint og kopier
Ønsker du å sende inn sertifikater du har allerede har initialisert, kan du bruke konstruktøren OppslagstjenesteKonfigurasjon(Miljø, X509Certificate2)
.
Async/Sync
Alle operasjonene/metodene i Oppslagstjenesten har både synkrone og asynkrone metoder. Velg det som passer din applikasjon. Klienten initialiserer på samme måte og det er kun gitt metode som styrer hvorvidt den er asynkron eller ikke.
Asynkrone metoder
Metodene som er asynkrone returnerer en Task<>
av objektet den synkrone metoden returnerer. Man kan bruke await
på svaret direkte eller vente på at Task
-en skal bli ferdig på annet vis.
Synkrone metoder
Logging
Generelt
Klienten bruker Common.Logging API for å abstrahere logging. Det er opp til brukeren å imlementere API med et passende loggrammeverk, men vi viser hvordan dette kan gjøres med Log4Net.
Loggnivå DEBUG
vil logge resultat for forespørsler som går bra og de som feiler, WARN
bare for feilede forespørsler eller verre, mens ERROR
vil aldri forekomme. Disse loggerne vil være under Difi.Oppslagstjeneste.Klient
Implementere Log4Net som logger
- Installer Nuget-pakke
Common.Logging.Log4Net
. Denne vil da også installere avhengigheteneCommon.Logging.Core
ogCommon.Logging
. Merk at versjoneringen her er litt underlig, men et søk i Nuget Gallery vil f.eks. vise at Log4Net 2.0.3 har pakkenavn Log4net [1.2.13] 2.0.3. Da er detCommon.Logging.Log4Net1213
som skal installeres. - Legg merke til hvilken versjon av Log4net som faktisk installeres. Av en eller annen grunn kan det bli 2.0.0 som installeres. Da må versjonen oppdateres til 2.0.3.
En fullstendig App.config med Log4Net-adapter og en RollingFileAppender
:
Logge forespørsel og respons
Det er mulig å logge hele forespørsel/respons som blir sendt/mottatt. For å aktivere dette setter du følgende på OppslagstjenesteKonfigurasjon
:
Det vil da logges til en logger med navn Difi.Oppslagstjeneste.Klient.RequestResponse
.
Merk at logging av forespørsel og respons kan gi mye dårligere ytelse. Det er ingen grunn til å logge dette i et produksjonsmiljø.
Eksempel på App.config med Log4Net-adapter. I dette eksempelet er det en logger for vanlig debug-logg samt en logger for forespørsel og response: