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 sikker-digital-post.
- Ø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 sikker-digital-post-klient og trykk Install.
Sende post
Det anbefales å bruke dokumentasjon i klassene for mer detaljert beskrivelse av inputparametere.
PostInfo for digital post
Først, lag en motaker av type DigitalPostMottaker
:
Postkassetjenesteleverandørene har ulik behandling av ikke-sensitiv tittel. Se begrep.difi.no for detaljer om denne forskjellen.
Husk at
OrgnummerPostkasse
er organisasjonsnummer til leverandør av postkassetjenesten. Organisasjonsnummeret leveres fra oppslagstjenesten sammen med postkasseadressen og sertifikatet til innbygger.
PostInfo for fysisk post
Skal du sende fysisk post må du først lage en FysiskPostMottaker
, en FysiskPostReturMottaker
og sette informasjon om farge og makulering:
Her er adressen av type NorskAdresse
eller UtenlandskAdresse
.
Ved sending av fysisk post må man oppgi en returadresse, uavhengig av om brevet er satt til Posthåndtering.MakuleringMedMelding
. Oppretting av en FysiskPostInfo vil da se slik ut:
Oppsett før sending
Opprett en avsender og en databehandler:
Hvis man har flere avdelinger innenfor samme organisasjonsnummer, har disse fått unike avsenderidentifikatorer, og kan settes på følgende måte:
Opprette forsendelse
Deretterer kan du opprette forsendelse. Forsendelsen inneholder de dokumentene som skal til mottakeren:
Opprette klient og sende post
Siste steg er å opprette en SikkerDigitalPostKlient
:
Transportkvitteringen får du tilbake umiddelbart; den trenger du ikke å polle for å få.
Hente kvitteringer
For å hente kvitteringer må du sende en kvitteringsforespørsel:
Husk at det ikke er mulig å hente nye kvitteringer før du har bekreftet mottak av nåværende.
Kvitteringer du mottar når du gjør en kvitteringsforespørsel kan være av følgende typer: Leveringskvittering
,Åpningskvittering
, Returpostkvittering
, Mottakskvittering
eller Feilmelding
. Kvittering kan også være av typenTransportFeiletKvittering
. Dette kan skje når selve kvitteringsforespørselen er feilformatert.
Husk at hvis du får
TomKøKvittering
så er køen tom. Du henter bare kvitteringer fra kø gitt avMpcId
ogPrioritet
. Hvis ikke dette blir satt spesifikt vil det hentes fra kø hvorMpcId = ""
ogPrioritet = Prioritet.Normal
.
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
bare skjer om sending av brev feilet. Disse loggerne vil være under Difi.SikkerDigitalPost.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
Når det sendes brev gjennom Sikker Digital Post, så legges det også ved en del ekstra informasjon. Denne informasjonen er strukturert som XML og er nødvending for at brevet skal leveres til mottaker. Ofte kan dette være svært nyttig informasjon å logge.
For å aktivere logging av forespørsel og respons så setter du følgende på Klientkonfigurasjon
:
Da vil det logges til en logger med navn Difi.SikkerDigitalPost.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ø.
Prosessere dokumentpakke som sendes
Når man logger forespørsel og respons, så logges bare XML som sendes, ikke selve dokumentpakken. Det er to måter å logge denne på:
- Aktiver logging til disk vha
Klientkonfigurasjon.AktiverLagringAvDokumentpakkeTilDisk
. - Implementer
IDokumentPakkeProsessor
og legg til iKlientkonfigurasjon.Dokumentpakkeprosessorer
Installere sertifikater
Som bruker av dette biblioteket er du en Databehandler som har ansvar for sending av meldinger. For å gjøre dette trenger du et sertifikat for å kunne autentisere deg mot Meldingsformidleren. Du kan lese mer om aktørene hos begrep.difi.no. 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.
Legg inn databehandlersertifikat i certificate store
Databehandlersertifikat er det sertifikatet du har fått utstedt for å kunne sende post.
- 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
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
SikkerDigitalPostKlient
har støtte for å ta inn thumbprint direkte for Databehandler
og PostMottaker
. Ønsker du å sende inn sertifikater du har allerede har initialisert, kan du kalle konstruktøren som tar inn X509Certificate2
.
Ytelse
Klientbiblioteket benytter en HttpWebRequest
for å kommunisere med Meldingsformidleren. I en konsollapplikasjon er denne begrenset til maks to samtidige forbindelser om gangen, mens den i en asp.net applikasjon er begrenset til ti. Dersom du ønsker å sende flere brev samtidig kan denne verdien endres f.eks til 3. Mer enn dette anbefales ikke.
Se ServicePointManager.DefaultConnectionLimit for mer informasjon.