AabcDigi.StilBrugerdatabasen.Oces3 1.3.0

AabcDigi.StilBrugerdatabasen.Oces3

Cross-platform SDK for integrating with STIL Brugerdatabasen using OCES3 WS-Security SOAP signing.

Targets .NET Framework 4.8.1 and .NET 9.

Installation

dotnet add package AabcDigi.StilBrugerdatabasen.Oces3

What this package does

• Signs SOAP envelopes with WS-Security (RSA-SHA256, X.509 certificate)
• Sends signed requests via HttpClient
• Bridges WCF-generated Message contracts to/from raw XML
• One-call client construction via BrugerdatabasenClientFactory
• Works on both .NET Framework 4.8.1 and modern .NET

What this package does NOT do

• Generate service contracts � use dotnet-svcutil or svcutil.exe in your own project
• Load configuration � pass resolved values directly
• Handle authentication beyond certificate signing

Quick start � .NET 9

1. Generate contracts

dotnet tool install --global dotnet-svcutil
dotnet-svcutil https://brugerdatabasen.stil.dk/bpi/wsaimport/8?wsdl \
    --outputDir Generated/WsaImport \
    --namespace "*,MyApp.Generated.WsaImport"

2. Load your certificate

var cert = CertificateLoader.Load(certCfg);

• Windows certificate store: pass a CertificateStoreOptions instance
• .p12/.pfx file: pass a CertificateFileOptions instance

3. Configure and call

using AabcDigi.Integration.Stil.Brugerdatabasen.Oces3.Client;
using AabcDigi.Integration.Stil.Brugerdatabasen.Oces3.Configuration;

var options = new StilBrugerdatabasenOptions
{
    BaseUrl = "https://brugerdatabasen.stil.dk/bpi/",
    Endpoints = new Dictionary<string, string>
    {
        [BrugerdatabasenEndpoints.WsaImport]         = "wsaimport/8",
        [BrugerdatabasenEndpoints.WsiBruger]         = "wsibruger/7",
        [BrugerdatabasenEndpoints.WsiEksport]        = "wsieksport/7",
        [BrugerdatabasenEndpoints.WsiInst]           = "wsiinst/6",
        [BrugerdatabasenEndpoints.WsiIdentifikation] = "wsiidentifikation/4"
    }
};

// Construct once � captures options, certificate and HttpClient.
var factory = new BrugerdatabasenClientFactory(options, cert);

// Call Create() per service invocation � cheap, no allocations.
var client = factory.Create();

// Preferred: pass the generated channel type � the SOAP action is resolved automatically
// from the [OperationContract] attribute on the channel interface.
var response = await client.SendAsync<
    WsaImportPortTypeChannel,
    helloWorldWithCertificateRequest,
    helloWorldWithCertificateResponse>(
        BrugerdatabasenEndpoints.WsaImport,
        new helloWorldWithCertificateRequest(
            new UdbydersystemIdType { Value = "your-udbydersystem-id" },
            new NoArgs()
        ));

If you need to supply the SOAP action manually (e.g. for a channel type not generated by svcutil), use the explicit overload:

var response = await client.SendAsync<helloWorldWithCertificateRequest, helloWorldWithCertificateResponse>(
    BrugerdatabasenEndpoints.WsaImport,
    "https://brugerdatabasen.stil.dk/bpi/wsaimport/8/WsaImportPortType/helloWorldWithCertificateRequest",
    new helloWorldWithCertificateRequest(
        new UdbydersystemIdType { Value = "your-udbydersystem-id" },
        new NoArgs()
    ));

Quick start � .NET Framework 4.8.1

1. Generate contracts

Use svcutil.exe from the Windows SDK:

"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\svcutil.exe" ^
    https://brugerdatabasen.stil.dk/bpi/wsaimport/8?wsdl ^
    /out:WsaImportClient.cs /language:C# /noConfig /async

2. Load your certificate

// From Windows certificate store
using (var store = new X509Store(StoreName.My, StoreLocation.CurrentUser))
{
    store.Open(OpenFlags.ReadOnly);
    var cert = store.Certificates
        .Find(X509FindType.FindByThumbprint, "YOUR_THUMBPRINT", false)[0];
}

// Or from a .pfx file
var cert = new X509Certificate2("path\\to\\cert.pfx", "password");

3. Configure and call

using AabcDigi.Integration.Stil.Brugerdatabasen.Oces3.Client;
using AabcDigi.Integration.Stil.Brugerdatabasen.Oces3.Configuration;

