Klienten er tilgjengelig som en NuGet-pakke.

For å installere NuGet-pakken, gjør følgende i Visual Studio/Rider:

1. Velg TOOLS -> NuGet Package Manager -> Manage Nuget Packages for Solution…
2. Søk etter Difi.SikkerDigitalPost.ProxyKlient.
3. Velg Difi.SikkerDigitalPost.ProxyKlient.X og trykk Install.

Biblioteket er avhengig av at integrasjonspunktet kjører.

Det anbefales å bruke dokumentasjon i klassene for mer detaljert beskrivelse av inputparametere.

Opprette digital post

Først, lag en motaker av type DigitalPostMottaker:

var personnummer = "01013300002";
var mottaker = new DigitalPostMottaker(
        personnummer 
);

var ikkeSensitivTittel = "En tittel som ikke er sensitiv";
var sikkerhetsnivå = Sikkerhetsnivå.Nivå3;
var postInfo = new DigitalPostInfo(mottaker, ikkeSensitivTittel, sikkerhetsnivå);

Postkassetjenesteleverandørene har ulik behandling av ikke-sensitiv tittel. Se https://difi.github.io/felleslosninger/ikkesensitivtittel.html for detaljer om denne forskjellen.

Opprett fysisk post

var navn = "Ola Nordmann";
var adresse = new NorskAdresse("0001", "Oslo");
var mottaker = new FysiskPostMottaker(navn, adresse);

var returMottaker = new FysiskPostReturmottaker(
    "John Doe", 
    new NorskAdresse("0566", "Oslo")
    {
        Adresselinje1 = "Returgata 22"
    });

var fysiskPostMottakerPersonnummer = "27127000293"
var postInfo = new FysiskPostInfo(
            fysiskPostMottakerPersonnummer,
            mottaker, 
            Posttype.A, 
            Utskriftsfarge.SortHvitt, 
            Posthåndtering.MakuleringMedMelding, 
            returMottaker
);

Adressen kan også være av typen UtenlandskAdresse.

Ved sending av fysisk post må man oppgi en returadresse, uavhengig av om brevet er satt til Posthåndtering.MakuleringMedMelding.

Oppsett før sending

Opprett en avsender og en databehandler:

var orgnummerAvsender = new Organisasjonsnummer("123456789");
var avsender = new Avsender(orgnummerAvsender);

var orgnummerDatabehandler = new Organisasjonsnummer("987654321");
var databehandler = new Databehandler(orgnummerDatabehandler);

Avsenderidentifikator benyttes for å identifisere en ansvarlig enhet innenfor en virksomhet. Identifikatoren tildeles ved tilkobling til tjenesten.

avsender.Avsenderidentifikator = "Avsenderidentifikator.I.Organisasjon";

Opprette forsendelse

var hoveddokument = new Dokument(
        tittel: "Dokumenttittel", 
        dokumentsti: "/Dokumenter/Hoveddokument.pdf", 
        mimeType: "application/pdf", 
        språkkode: "NO", 
        filnavn: "filnavn"
    );

var dokumentpakke = new Dokumentpakke(hoveddokument);

var vedleggssti = "/Dokumenter/Vedlegg.pdf";
var vedlegg = new Dokument(
    tittel: "tittel", 
    dokumentsti: vedleggssti, 
    mimeType: "application/pdf", 
    språkkode: "NO", 
    filnavn: "filnavn");

dokumentpakke.LeggTilVedlegg(vedlegg);

Avsender avsender = null; //Som initiert tidligere
PostInfo postInfo = null; //Som initiert tidligere
var forsendelse = new Forsendelse(avsender, postInfo, dokumentpakke);

Opprette forsendelse med utvidelse

Difi har egne dokumenttyper, eller utvidelser, som kan sendes som metadata til hoveddokumenter. Disse utvidelsene er strukturerte xml-dokumenter med egne mime-typer.
Disse utvidelsene benyttes av postkasseleverandørene til å gi en øket brukeropplevelse for innbyggere.
Les mer om utvidelser på: https://difi.github.io/felleslosninger/sdp_utvidelser_index.html

