Objektserialisierung in ASP.NET Core Web APIs

Objektserialisierung in ASP.NET Core Web APIs
Page content

In diesem Artikel sehen wir uns die Serialisierung von Objekten in ASP.NET Core Projekten genauer an. Zudem gibt es noch ein paar Tipps zur Benamung der Properties mit Attributen.

Beispielprojekt

Die Serialisierung möchte ich anhand folgendes Beispielcontroller vorstellen:

// Datenklasse
public class DataModel {
  public string StringValue { get; set; }
  public int IntegerValue { get; set; }
}

// ApiController
[ApiController]
[Route("api/[controller]")]
public class ExampleApiController : Controller {
  public DataModel Index() {
    return new DataModel() {
      StringValue = "Hello world!",
      IntegerValue = 30
    };
  }
}

Die Datenklasse beinhaltet zwei Properties: eine Zeichenkette und eine Ganzzahl. Der Controller gibt beispielhaft ein statisches Objekt zurück.

Die Route wird standardmäßig aus dem Namen des Controllers abgeleitet. In diesem Beispiel ist der Endpunkt über http://localhost:50000/api/exampleapi erreichbar. In der Dokumentation von Microsoft findet ihr weitere Details zum Routing .

Die Rückgabetypen

Die Formate XML oder JSON werden verwendet, um ein Objekt einer REST-Abfrage an den Client zurückliefern. Das ASP-Projekt ist so „klug“, dass abhängig vom Accept-Header das Ergebnis als JSON oder XML-Objekt zurückgeliefert wird. Das Ergebnis sieht folgendermaßen aus:

// JSON-Objekt
{
  "stringValue": "Hello world!",
  "integerValue": 30
}
<!-- XML-Objekt -->
<DataModel
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <StringValue>Hello world!</StringValue>
  <IntegerValue>30</IntegerValue>
</DataModel>

Unterschiede der Aufbereitung

Grundsätzlich wird der Name des Properties 1:1 verwendet und für den jeweiligen Rückgabetypen umgewandelt. Bei XML wird der Name in CamelCase angegeben. Das JSON-Äquivalent beginnt mit einem Kleinbuchstaben.

Beim Umbenennen der Properties sollte man daher aufpassen, ob diese nur von der eigenen Anwendung verwendet werden oder zu einer öffentlichen API gehören. Die Aufrufe oder Dokumentationen müssen möglicherweise angepasst werden.

Namen ändern via Attribut

Die Serialisierung kann mit Hilfe von Attributen konfiguriert werden. Mit Hilfe des Attributes JsonProperty können wir für die JSON-Serialisierung einen anderen Namen angeben:

public class DataModel {

  [JsonProperty("Prop_String")]
  public string StringValue { get; set; }

  [JsonProperty("Prop_Int")]
  public int IntegerValue { get; set; }

}

Die Properties heißen nun Prop_Stringund Prop_Int. Eine Abfrage liefert uns nun folgende Ergebnisse:

// JSON-Objekt
{
  "Prop_String": "Hello world!",
  "Prop_Int": 30
}
<!-- XML-Objekt -->
<DataModel
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <StringValue>Hello world!</StringValue>
  <IntegerValue>30</IntegerValue>
</DataModel>

Die Ausgabe für JSON hat sich geändert. Allerdings ist das XML-Objekt noch im „alten“ Layout. Damit die Werte nur einmalig gesetzt werden müssen, gibt es DataContracts und DataMember .

Die Datenklasse sieht nun folgendermaßen aus:

[DataContract()]
public class DataModel {

  [DataMember(Name = "Prop_String")]
  public string StringValue { get; set; }

  [DataMember(Name = "Prop_Int")]
  public int IntegerValue { get; set; }

}

Durch die Attribute DataContract und DataMember wurden „allgemein gültige“ Regeln für die Serialisierung angegeben. Dies wirkt sich auf die Abfragen der REST-Schnittstelle aus, wie man in nachfolgenden Ergebnissen sehen kann:

// JSON-Objekt
{
  "Prop_String": "Hello world!",
  "Prop_Int": 30
}
<!-- XML-Objekt -->
<DataModel
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Prop_Int>30</Prop_Int>
  <Prop_String>Hello world!</Prop_String>
</DataModel>

Konfiguration anpassen

Falls die automatische Serialisierung zu JSON oder XML nicht funktioniert, müsst ihr den Aufruf der Startfunktionen anpassen:

public void ConfigureServices(IServiceCollection services) {
  services.AddMvc(config => {
    config.RespectBrowserAcceptHeader = true;
  })
  .AddXmlDataContractSerializerFormatters()
  .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

Fazit

Wir haben gesehen, dass ASP.Net Core grundlegend Objekte serialisieren kann. Mit Hilfe von DataContract und DataMember können wir die Namen selbst festlegen. Unter Umständen muss die Serialisierung in den Startoptionen geändert werden.

Wie ist eure Erfahrung mit Serialisierung und Konfiguration der Namen?


Bildnachweis: Pixabay.com