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ø.
var testmiljøKonfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.FunksjoneltTestmiljø, avsendersertifikatThumbprint);
var produksjonsmiljøKonfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.Produksjonsmiljø, avsendersertifikatThumbprint);Proxy
For å bruke proxy setter man ProxyHost,ProxyPort og ProxyScheme i konfigurasjonen:
var konfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.FunksjoneltTestmiljø, avsendersertifikatThumbprint);
{
ProxyHost = "proxyhost",
ProxyPort = 3333,
ProxyScheme = "https"
};På vegne av
For å gjøre oppslag på vegne av en annen virksomhet settes organisasjonsnummeret til gitt bedrift i OppslagstjenesteKonfigurasjon.SendPåVegneAv:
var testmiljøKonfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.FunksjoneltTestmiljø, avsendersertifikatThumbprint);
testmiljøKonfigurasjon.SendPåVegneAv = "984661185";Eksempel på kall
Det er bare tre kall du kan gjøre mot oppslagstjenesten; hente endringer, hente personer og hente printsertifikat. Her er et minimumseksempel på hva du må ha når du har fått hentet sertifikatene som er installert.
var konfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.FunksjoneltTestmiljøVerifikasjon1, avsendersertifikatThumbprint);
var register = new OppslagstjenesteKlient(konfigurasjon);
const int fraEndringsNummer = 600;
var endringer = register.HentEndringer(fraEndringsNummer,
Informasjonsbehov.Person ,
Informasjonsbehov.Kontaktinfo ,
Informasjonsbehov.Sertifikat ,
Informasjonsbehov.SikkerDigitalPost ,
Informasjonsbehov.VarslingsStatus
);
var personidentifikator = new[] {"08077000292"};
var personer = register.HentPersoner(personidentifikator,
Informasjonsbehov.Kontaktinfo ,
Informasjonsbehov.Sertifikat ,
Informasjonsbehov.SikkerDigitalPost ,
Informasjonsbehov.VarslingsStatus
);
var printSertifikat = register.HentPrintSertifikat();Installere sertifikater
For å sende forespørsler til Oppslagstjenesten trenger du å installere sertifikater på maskinen. Grunnen til at de skal installeres er i hovedsak sikkerhet. Når du installerer ditt private avsendersertifikat på datamaskinen så blir du spurt om passord. Dette skjer kun én gang, og etter dette kan du bruke sertifikatet i koden uten å eksponere passordet.
Installere avsendersertifikat/virksomhetssertifikat
Avsendersertifikatet brukes av Virksomhet for å signere forespørsler som går til Oppslagstjenesten.
- Dobbeltklikk på sertifikatet (Sertifikatnavn.p12)
- Velg at sertifikatet skal lagres i Current User og trykk Next
- Filnavn skal nå være utfylt. Trykk Next
- Skriv inn passord for privatekey og velg Mark this key as exportable …, trykk Next
- Velg Automatically select the certificate store based on the type of certificate
- Next og Finish
- Får du spørsmål om å godta sertifikatet så gjør det.
- Du skal da få en dialog som sier at importeringen var vellykket. Trykk Ok.
Finne installert sertifikat
OppslagstjenesteKlient tar inn OppslagstjenesteKonfigurasjon, som igjen tar inn thumbprint direkte:
var konfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.FunksjoneltTestmiljø, avsendersertifikatThumbprint);
var klient = OppslagstjenesteKlient(konfigurasjon);For å finne thumbprint så er det lettest å gjøre det vha Microsoft Management Console (mmc.exe).
- Start mmc.exe (Trykk windowstast og skriv mmc.exe)
- Velg File -> Add/Remove Snap-in…
- Merk Certificates og trykk Add >
- Velg My user account og trykk Finish
- Åpne mappe for sertifikat og finn avsendersertifikat: Åpne noden Certificates - Current User - Personal - 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 kalle konstruktøren som tar inn 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 await`e svaret direkte eller ventet på at Task-en skal bli ferdig på annet vis.
var konfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.FunksjoneltTestmiljøVerifikasjon1, avsendersertifikatThumbprint);
var register = new OppslagstjenesteKlient(konfigurasjon);
var endringer = await register.HentEndringerAsynkront(fraEndringsNummer,
Informasjonsbehov.Person ,
Informasjonsbehov.Kontaktinfo ,
Informasjonsbehov.Sertifikat ,
Informasjonsbehov.SikkerDigitalPost ,
Informasjonsbehov.VarslingsStatus
);
//Returnerer Task<>
var personidentifikator = new[] {"08077000292"};
Task<IEnumerable<Person>> personer = register.HentPersonerAsynkront(personidentifikator,
Informasjonsbehov.Kontaktinfo ,
Informasjonsbehov.Sertifikat ,
Informasjonsbehov.SikkerDigitalPost ,
Informasjonsbehov.VarslingsStatus
);
//Vent på at tasken blir ferdig..
var printSertifikat = await register.HentPrintSertifikatAsynkront();Synkrone metoder
var konfigurasjon = new OppslagstjenesteKonfigurasjon(Miljø.FunksjoneltTestmiljøVerifikasjon1, avsendersertifikatThumbprint);
var register = new OppslagstjenesteKlient(konfigurasjon);
var endringer = register.HentEndringer(fraEndringsNummer,
Informasjonsbehov.Person ,
Informasjonsbehov.Kontaktinfo ,
Informasjonsbehov.Sertifikat ,
Informasjonsbehov.SikkerDigitalPost ,
Informasjonsbehov.VarslingsStatus
);
var personidentifikator = new[] {"08077000292"};
var personer = register.HentPersoner(personidentifikator,
Informasjonsbehov.Kontaktinfo ,
Informasjonsbehov.Sertifikat ,
Informasjonsbehov.SikkerDigitalPost ,
Informasjonsbehov.VarslingsStatus
);
var printSertifikat = register.HentPrintSertifikat();Logging
Generelt om logging
Loggrammeverket som blir brukt er Log4Net 2.0.4. Pass på å bruke 2.0.4 eller høyere for at logging skal fungere.
Hvis man setter loggnivået til DEBUG vil alle forespørsler og responser bli logget. WARN vil kun logge feilmeldinger. Alle loggerne ligger i navnerommet Difi.Oppslagstjeneste.Klient.
<log4net>
<logger name="Difi.Oppslagstjeneste.Klient">
<appender-ref ref="TraceAppender"/>
<appender-ref ref="RollingFileAppender"/>
<level value="WARN"/>
</logger>
<appender name="TraceAppender" type="log4net.Appender.TraceAppender">
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date [%thread] %-5p %c %message%newline" />
</layout>
</appender>
<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
<lockingModel type="log4net.Appender.FileAppender+MinimalLock" />
<file value="${AppData}\Difi\Log\" />
<appendToFile value="true" />
<rollingStyle value="Date" />
<staticLogFileName value="false" />
<rollingStyle value="Composite" />
<param name="maxSizeRollBackups" value="10" />
<datePattern value="yyyy.MM.dd' Difi.Oppslagstjeneste-klient-dotnet.log'" />
<maximumFileSize value="100MB" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date [%thread] %-5level %logger [%property{NDC}] - %message%newline" />
</layout>
</appender>
</log4net>Eksempel på logging av forespørsel og respons
Det kan være kjekt å logge selve SOAP forespørselen/responsen som blir sendt/mottatt når man gjør den initielle integrasjonen. Dette kan man gjøre ved å lage en logger mot navnerommet Difi.Oppslagstjeneste.Klient.RequestLog. Se følgende eksempel:
<log4net>
<logger name="Difi.Oppslagstjeneste.Klient.RequestLog">
<appender-ref ref="TraceAppender"/>
<appender-ref ref="RollingFileAppender"/>
<level value="DEBUG"/>
</logger>
<appender name="TraceAppender" type="log4net.Appender.TraceAppender">
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date [%thread] %-5p %c %message%newline" />
</layout>
</appender>
<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
<lockingModel type="log4net.Appender.FileAppender+MinimalLock" />
<file value="${AppData}\Difi\Log\" />
<appendToFile value="true" />
<rollingStyle value="Date" />
<staticLogFileName value="false" />
<rollingStyle value="Composite" />
<param name="maxSizeRollBackups" value="10" />
<datePattern value="yyyy.MM.dd' Difi.Oppslagstjeneste-klient-dotnet.log'" />
<maximumFileSize value="100MB" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date [%thread] %-5level %logger [%property{NDC}] - %message%newline" />
</layout>
</appender>
</log4net>Advarsel: Forespørsel- og response logging burde ikke være aktivert i et produksjonsmiljø siden dette kan ha innvirkninger på ytelsen av applikasjonen.