var raw = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
                      "<lenke xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns=\"http://begrep.difi.no/sdp/utvidelser/lenke\">" +
                      "<url>https://difi.github.io/felleslosninger/sdp_lenke.html</url>" +
                      "<beskrivelse lang=\"nb\">Les mer om lenkeutvidelse</beskrivelse>" +
                      "</lenke>";

MetadataDocument metadataDocument = new MetadataDocument("lenke.xml", "application/vnd.difi.dpi.lenke", raw);

Dokumentpakke dokumentpakke = null; //Som initiert tidligere
Avsender avsender = null; //Som initiert tidligere
PostInfo postInfo = null; //Som initiert tidligere
var forsendelse = new Forsendelse(avsender, postInfo, dokumentpakke) { MetadataDocument = metadataDocument };

Opprette klient og sende post

var integrasjonspunktLocalhost = new Miljø(new Uri("http://localhost:9093"));
var klientKonfig = new Klientkonfigurasjon(integrasjonspunktLocalhost);

Databehandler databehandler = null; //Som initiert tidligere
Forsendelse forsendelse = null;     //Som initiert tidligere

var sdpKlient = new SikkerDigitalPostKlient(databehandler, klientKonfig);
var transportkvittering = sdpKlient.Send(forsendelse);

if (transportkvittering is TransportOkKvittering)
{
    //Når sending til integrasjonspunktet gikk bra.		
}
else if(transportkvittering is TransportFeiletKvittering)
{
    var beskrivelse = ((TransportFeiletKvittering)transportkvittering).Beskrivelse;
}

Hente kvitteringer

For å hente kvitteringer fra integrasjonspunktet må du sende en kvitteringsforespørsel:

SikkerDigitalPostKlient sdpKlient = null; //Som initiert tidligere

var kvitteringsForespørsel = new Kvitteringsforespørsel();
Kvittering kvittering = sdpKlient.HentKvittering(kvitteringsForespørsel);

if (kvittering is TomKøKvittering)
{
    Console.WriteLine("  - Kø er tom. Stopper å hente kvitteringer.");
}

if (kvittering is TransportFeiletKvittering)
{
    var feil = ((TransportFeiletKvittering) kvittering).Beskrivelse;
    Console.WriteLine("En feil skjedde under sending til integrasjonspunktet.");
}

if (kvittering is Leveringskvittering)
{
    Console.WriteLine("  - En leveringskvittering ble hentet!");
}

if (kvittering is Åpningskvittering)
{
    Console.WriteLine("  - Noen har åpnet et brev. ");
}

if (kvittering is Returpostkvittering)
{
    Console.WriteLine("  - Du har fått en returpostkvittering for fysisk post.");
}

if (kvittering is Mottakskvittering)
{
    Console.WriteLine("  - Kvittering på sending av fysisk post mottatt.");
}

if (kvittering is Feilmelding)
{
    var feil = (Feilmelding)kvittering;
    Console.WriteLine("  - En feilmelding ble hentet :" + feil.Detaljer, true);
}

Husk at det ikke er mulig å hente nye kvitteringer før du har bekreftet mottak av nåværende.

sdpKlient.Bekreft((Forretningskvittering)kvittering);

Det er ikke mulig å hente nye kvitteringer før du har bekreftet mottak av liggende kvittering på køen. For mer informasjon om de ulike kvitteringene henviser vi til Digitaliseringsdirektoratet: https://difi.github.io/felleslosninger/sdp_index.html

Formålet med dette biblioteket er å tilby en drop-in erstatning for sikker-digital-post-klient-biblioteket, slik at man enkelt kan ta i bruk Integrasjonspunktet fremfor direkte sending til meldingsformidleren. API-et til sikker-digital-post-klient er bevart etter beste evne. Under er det listet opp konsepter som skiller seg fra sikker-digital-post-klient.

• Konfigurasjon av miljø
• Endring i opprettelse av printforsendelse
• Metoder og klasser som er obsolete eller fjernet
• mpcID
• Prioritet
• Nøkler og sertifikat