var options = new StilBrugerdatabasenOptions
{
    BaseUrl = "https://brugerdatabasen.stil.dk/bpi/",
    Endpoints = new Dictionary<string, string>
    {
        { BrugerdatabasenEndpoints.WsaImport,         "wsaimport/8"         },
        { BrugerdatabasenEndpoints.WsiBruger,         "wsibruger/7"         },
        { BrugerdatabasenEndpoints.WsiEksport,        "wsieksport/7"        },
        { BrugerdatabasenEndpoints.WsiInst,           "wsiinst/6"           },
        { BrugerdatabasenEndpoints.WsiIdentifikation, "wsiidentifikation/4" }
    },
    UdbydersystemId = "US..."
};

// Construct once � captures options, certificate and HttpClient.
var factory = new BrugerdatabasenClientFactory(options, cert);

// Call Create() per service invocation � cheap, no allocations.
var client = factory.Create();

// Preferred: pass the generated channel type � the SOAP action is resolved automatically
// from the [OperationContract] attribute on the channel interface.
var response = await client.SendAsync<
    WsaImportPortTypeChannel,
    helloWorldWithCertificateRequest,
    helloWorldWithCertificateResponse>(
        BrugerdatabasenEndpoints.WsaImport,
        new helloWorldWithCertificateRequest(
            new UdbydersystemIdType { Value = options.UdbydersystemId },
            new NoArgs()
        ));

If you need to supply the SOAP action manually, use the explicit overload:

var response = await client.SendAsync<helloWorldWithCertificateRequest, helloWorldWithCertificateResponse>(
    BrugerdatabasenEndpoints.WsaImport,
    "https://brugerdatabasen.stil.dk/bpi/wsaimport/8/WsaImportPortType/helloWorldWithCertificateRequest",
    new helloWorldWithCertificateRequest(
        new UdbydersystemIdType { Value = options.UdbydersystemId },
        new NoArgs()
    ));

Client factory

BrugerdatabasenClientFactory is an instance class that captures StilBrugerdatabasenOptions, the XmlSigner and the HttpClient once at construction. Call the parameterless Create() on every service invocation � it is cheap and all underlying resources are reused.

// From a certificate store / file options class �
var factory = new BrugerdatabasenClientFactory(options, certCfg);

// � or from an already-loaded certificate
var factory = new BrugerdatabasenClientFactory(options, cert);

// Per service call � no arguments needed
var client = factory.Create();

Reusing a singleton HttpClient

Each constructor overload accepts an optional HttpClient. When omitted, the factory creates one internally and reuses it across all Create() calls. In long-running services, pass a shared singleton � it is borrowed and never disposed by the factory:

private static readonly HttpClient SharedClient = new(new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(5) // refresh DNS periodically
});

var factory = new BrugerdatabasenClientFactory(options, certCfg, SharedClient);

Configuration reference

{
  "StilBrugerdatabasen": {
    "BaseUrl": "https://brugerdatabasen.stil.dk/bpi/",
    "Endpoints": {
      "WsaImport":         "wsaimport/8",
      "WsiBruger":         "wsibruger/7",
      "WsiEksport":        "wsieksport/7",
      "WsiInst":           "wsiinst/6",
      "WsiIdentifikation": "wsiidentifikation/4"
    }
  }
}

Endpoint constants

Use BrugerdatabasenEndpoints to avoid magic strings:

BrugerdatabasenEndpoints.WsaImport         // "WsaImport"
BrugerdatabasenEndpoints.WsiBruger         // "WsiBruger"
BrugerdatabasenEndpoints.WsiEksport        // "WsiEksport"
BrugerdatabasenEndpoints.WsiInst           // "WsiInst"
BrugerdatabasenEndpoints.WsiIdentifikation // "WsiIdentifikation"

License / Licens

English

This software is licensed under the European Union Public Licence v1.2 (EUPL-1.2).

You may use, modify, and distribute this software under the terms of the EUPL-1.2.
The full licence text is available at:
https://interoperable-europe.ec.europa.eu/collection/eupl/eupl-text-eupl-12

See LICENSE for the copy included in this repository.

Dansk

Denne software er licenseret under European Union Public Licence v1.2 (EUPL-1.2).

Du m� bruge, �ndre og distribuere denne software i henhold til betingelserne i EUPL-1.2.
Den fulde licenstekst er tilg�ngelig p�:
https://interoperable-europe.ec.europa.eu/collection/eupl/eupl-text-eupl-12

Se LICENSE for den kopi, der er inkluderet i dette repository.