Die DVDV-Bibliothek für .NET

Die DVDV-Bibliothek für .NET bietet einen einfachen Zugang zu der REST-API des Deutschen Verwaltungsdiensteverzeichnis. Sie richtet sich damit am Hersteller:innen von in .NET programmierten Fachverfahren. Die DVDV-Bibliothek ist eine .NET Standard 2.0-Bibliothek und unterstützt folglich .NET Core und .NET Framework gleichermaßen.

Sie bietet folgende Funktionalitäten:

  • Authentifizierung entweder am IAM/Keycloak oder direkt am DVDV-Server mittels zertifikatbasierter Authentifizierung ("Standalone-Authentifizierung") sowie den Zugriff ohne Authentifizierung über die intern-Schnittstelle per Konfiguration.
  • Failover zur Nutzung von mehreren DVDV-Servern. Ist ein Server nicht erreichbar, dann wird der nächste Server in der Kette verwendet.
  • Aufruf der DVDV2-Rest-Services und Aufbereitung der Service-Antwort in einem dedizierten Datenmodell.

Beispiele

Als Einstieg eignet sich das Beispiel dvdv-dotnet-controlfile. Dabei handelt es sich um eine Kommandozeilenapplikation für solche Aspekte der Bibliothek, die eine umfangreiche Parametrisierung erfordern.

Das o.a. Beispiel wird in einer CI/CD-Pipeline gebaut und in einer default-Konfiguration gestartet, sodass Sie sich von der Lauffähigkeit des Beispiels überzeugen können.

API-Dokumentation

Hier finden Sie die API-Dokumentation. Einstiegspunkt für die API ist die Klasse Dvdv.Impl.Manager.DVDV2ManagerFactory bzw. das Interface Dvdv.Api.Manager.IDVDV2ManagerFactory. Informationen zur Initialisierung des factory-Objektes finden Sie in IDVDV2ManagerFactory.Initialize

Kurze Übersicht

Derzeit sind die folgenden Methoden am Interface DVDV2Manager umgesetzt

  • FindOrganizationDescription: Suche nach einer Organisation oder einem Stellvertreter; vergleichbar zur Methode FindAuthorityDesctiption aus DVDV1.

    • Eingabeparameter: Organisationsschlüssel, Kategorie der Organisation
    • Rückgabewert: Die einzige zu den Eingabewerten passende Organisation (inklusive aller ihrer Dienste und Stellvertreter), falls es eine solche gibt.

  • findOrganizationDescriptions: Suche nach Organisationen oder Stellvertretern; vergleichbar zur Methode findOrganizationDescription, allerdings ohne Angabe der Kategorie.

    • Eingabeparameter: Organisationsschlüssel
    • Rückgabewert: Liefert die Organisationen, die den angegebenen Organisationsschlüssel haben, falls es solche gibt. Das ist fast immer höchstens eine.

  • FindServiceDescription: Suche nach einem Dienst zu einer Organisation; vergleichbar zur entsprechenden Methode aus DVDV1.

    • Eingabeparameter: Organisationsschlüssel, URI der Dienstspezifikation
    • Rückgabewert: Der einzige zu den Eingabewerten passende und zum Zeitpunkt des Aufrufs gültige Dienst, falls es einen solchen gibt.

  • VerifyCategory: Suche nach einer Organisation oder einem Stellvertreter, vergleichbar zur entsprechenden Methode aus DVDV1.

    • Eingabeparameter: Kategorie der Organisation, Fingerprint eines Client-Zertifikates
    • Rückgabewert: true, wenn zu dem Zertifikat eine Organisation der entsprechenden Kategorie existiert, false sonst

  • FindCategories: Ermittlung der Kategorie einer Organisation oder eines Stellvertreters

    • Eingabeparameter: Organisationsschlüssel, Fingerprint eines Client-Zertifikates
    • Rückgabewert: Liste der Kategorien derjenigen Organisationen, die den angegebenen Schlüssel und das angebene Client-Zertfifikat haben. (Davon gibt es i.d.R. nur höchstens eine.)

  • findServiceSpecificationUrisByCategory: Ermittlung aller URIs von Diensten, die eine Organisation der angegebenen Kategorie anbieten darf

    • Eingabeparameter: Organisationsategorie
    • Rückgabewert: Liste aller Dienste-URIs von solchen Dienstbeschreibungen, die eine Organisation anbieten darf, wenn sie die angegebene Kategorie hat.

  • FindOrganizationsByServiceElement: Suche von Organisationen suchen anhand bestimmter Eigenschaften eines ihrer Dienstelemente.

    • Eingabeparameter: Dienstelementtyp sowie und ein weiterer Suchparameter, gegeben durch Typ und Wert
    • Rückgabewert: Liste derjenigen Organisationen, die ein Dienstelementzertifikat von angegeben Dienstelementtyp haben, das außerdem das mit den Suchparameter angegeben Kriterium erfüllt.

  • FindCertificateByFingerprint: Suche nach einem Zertifikat anhand eines Fingerprint

    • Eingabeparameter: Fingerprint eines Zertifikates
    • Rückgabewerte: Das Zertifikat mit dem angegebenen Fingerprint, wenn es in der DVDV-Datenbank hinterlegt ist.

  • getIntermediaries: Ermittelt alle Intermediäre im DVDV

    • Eingabeparameter: keine
    • Rückgabewerte: Liste aller im DVDV verzeichneten Intermediäre mit Angabe der URI, des Namens und der zugehörigen Organisation/ des Providers.

  • getCategories: Liefert den Baum aller im DVDV verzeichneten Kategorien.

    • Eingabeparameter: keine
    • Rückgabewerte: Liste aller im DVDV verzeichneten Kategorien.

Fast alle oben angegebenen Methoden sind überladen mit einer sogenannte "batch-Variante". Mit der jeweiligen batch-Variante erhalten Sie die Rückgabewerte von mehreren Einzelmethodenaufrufen mit einem einzelnen HTTP(S)-Request.

Failover

Beim Auruf von IDVDV2ManagerFactory.Initialize können Sie mehrere DVDV-Serververbindungen angeben. Der Eintrag mit Index 0 ist der Standard-DVDV-Server. Die der jeweils folgende Eintrag wird nur benutzt, wenn alle vorangegangenen ausgefallen sind (Failover). In diesem Fall wird die DVDV-Bibliothek in gewissen Abständen versuchen, wieder auf den Standard-DVDV-Server zu wechseln. Wenn Ihr Fachverfahren auf Failover-Ergeignisse reagieren soll, verwenden Sie die Methode IDVDV2Manager.AddFailoverListener

Download

Die Bibliothek finden Sie im Package Repository.