Microsoft SQL Server Master Data Services (MDM)

Einleitung

Master Data Services – kurz MDM – ist ein Bestandteil der SQL Server Produktpalette seit SQL Server 2008 R2 und hat sich in den letzten Jahren bis 2016 nur marginal weiterentwickelt. Dies lag vorwiegend daran, dass Microsoft den Schwerpunkt auf den Business Intelligence Stack gelegt hatte.

Mit dem Release von SQL Server 2017 wurde MDM grundlegend erneuert: HTML5 und neue Technologien tragen zu Stabilität und Akzeptanz bei.

Am Namen und der damit verbundenen, hohen Erwartungshaltung wurde (leider) nichts geändert: was dem Thema an sich zwar nicht schadet, aber für Erklärungsbedarf sorgt.

Was ist MDM und was sind die Herausforderungen, die damit gelöst werden sollen?

In der reinen Theorie ist MDM eine Grundsatzentscheidung dafür, seine Unternehmensdaten zentral zu verwalten, zu vereinheitlichen und dadurch die Grundlage für belastbare Aussagen/Auswertungen zu schaffen.

Auch 2017 sind Unternehmen noch immer damit konfrontiert, Daten aus einer Vielzahl von Systemen zu verwalten. Ist-Daten aus System A wollen in einer Auswertung mit Plan-Daten aus System B angereichert werden. Eine Verknüpfung ist meist aufwändig bzw. gar nicht möglich, da die Datensätze zwar logisch ident sind, aber aufgrund der Schreibweise trotzdem unterschiedlich sind (z.B. Halle8 <> Halle 08).

MDM Systemlösungen

Zur Umsetzung von MDM gibt es bereits viele Produkte: SQL Server, MUM, inubit, SAP MDM, Biztalk, etc. Viele davon bieten einen vordefinierten Bausatz an Funktionen, um sich dem Thema zu nähern.

Eine Standardlösung, ohne jegliche Zusatzprogrammierung, ist aber weder mit Produkt A noch mit Produkt B realistisch – auch wenn das gerne postuliert wird.

Die hohe Kunst im Bändigen von MDM besteht darin, die Verflechtung von organisatorischen und IT-technischen Aktivitäten a) bestmöglich zu koordinieren und b) ein Tool zu verwenden, das die Abläufe und Datenflüsse bestmöglich visualisiert und beim Bearbeiten von Dateninkonsistenzen unterstützt.

Eine optimale MDM-Lösung ist ein Zusammenspiel aus Systemkomponenten (IT) und organisatorischen Verantwortlichkeiten (Fachbereich), bei dem nicht das IT-Tool im Vordergrund steht. Vielmehr ist das Bewusstsein für ein integratives, workflowbasiertes „Doing“ zu beachten.

MDM Projektansatz bei PASO Solutions

Ein Ansatz, den wir bei PASO Solutions in MDM-Projekten bereits erfolgreich umsetzen konnten, wird in folgender Architekturskizze beleuchtet.

  1. Vorsysteme tauschen Daten über eine sog. Datendrehscheibe – kurz DDS – aus, welche in der Regel als relationale Datenbank realisiert wird. Dadurch ist gewährleistet, dass die Daten mittels SQL-basierten Tools abgelegt und analysiert werden können. Auch dateibasierte Schnittstellen (z.B. XML) können mittels EAI-Tools (vgl. inubit, BizTalk) in die DDS überführt werden.
  2. In der DDS gibt es ein mehrstufiges System zur Datenqualitätsabsicherung. Dazu werden die Rohdaten zuerst in einem sog. Staging-Bereich gesammelt. Neuartige, noch nicht validierte Datensätze werden vom Staging-Bereich in den MDM-Bereich transferiert. Sie haben somit den Status DATEN_UNGEPRÜFT.
  3. Im MDM-Bereich erfolgt die klassische Validierung, insb. auf Dubletten und Inkonsistenzen. Dazu werden Standardalgorithmen wie bspw. Fuzzy-Logic und sog. Mapping-Tabellen herangezogen, um Datensätze zu identifizieren und in unterschiedliche Problemklassen einzuteilen. Der neue Status ist nun DATEN_KLASSIFIZIERT.
  4. Mittels automatisierter Berichte (vgl. SSRS-Abonnements) ist es möglich, Dateninkonsistenzen periodische an sog. Clearing-Stellen zu berichten. Solche Prüfberichte können mittels HTML-Links in webbasierte MDM-Systeme verbinden, um den Korrektur-Ablauf für die Benutzer bestmöglich zu gewährleisten.
  5. Manuell nachbearbeitete Datensätze werden vom MDM zurück an die DDS geliefert und überführen die Datensätze in den nächsten Datenqualitätsstatus DATEN_VALIDIERT.
  6. Über eine konfigurierbare Signal-Funktion werden von der DDS die validierten Daten an andere Systeme weitergeleitet (Trigger-basiert).