Pakken Difi.SikkerDigitalPost.Klient.Resources er ikke videreført og kan fjernes som avhengighet.

Konfigurasjon av miljø

Konfigurasjon av miljø gjøres nå ved å spesifisere URL-en til integrasjonspunktet som man ønsker å benytte.

Klientkonfigurasjon tilbyr nå tre metoder for å sette miljø. Vær OBS på å endre parameter hvis string- eller URI-builder-metoden ble benyttet i tidligere klientbibliotek da man i tilfellet ikke vil få noen typefeil/synlige feil i koden.

//builder(Miljo miljo)}
Miljo INTEGRASJONSPUNKT_LOCALHOST = new Miljo(URI.create("http://localhost:9093"));
KlientKonfigurasjon klientKonfigurasjon = KlientKonfigurasjon.builder(miljo).build();


//builder(URI integrasjonspunktRoot)
URI INTEGRASJONSPUNKT_URI = URI.create("http://localhost:9093");
KlientKonfigurasjon klientKonfigurasjon = KlientKonfigurasjon.builder(INTEGRASJONSPUNKT_URI).build();

//@Deprecated
//builder(String integrasjonspunktRootUri)
String INTEGRASJONSPUNKT_URI = "http://localhost:9093";
KlientKonfigurasjon klientKonfigurasjon = KlientKonfigurasjon.builder(INTEGRASJONSPUNKT_URI).build();

Endring i opprettelse av printforsendelse

Personidentifikator til mottaker må nå oppgis.

// Tidligere
var postInfo = new FysiskPostInfo(
            mottaker, 
            Posttype.A, 
            Utskriftsfarge.SortHvitt, 
            Posthåndtering.MakuleringMedMelding, 
            returMottaker
);

// Nå   
var fysiskPostMottakerPersonnummer = "27127000293"
var postInfo = new FysiskPostInfo(
            fysiskPostMottakerPersonnummer,
            mottaker, 
            Posttype.A, 
            Utskriftsfarge.SortHvitt, 
            Posthåndtering.MakuleringMedMelding, 
            returMottaker
);

Metoder og klasser som er obsolete eller fjernet

Utdaterte konsepter er markert med obsolete. Det er anbefalt å benytte overloadet metoder. Under følger en listet over noen berørte klasser og felter. Generelt er alle felter som har med sertifikat markert som obsolete. Bakgrunnen for dette er at integrasjonspunktet nå håndterer dette.

• CertificateReader: Klasse og alle metoder er obsolete.
• Databehandler: Konstruktør som tar inn sertifikat. Feltet Sertifikat er market som obsolete og error:true (kaster feil om det aksesseres).
• Kvitteringsforespørsel: Prioritet og MpcID er obsolete.
• FysiskPostMottaker: Konstruktør som tar inn sertifikat er obsolete.
• DigitalPostMottaker: Konstruktør som tar inn sertifikat er obsolete.
• KlientKonfigurasjon: AktiverLagringAvDokumentpakkeTilDisk og Dokumentpakkeprosessorer er fjernet. Det er integrasjonspunktet som er ansvarlig for å lage ASiC.
• EpostVarsel: Konstruktører som tar inn e-postadresse er obsolete.
• SmsVarsel: Konstruktører som tar inn mobilnummer er obsolete.

mpcID

MpcID settes nå i integrasjonspunktet.

Prioritet

Kø-prioritet settes nå i integrasjonspunktet.

Nøkler og sertifikat

Nøkler og sertifikater håndteres av integrasjonspunktet.

Debugging

Sette opp logging

Klient biblioteket har evnen til å logge nyttig informasjon som kan bli brukt for debugging. For å skru på logging, gi SikkerDigitalPostKlient en Microsoft.Extensions.Logging.ILoggerFactory i konstruktøren. Dette er Microsoft sitt eget logging API og lar brukeren velge deres egen logging framework.

Om du skrur på logging med nivå DEBUG vil output være positive resultater av requests og verre, WARN gir bare feilet requests eller verre, mens ERROR gir bare feilet requests. Disse loggerne vil være under Difi.SikkerDigitalPost.Klient namespace.

