Details der Serialisierung sowie den zu verwendenden JSON- bzw. XML-Serializer kann der Entwickler über die globale Konfiguration anpassen – als Ort für diese Anpassungen, bietet sich, wie so häufig, die Methode WebApiConfig.Register an. Das nachfolgende Listing demonstriert einige Einstellungsmöglichkeiten für jenen Serializer, der standardmäßig vom JsonFormatter herangezogen wird.
UseDataContractJsonSerializer definiert, ob der aus WCF bekannte DataContractJsonSerializer zum Einsatz kommen soll. Obwohl diese Einstellung aus Gründen der Kompatibilität zu WCF-basierten Systemen sinnvoll erscheint, sollte sie gerade bei Neuentwicklungen auf ihren Standardwert false belassen werden. Dies hat zur Folge, dass ASP.NET Web API auf den mächtigeren Serializer aus dem freien Projekt JSON.Net, welches mit der Web API ausgeliefert wird, zurückgreift.
DateTimeZoneHandling legt es fest, welche Zeitzone beim Übertragen von Datumswerten zu verwenden ist. Die im betrachteten Fall verwendete Option DateTimeZoneHandling.Local bewirkt, dass ASP.NET Web API Uhrzeiten als lokale Uhrzeiten (unter Berücksichtigung der Einstellungen am Server) inkl. Zeitzonenoffset überträgt. Alternativen sind DateTimeZoneHandling.Utc sowie DateTimeZoneHandling.RoundtripKind. Erstere konvertiert Uhrzeiten immer nach UTC; letztere erhält die Zeitzone, die der Client übersendet hat.
Eine der wohl wichtigsten Eigenschaften, welche den Umgang mit Datumswerten beeinflusst, ist DateFormatHandling. Sie legt fest, wie Datumswerte in JSON dargestellt werden sollen und adressiert somit die Problemstellung, dass die JSON-Spezifikation keine Aussage darüber macht. Die Option IsoDateFormat, welche auch den Standardwert darstellt, bewirkt, dass ASP.NET Web API Datumswerte, wie auch in XML üblich, nach ISO 8601 darstellt. Ein Beispiel dafür ist 2013-01-20T21:00:00+01:00. Das T trennt dabei den Datumsteil von der Uhrzeit und am Ende wird ein eventuelles Zeitzonenoffset angehängt. Bei +01:00 handelt es sich um das Offset für die mitteleuropäische Zeit (MEZ), welche von der Standardzeit (UTC) um eine Stunde abweicht. Eine Alternative dazu stellt die Option MicrosoftDateFormat dar. Sie legt fest, dass jene Darstellung für Datumswerte, welche Microsoft-Frameworks im Zuge der JSON-Serialisierung in der Vergangenheit verwendet haben, heranzuziehen ist. Zugunsten der allgemein akzeptierten ISO-Repräsentation sollte der Entwickler diese Einstellung nur nutzen, wenn das entwickelte System zu solchen Systemen kompatibel sein muss.
Eine weitere Eigenschaft, die in Listing 35 verwendet wird, ist Formatting. Wird sie auf Formatting.Indented gesetzt, kommen – zur besseren Lesbarkeit – Zeilenschaltungen und Einrückungen zum Einsatz. Ansonsten verzichtet der JSON-Serializer darauf.
var jf = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
jf.UseDataContractJsonSerializer = false;
jf.SerializerSettings.DateTimeZoneHandling =
Newtonsoft.Json.DateTimeZoneHandling.Local;
jf.SerializerSettings.DateFormatHandling =
Newtonsoft.Json.DateFormatHandling.IsoDateFormat;
// jf.SerializerSettings.DateFormatHandling =
// Newtonsoft.Json.DateFormatHandling.MicrosoftDateFormat;
jf.SerializerSettings.Formatting = Newtonsoft.Json.Formatting.Indented;