Blogeintrag_MDM
Architekturskizze

Vorteile durch MDM mittels Microsoft SQL Server Stack

Microsoft SQL Server bietet neben der klassischen relationalen Datenbank viele weitere Services out-of-the-box. Neben den bekannten Themen wie Analysis Services (SSAS), Reporting Services (SSRS) und Integration Service (SSIS) drängen nun verstärkt die neuen, exotischen Services in den Vordergrund:

Machine-learning Services (vormals R-Services) und Master-Data-Services bilden im Verbund mit den tradierten Services ein optimales Toolset, um den MDM Projektansatz umsetzen zu können.

Mittels MDM können im Clearing-Center durch Machine-learning-Services vorvalidierte Datensätze nachbearbeitet werden, um dann mittels Integration Services zwischen den Datenqualitätsstufen transferiert zu werden.

Alles aus einer Hand, mit einem Toolset und zu einem lukrativen Preis, insbesondere dann, wenn Microsoft-SQL-Server-Lizenzen bereits vorhanden sind, nahezu kostenfrei.

Conclusio

MDM Services von Microsoft ist eine Komponente, um MDM erfolgreich umzusetzen. Aber erst das Zusammenspiel des kompletten SQL Server Stacks ermöglicht eine umfassende und integrative Behandlung des Themas. Organisatorische Rahmenbedingungen (Clearing-Stelle) und Workflow-basierte Abarbeitung sind das A und O, um die Komplexität zu beherrschen.

Advertisements

SAP HANA und Microsoft BI: a true love-story?

Mit der neuen SAP HANA In Memory Technologie ist nun auch ein einfacher Zugriff auf SAP-Daten möglich.

Dazu gibt es im Microsoft BI Umfeld interessante Möglichkeiten, um an wertvolle ERP-Informationen zu gelangen

1. Zugriff mittels PowerBI Desktop

In der Self-Service-BI Suite „PowerBI Desktop“ ist ein Zugang mit dem neuen SAP HANA Connector möglich.

Zuerst ist es aber erforderlich, die SAP HANA ODBC Treiber für Windows zu installieren. Diese können unter https://support.sap.com/en/my-support/software-downloads.html direkt von SAP bezogen werden. Hier ist eine S-ID Voraussetzung, die man vom unternehmensinternen SAP-Admin erhalten kann.

Sind die ODBC-Treiber installiert, kann mit wenigen Klicks eine Verbindung zum HANA Server aufgebaut werden. Single-Sign-On und Berechtigung im SAP sind hier Voraussetzung.

Ist die Berechtigungshürde gemeistert, kann auf die entsprechenden Entitäten im HANA Datenbankmodell zugegriffen werden. Eine detaillierte Anleitung findet sich unter dem BI Channel von PowerBI https://www.youtube.com/watch?v=Zpbh6UE3pSE

2. Zugriff über SAP-PO und ETL