Implementing using NLog

Det er flere måter å implementere en logger, men følgene eksempler vil være basert på NLog dokumentasjonen.

1. Installer Nuget pakkene NLog, NLog.Extensions.Logging og Microsoft.Extensions.DependencyInjection.
2. Legg en nlog.config fil. Den følgende er ett eksempel som logger til både fil og konsol:

<?xml version="1.0" encoding="utf-8"?>

<!-- XSD manual extracted from package NLog.Schema: https://www.nuget.org/packages/NLog.Schema-->
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xsi:schemaLocation="NLog NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      autoReload="true"
      internalLogFile="c:\temp\console-example-internal.log"
      internalLogLevel="Info">
    <!-- the targets to write to -->
    <targets>
        <!-- write logs to file -->
        <target xsi:type="File"
                name="fileTarget"
                fileName="${specialfolder:folder=UserProfile}/logs/difi-sikker-digital-post-klient-dotnet/difi-sikker-digital-post-klient-dotnet.log"
                layout="${date}|${level:uppercase=true}|${message} ${exception}|${logger}|${all-event-properties}"
                archiveEvery="Day"
                archiveNumbering="Date"
                archiveDateFormat="yyyy-MM-dd"/>
        <target xsi:type="Console"
                name="consoleTarget"
                layout="${date}|${level:uppercase=true}|${message} ${exception}|${logger}|${all-event-properties}" />
    </targets>

    <!-- rules to map from logger name to target -->
    <rules>
        <logger name="*" minlevel="Trace" writeTo="fileTarget,consoleTarget"/>
    </rules>
</nlog>

I din applikasjon, gjør følgende for å lage en logger og gi den til SikkerDigitalPostKlient:

private static IServiceProvider CreateServiceProviderAndSetUpLogging()
{
    var services = new ServiceCollection();

    services.AddSingleton<ILoggerFactory, LoggerFactory>();
    services.AddSingleton(typeof(ILogger<>), typeof(Logger<>));
    services.AddLogging((builder) =>
    {
        builder.SetMinimumLevel(LogLevel.Trace);
        builder.AddNLog(new NLogProviderOptions
            {CaptureMessageTemplates = true, CaptureMessageProperties = true});
        NLog.LogManager.LoadConfiguration("./nlog.config");
    });

    return services.BuildServiceProvider();
}

static void Main(string[] args)
{
    //Oppsett beskrevet tidligere:
    Klientkonfigurasjon klientKonfig = null;
    Databehandler dataBehandler = null;
    
    var serviceProvider = CreateServiceProviderAndSetUpLogging();
    var client = new SikkerDigitalPostKlient(dataBehandler, klientKonfig, serviceProvider.GetService<ILoggerFactory>());
}

Request og Response Logging

Til integrasjon og debugging formål så kan det være nyttig å logge direkte requests og responses som kommer “over the wire”. Dette kan oppnåes ved å gjøre følgende:

Sett denne property Klientkonfigurasjon.LoggForespørselOgRespons = true.

Merk at logging av forespørsel og respons kan gi betraktlig dårligere ytelse.

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å:

1. Aktiver logging til disk vha Klientkonfigurasjon.AktiverLagringAvDokumentpakkeTilDisk.
2. Implementer IDokumentPakkeProsessor og legg til i Klientkonfigurasjon.Dokumentpakkeprosessorer

Klientbiblioteket benytter en HttpWebRequest for å kommunisere med integrasjonspunktet. 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.

System.Net.ServicePointManager.DefaultConnectionLimit = 3;

Se ServicePointManager.DefaultConnectionLimit for mer informasjon.

Klassen SikkerDigitalPostKlient fungerer best ved at man oppretter en instans per applikasjon. SikkerDigitalPostKlient bruker en og samme instans av HttpClient under panseret. Denne klassen er trådsikker og beste måte å bruke denne klassen på er å ha en instans per applikasjon som gjenbrukes for alle http-kall i applikasjons levetid. Av trådsikkerhetshensyn og ytelse er dette også måten brukere av biblioteket bør benytte SikkerDigitalPostKlient på.