Ein Zugriff auf SAP Daten funktioniert am besten über die Schiene SAP PO (Process Orchestration) bzw. dem Vorgänger-System PI (Process Integration: https://de.wikipedia.org/wiki/SAP_Process_Integration ).

Dabei werden die SAP-Daten mittels PO auf eine unabhängig Datendrehscheibe (DDS) transferiert. PO kümmert sich nur um die erste Meile (von SAP zur DDS) und um die letzte Meile (von DDS nach SAP). SAP PO kann dabei auf BAPI, RFC sowie neue HANA Methoden zugreifen.

Die Datenextrakte werden mittels SQL-Statements auf Basis von JDBC direkt in eine SQL-basierte DDS geschrieben. Bspw. können mit einem SAP-Report alle FI-Belege eines Geschäftsjahres extrahiert werden. Diese Daten greift die PO auf, generiert ein SQL-Insert-Statement, welches dann auf die DDS abgesetzt wird. Sobald der Extraktionsvorgang fertig ist, ruft die PO eine Stored-Procedure auf der DDS auf, welche die Fertigmeldung absetzt und Folgeprozesse anstößt (bspw. den Weitertransport von der DDS in das DWH).

Hinweis: die PO/PI ist asynchron, d.h. man muss einen „Wait-On-PO“-Job anstoßen, der solange wartet, bis alle Daten aus der PO in die DDS übertragen wurden. Das ist zwar nicht ganz schön, funktioniert aber insofern charmant, weil die PO vor dem Übertrag nach DDS weiß, wie viele Datensätze ankommen sollen. Der WaitOnPO-Job wartet dann solange, bis in der DDS diese Anzahl an Datensätzen angekommen ist.

Alle anderen Schritte der klassischen ETL-Strecke – also Transformation/Harmonisierung und Datenkonvertierungen sollen in dafür spezialisierten EAI-Tools gemacht werden (inubit, SSIS, etc.).

Aus heutiger Sicht ist die PO leider zu schwerfällig und benutzerunfreundlich.

PowerBI-Reportserver: Was steckt wirklich dahinter?

Mit Juni und später mit August 2017 stellte Microsoft seine Antwort auf die Konkurrenz durch Qlikview und Tableau vor: Lokale Berichterstellung mit Power BI-Berichtsserver (https://powerbi.microsoft.com/de-de/report-server/)

Versprochen wird eine Verknüpfung der neuen Self-Services-Features, die seit 2016 durch Power BI Desktop bekannt sind, kombiniert mit den mächtigen Standard-Reporting-Funktionen der Reporting-Services aus dem SQL Server Stack. Damit können moderne, interaktive Berichte on-premise den unternehmens-internen Benutzern zur Verfügung gestellt werden.

Look&Feel sowie Funktionalität halten auf den ersten Blick die Versprechungen einer „Self-Service-BI und Enterprise-Berichterstellung – in einer Komplettlösung“. Berichte, die mittels einer speziellen Power BI Desktop-Version gewohnt intuitiv erstellt werden, können mit wenigen Klicks auf der Reportwebsite bereitgestellt werden. Bekannte PowerBI Rendering-Elemente stehen ebenso zur Verfügung wie exotischere Varianten von Stacked-Bars und Funnel-Diagrammen. Außerdem können bestehende paginierte Standardberichte Seite an Seite auf dem Power BI-Reportserver veröffentlicht werden. Das von QlikView vorzelebrierte Rendering ohne Fullsite-Postbacks ist in der gänzlich HTML5 basierten Power BI Reportserver-Umgebung exzellent umgesetzt. Das Warten auf bestimmte Ereignisse bereitet dank asynchroner Webabrufe kaum Probleme. Die Berichts-Visualisierung ist am Smartphone, Tablet und PC ohne zusätzliche Programmierung möglich.

Zu all dem Licht gehört leider auch ein wenig Schatten: um eine vollständige Konkurrenz zu den großen Playern im on-premise Self-Service darzustellen, fehlt leider die letzte Konsequenz. Was sicher auch der ersten, Microsoft-Philosophie folgenden „unvollständigen“ Preview-Version zu schulden ist. Gerade die bekannten Features „Abonnement“ und „Security-Einstellungen“ aus SSRS fehlen, um einen vollwertigen Einsatz in Organisationen zu ermöglichen. Auch die Einschränkung auf multi-dimensionale Datenquellen (SSAS) stellte im „June“-Release eine größere Einstiegshürde dar – gerade dann, wenn Kerberos und Server-Hoping unbekanntes Terrain ist.

Mit dem „August“-Release sind mittlerweile auch relationale Datenquellen verfügbar.

Eine Empfehlung ist an dieser Stelle schwierig:

Auf der einen Seite ist der erste Wurf (der Konkurrenz geschuldet) zu schnell erfolgt: wie bei vielen Microsoft-Produkten!

Durch das frühe Release ist es zwar möglich, die Zielrichtung zukünftiger Funktionen abzuschätzen. Dennoch ist von einem produktiven Einsatz in ergebnis-orientierten Organisationen aus heutiger Sicht abzuraten.

Auf der anderen Seite ist ein frühes Auseinandersetzen mit den neuen Power PI Funktionen durchaus sinnvoll. Gerade unendliche Erweiterungsmöglichkeiten durch R und CustomVisuals legen die Grundlage für moderne Reporting-Plattformen, die nicht mehr nur reine Datenfriedhöfe sondern moderne Self-Service-Reporting-Shops realisieren.

SQL Server 2017 SSIS Catalog und Project Connections

SSIS Catalog ist eine zentrale Ablage von SSIS-Paketen, die nun mit Click-Once Deployment direkt aus dem Visual Studio auf den SQL Server veröffentlicht werden können.

Im Zuge der zentralen Ablage können nun auch Project-Connections verwendet werden, die so für alle Packages einer SSIS-Projektes verwendet werden können.

Beim Deployen von SSIS-Paketen, die auf Project-Connections verweisen, ist darauf zu achten, dass vorher auch die in diesem Paket verwendeten Project-Connections veröffentlicht werden.

Das Veröffentlichen von Project-Connections funktioniert leider nicht singulär, sondern es muss die gesamte SSIS-Projektmappe veröffentlich werden.

Unbenannt

 

POWER BI REPORT SERVER

Technical Preview:
Funktionsumfang & Einschränkungen

Die am 17.05.2017 vorgestellte Power BI Report Server Preview (Blog Announcement) erweitert die bisherigen SQL Server Reporting Services. Zu den unterstützten Berichtstypen gehört nun neben den vorhandenen Berichttypen, Paginierter (RDL) und Mobil (Datazen), auch der Power BI Bericht.

pbrs
Produktvergleich

Bisher war Power BI fast gänzlich in der Cloud. Entweder durch benutzen des Power BI Online Portals bzw. Azure Power BI Embedded konnten die Berichte zentral gespeichert und gerendert werden. Mithilfe von Power BI Desktop und SQL Server Reporting Services (welches die Power BI Berichte nur ablegen jedoch nicht darstellen kann) konnte man zwar die Cloud umgehen war aber dadurch auch sehr eingeschränkt. Die On-Prem Enterprise Lösung bietet nun der Power BI Report Server.

Konfiguration

Um den Power BI Report Server zu installieren ist ein installierter SQL Server notwendig. Weitere Voraussetzungen sind unter Reportserver System Requirements detailliert aufgelistet.

Über den Installer kann der Power BI Report Server installiert werden (Downloadlink). Nach erfolgreicher Installation muss das Ganze noch über den Report Server Configuration Manager konfiguriert werden. Diese Konfiguration ist ident mit dem Reporting Services Configuration Manager. Falls bereits SSRS installiert ist muss darauf geachtet werden verschiedene Zugriffs URLs festzulegen, da beide dieselben Standardeinstellungen verwenden. Eine detaillierte Anleitung zur Installation & Konfiguration findet man unter folgendem Link:  Reportserver Installation

Workflow

Über das Webportal und Power BI Desktop können nun Berichte hinzugefügt, erstellt und verwaltet werden. Hierbei zu beachten ist, dass dazu derzeit eine spezielle Version von Power BI Desktop für die Erstellung zu verwenden ist. Diese kann unter demselben Link wie die Report Server Installationsdatei heruntergeladen werden. Der Workflow ist sehr ähnlich wie bei den anderen Berichtstypen. (Handbuch)

Einschränkungen

Eine wesentliche Einschränkung der aktuellen Version ist, dass derzeit nur Berichte mit einer Live-Verbindung zu Analysis Services unterstützt werden.

Zusammenfassung

Der neue Power BI Report Server unterstützt nun alle Berichtstypen des Microsoft Technologie Stacks. Da Power BI Berichte vom Funktionsumfang, Interaktivität und Usability sich in gewisser Weise von den anderen Berichtstypen absetzen und auch deren Weiterentwicklung von Microsoft stark vorangetrieben wird ist eine On-Prem Unterstützung ein logischer und notwendiger Schritt um sich als Standard für Berichte zu etablieren.

Unstrukturierte Exceldaten mit SSIS

In seltenen Fällen müssen Exceldaten mit SSIS eingelesen werden, die keine tabellarische Struktur haben. Bspw. sind das Formulare, die besondere Usability-Anforderungen haben.

Hierfür sind die Standard-SSIS-Source-Connections nicht brauchbar, da diese nur Daten in tabellarischer Form auslesen können.

Abhilfe schafft hier die generische einsetzbare Skript-Komponente mit der Einstellung als Quelle/Source.

 

Folgende Schritte sind einzustellen:

  1. Zuerst übergibt man den gesuchten Datei-Namen als „Readonly“-Variable in die Komponente.
  2. Danach müssen die Ausgabe-Spalten definiert werden
  3. Der wichtigste Part betrifft das C#-Skript an sich
  4. Zuerst müssen die Referenzen für Excel (Microsoft Excel 14.0 Object Library) und CSharp (Microsoft.CSharp.dll) hinzugefügt werden

 

public void GetData(string fileCheckout)
{

Microsoft.Office.Interop.Excel.Application oXL = null;
Microsoft.Office.Interop.Excel.Workbook mWorkBook = null;
Microsoft.Office.Interop.Excel.Worksheet mWSheet3 = null;
Microsoft.Office.Interop.Excel.Range xlRange = null;
try
{
oXL = new Microsoft.Office.Interop.Excel.Application();

mWorkBook = oXL.Workbooks.Open(fileCheckout);

mWSheet3 = mWorkBook.Sheets[3]; //Bilddokumentation

xlRange = mWSheet3.UsedRange;

string FahrzeugWerk = xlRange.Cells[2, 1].Value2 as string;

string Bewertung = xlRange.Cells[4, 3].Value2 as string;  //alles in Spalte C
string Modell = xlRange.Cells[5, 3].Value2 as string;
string FGNR = xlRange.Cells[6, 3].Value2 as string;
string Fehlerort = xlRange.Cells[7, 3].Value2 as string;
string Fehlerart = xlRange.Cells[8, 3].Value2 as string;
string Anzahl = xlRange.Cells[9, 3].Value2 as string;
string Bemerkung = xlRange.Cells[10, 3].Value2 as string;
string Pruefdatum = xlRange.Cells[13, 3].Value2 as string;
string Proddatum = xlRange.Cells[14, 3].Value2 as string;

Output0Buffer.AddRow(); //hinzufügen der neuen Daten zum Output
Output0Buffer.FahrzeugWerk = FahrzeugWerk;
Output0Buffer.Bewertung = Bewertung;
Output0Buffer.Modell = Modell;
Output0Buffer.FGNR = FGNR;
Output0Buffer.Fehlerort = Fehlerort;
Output0Buffer.Fehlerart = Fehlerart;
Output0Buffer.Anzahl = Anzahl;
Output0Buffer.Bemerkung = Bemerkung;
Output0Buffer.Pruefdatum = Pruefdatum;
Output0Buffer.Proddatum = Proddatum;

}
catch (Exception ex)
{
throw ex;
}
finally
{
GC.Collect();
GC.WaitForPendingFinalizers();

Marshal.FinalReleaseComObject(xlRange);
Marshal.FinalReleaseComObject(mWSheet3);

mWorkBook.Close(Type.Missing, Type.Missing, Type.Missing);
Marshal.FinalReleaseComObject(mWorkBook);

oXL.Quit();
Marshal.FinalReleaseComObject(oXL);
}
}

REST Client generieren mittels Swagger

In diesem Artikel geht es um einen automatisierten Weg, um von einem oder mehreren  ASP.NET WebApi Controllern zu einem entsprechenden Client zu kommen. Der Client kann in einer beliebigen Sprache generiert werden, solange es ein Tool dafür gibt.

Vorerst noch eine Anmerkung: Wenn man mit .NET arbeitet, muss das Target-Framework bei mindestens 4.5.1 liegen, um die hier genannten Tools verwenden zu können.

Client generieren in Visual Studio

Anzumerken ist, dass Visual Studio mittlerweile eine native Integration für Swagger Spezifikationen hat. Um in VS einen REST Client zu generieren muss man nur ein neues Projekt erstellen, anschließend mittels Rechtsklick auf das Projekt das Kontextmenü öffnen und dann „Add->REST API Client…“ auswählen. Nachdem man das Metadata File bzw. die Url dazu eingetragen hat, muss man nur noch auf OK klicken und schon startet der Prozess (Standardmäßig muss zur WebService-URL nur „/swagger/docs/v1“ angefügt werden).

addrest

UPDATE: Bei der Verwendung von VS2015 kommt es zu einer Inkompatibilität mit Xamarin.iOS, weil die mitgelieferte AutoRest.exe zu alt ist.

Als Workaround verwenden wir stattdessen immer die neueste Version der NuGet-Pakete AutoRest und Microsoft.Rest.ClientRuntime und generieren den Client über die Kommandozeile. Zur Vereinfachung haben wir ein Powershell Skript erstellt, das einfach über die NuGet Package Manager Console ausgeführt werden kann: Tools->NuGet Package Manager->PackageManagerConsole

Zuerst muss das Skript ins Rootverzeichnis des Projektes kopiert werden. Das Skript nimmt zwei Argumente:

  1. Swagger Url
  2. Client Namespace

Beispiel.: ./autorest -swagger_url http://swaggertest.azurewebsites.net/swagger/docs/v1 -namespace SwaggerTest

Anschließend muss der Client noch in das Projekt inkludiert werden, das geht am einfachsten so:

  1. Project->Show All Files
  2. Der Ordner scheint im Portable Projekt auf mit dem Namen: [namespace]Client
  3. Rechtsklick auf diesen Ordner->Include In Project

Swagger Spezifikation generieren in Visual Studio

Aber wie kommt man nun zur besagten Spezifikation? Dafür gibt es vielerlei Möglichkeiten, z.B. den Swagger Editor auf Swagger.io. Empfehlenswert ist es allerdings ein natives Tool zu verwenden, in unserem Fall verwenden wir das NuGet Paket NSwag.CodeGeneration, das eine Middleware darstellt und das Swagger File direkt am Webserver vom Code aus generiert. Dafür müssen allerdings noch Annotationen eingefügt werden und ein bisschen Code, der das File generiert. Ein gutes Tutorial vom Entwickler selbst befindet sich z.B. hier: https://github.com/NSwag/NSwag/wiki/WebApiToSwaggerGenerator

UPDATE: Mittlerweile verwenden wir ein anderes Tool zum Generieren der Swagger Spec, das komplett auf Annotationen verzichtet und sich alle nötigen Informationen direkt aus den Web-Method-Headern und Controllernamen holt. Das besagte Tool heißt Swashbuckle, kann einfach über NuGet installiert werden und kommt ohne jegliche Konfiguration aus.

Allerdings gibt es einige Dinge, die man bei der Verwendung von Swagger und Swashbuckle beachten muss, hier eine Liste von Problemen, die bei uns bis jetzt aufgetreten sind:

Generelle Fehlersuche

Um zu Überprüfen, ob das Swagger-File (JSON File) korrekt generiert wurde, startet man den Debug-Modus und geht auf die angegebene localhost URL (falls das Browserfenster nicht automatisch aufgeht, kann man die URL herausfinden, indem man in der Taskleiste auf das IIS-Symbol rechtsklickt und dann WebService auswählt). Dann nach der URL fügt man die Route „/swagger/docs/v1“ hinzu. Kommt nun ein JSON-File, hat die Generierung funktioniert, ansonsten kommt eine Fehlermeldung. Wichtig: Wenn man den WebService bereits auf Azure gepublished hat, dann wird keine Fehlermeldung angezeigt, sondern nur „An error occured“, was zum Debuggen ziemlich nutzlos ist.

Unter der Route „/swagger“ ist eine GUI zu finden, in der alle Methoden aufgelistet werden und die sogar gewisse Funktionalitäten hat, den Web Service durchzutesten. Dieses Interface dürfte allerdings noch in einer sehr frühen Entwicklungsphase sein, weil bei unserem Web Service der Browsertab einfach einfriert, wenn man auf diese Seite geht (Unter Chrome).

Controller mit mehreren Methoden mit der gleichen HttpMethod (Get, Put, …)

Da WebApi 2 das Überladen von Funktionen unterstützt, Swagger aber (noch) nicht, kommt es hierbei zu Problemen.

Es gibt dafür zwei uns bekannte Lösungen:

  1. Alle Methoden einzigartig benennen (z.B. GetRecipeById, GetAllRecipes, ..) und auf Überladung verzichten.
  2. Für jede überladene Methode eine eigene Route konfigurieren (über die Annotation [Route(„…“)], z.B. [Route(„id“], [Route(„all“)], wobei in diesem Fall ein RoutePrefix für den Controller definiert werden sollte). Mehr Infos: Attribute Routing

Rekursive Verweise

Da dieser Punkt sowieso bei der Verwendung von JSON auch beachtet werden muss, gehe ich hier nicht näher darauf ein. Grundsätzlich müssen hierfür sogenannte Data Transfer Objects (kurz DTOs) erstellt werden. Nähere Informationen finden Sie auf: DTOs erstellen.

Interne Klassen werden auch von Swashbuckle erfasst

Man möchte natürlich nur die notwendigen Klassen (DTOs, Controller) und Web-Methoden in der Swagger Spezifikation haben und alle anderen ignorieren.

Gerade bei der Verwendung des Entity Frameworks ist das sehr lästig, wenn beim Client alle Model-Klassen zu finden sind, die im Client aber absolut nichts zu suchen haben.

Grundsätzlich erfasst Swashbuckle nur Methoden und Klassen, die als public deklariert sind. Um die Visibility nun nicht zu sehr einschränken zu müssen, kann man statt public das Keyword internal verwenden. Am besten macht man das im Designer durch Öffnen des .edmx-Files, um zu verhindern, dass die protection modifier bei jedem Update wieder auf public geändert werden.

Dazu klickt man zuerst auf den leeren Bereich neben den Tabellen und ändert unter den Properties das Feld „Entity Container Access“ auf „Internal“ um.

unbenannt

Anschließend muss man noch auf jeden Tabellentitel klicken und dort das Feld „Access“ ebenfalls auf „Internal“ umändern.

unbenannt2

Danach kann es noch passieren, dass ein paar Build-Errors entstehen, hier muss man einfach alle public-Schlüsselwörter ebenfalls auf internal umändern. Deshalb ist es wichtig, diesen Schritt gleich am Anfang vorzunehmen.

Wenn dennoch Konflikte entstehen, weil man das Datenbank-Modell beispielsweise in einem anderen Projekt innerhalb der selben Solution abgekapselt hat, kann man in der Datei „AssemblyInfo.cs“ in den Properties einfach die Zeile „[assembly: InternalsVisibleTo(„*WebServiceProjektName*“)]“ hinzufügen.

Namenskonflikt von Web Methoden und Tabellennamen

Dieses Problem sollte sich bei der Erstellung von DTOs vermeiden lassen, passiert dennoch ein Fehler bei der Client-Generierung (das Swagger-File selbst dürfte korrekt sein, aber im Visual Studio kommt dann der Fehler beim Importieren), dann hilft es, den ControllerKlassen einen anderen Namen zu vergeben, als den DTO-Objekten.

Unterstriche in Methodennamen

Wer darauf Wert legt, den vollständigen Methodennamen vom Web Service auch im Client zu haben, der sollte auf Unterstriche verzichen, da alles nach dem Unterstrich einfach ignoriert wird.

Verwendung des generierten Clients

Nun zur Anwendung des Clients. Hierzu gibt es nicht mehr allzu viel zu sagen, denn die meisten Probleme treten bei der Generierung des Swagger Files auf.

Als Erstes muss man den Client instanziieren, dieser hat den Namen *Namespace*Client, wobei man den Namespace beim Importieren des Clients angibt. Hier ein Beispiel aus einer Xamarin App:

unbenannt3

Über diesen Client kann nun auf alle Web Methoden zugegriffen werden, hierbei ist allerdings zu beachten die Extension-Methods zu verwenden und nicht die Async-Methoden, also kurz gesagt: Die Methode mit dem Namen selben Namen der Web Methode im Controller ist die Richtige, die Methoden, die auf Async enden ist die „kompliziertere“ und muss nur verwendet werden, wenn man die async Funktionalität auch serverseitig implementiert hat bzw. im Client braucht.

Zusammenfassung

Abschließend lässt sich sagen, dass sich der Overhead jedenfalls auszahlt, und zwar noch viel mehr bei größeren Web Services. Swagger ist mittlerweile die Standard-Methode für REST und lässt sich gut vergleichen mit WSDL für SOAP Services.