Wandle C#-Klassen in JSON um!

Füge C#-Code (class·record) ein und erhalte ein Beispiel-JSON! Unterstützt System.Text.Json [JsonPropertyName], Newtonsoft.Json [JsonProperty]. Praktisch für API-Dokumentation und Test-Request-Bodys (mock request body).
C#
Ergebnis
 

Wandle C#-Klassen in JSON um!

Füge C#-Modelle aus class, record oder struct ein und erhalte ein Beispiel-JSON-Dokument nach den Regeln von System.Text.Json und Newtonsoft.Json. Du wählst zwischen der camelCase-Namensrichtlinie, die ASP.NET Core standardmäßig verwendet, und den Property-Namen wie geschrieben; mit [JsonPropertyName] oder [JsonProperty] festgelegte Namen haben immer Vorrang.

Damit gibst du aus Request-/Response-Modellen einer Web API ein Beispiel an das Frontend oder einen externen Partner weiter, füllst Swagger-Beispiele (Swashbuckle) oder bereitest Bodies für Integrationstests mit HttpClient vor.

So funktioniert es

  1. Füge den Quelltext des Modells ein. using, namespace, Konstruktoren und Methoden dürfen stehen bleiben.
  2. Wähle eine Namensrichtlinie: camelCase (ASP.NET Core-Standard) für normale Web-API-Projekte oder Eigenschaftsnamen unverändert, wenn du PropertyNamingPolicy = null setzt oder dich auf die Newtonsoft-Standards verlässt.
  3. Steht Wurzeltyp auf Automatisch, wird der erste Typ, auf den kein anderes Modell verweist, zur Wurzel; bei Bedarf wählst du ihn aus der Liste.
  4. Kopiere das JSON in ein Swagger-Beispiel, eine .http-Datei oder einen xUnit-Request-Body. Deine Optionen werden in der URL gespeichert.

Beispiel

Eingabe (C#)
public class InventoryItem
{
    public Guid Id { get; set; }
    public string SKU { get; set; } = "";
    [JsonPropertyName("stock_qty")]
    public int StockQuantity { get; set; }
    public StockState State { get; set; } = StockState.InStock;
    public DateTimeOffset UpdatedAt { get; set; }
    public List<string> Barcodes { get; set; } = new();
    [JsonIgnore]
    public string WarehouseNote { get; set; } = "";
    private int _version;
}

public enum StockState { InStock, LowStock, OutOfStock }
Ausgabe (JSON · camelCase)
{
  "id": "00000000-0000-0000-0000-000000000000",
  "sku": "",
  "stock_qty": 0,
  "state": 0,
  "updatedAt": "1970-01-01T00:00:00+00:00",
  "barcodes": [
    ""
  ]
}

Unter der camelCase-Richtlinie wird ein durchgehend großgeschriebener Name wie SKU zu sku, passend zu JsonNamingPolicy.CamelCase von System.Text.Json, während [JsonPropertyName("stock_qty")] seinen Namen unabhängig von der Richtlinie behält. WarehouseNote ([JsonIgnore]) und das private-Feld _version fehlen. Das Enum State hat keinen String-Converter und zeigt daher 0, den numerischen Wert seines Initialisierers StockState.InStock.

Unterstützte Funktionen

  • Attribute zum Umbenennen: [JsonPropertyName] von System.Text.Json, [JsonProperty] von Newtonsoft und [DataMember(Name = ...)].
  • Nur public Properties und Felder werden aufgenommen, dazu nicht-öffentliche Member mit [JsonInclude]. static, const, [JsonIgnore] und [IgnoreDataMember] werden ausgeschlossen; bedingte Ignores wie Condition = WhenWritingNull bleiben drin.
  • Positional Records (record Customer(long Id, string Name)) und Ziele wie [property: JsonPropertyName(...)] werden unterstützt.
  • Berechnete Properties mit Expression Body (=> ...) werden aufgenommen, so wie System.Text.Json sie serialisieren würde.
  • Enums werden als Zahlen geschrieben, wie es System.Text.Json und Newtonsoft standardmäßig tun (inklusive expliziter Werte wie = 10). Mit [JsonConverter(typeof(JsonStringEnumConverter))] (oder StringEnumConverter von Newtonsoft) am Enum oder an der Property bzw. mit [JsonStringEnumMemberName] / [EnumMember(Value = ...)] an den Membern wird stattdessen der Name als String verwendet.
  • Datum und IDs: DateTime → 1970-01-01T00:00:00, DateTimeOffset → 1970-01-01T00:00:00+00:00, DateOnly → 1970-01-01, TimeOnly/TimeSpan → 00:00:00, Guid → GUID aus lauter Nullen.
  • int?/Nullable<T> verwenden den inneren Typ, List<T>/IEnumerable<T>/Arrays bekommen ein Element, Dictionary<int, V> verwendet einen Key "0", und object, JsonElement und JObject werden zu null.
  • Literale Initialisierer (= 1.5, = "KRW") dienen als Beispielwerte.

Anwendungsfälle

Swashbuckle-Beispiele an echte Antworten angleichen

DTOs, die [JsonPropertyName] mit der Standardbenennung mischen, machen die generierten Beispiele in Swagger UI leicht missverständlich. Verwende diese Ausgabe in einem ISchemaFilter oder einem XML-Kommentar <example>, damit Doku und Antwort dieselben Keys haben.

Umstieg von Newtonsoft auf System.Text.Json

Schalte die Namensrichtlinie beim selben Modell hin und her, um vorab zu sehen, wie sich die Schreibweise der Keys nach der Migration ändert.

Den Vertrag zwischen Unity/MAUI-Client und Server prüfen

Pflegen Client und Server getrennte Kopien eines Modells, erzeuge auf beiden Seiten JSON und vergleiche es, um abweichende Key-Namen schnell zu finden.

Hinweise und Einschränkungen

  • Ein global mit AddJsonOptions in Program.cs registrierter JsonStringEnumConverter ist im Modellcode nicht sichtbar, daher erscheinen Enums weiterhin als Zahlen. Um Namen zu sehen, ergänze vor dem Einfügen [JsonConverter(typeof(JsonStringEnumConverter))] an der Enum-Deklaration.
  • Nullable Referenztypen wie string? bekommen ein typisiertes Beispiel, nicht null.
  • Eigene [JsonConverter]-Attribute außer dem Enum-String-Converter, DefaultIgnoreCondition in JsonSerializerOptions und snake_case-Richtlinien (JsonNamingPolicy.SnakeCaseLower) werden nicht angewendet.
  • Polymorphie über [JsonPolymorphic]/[JsonDerivedType] wird nicht unterstützt; erzeugt wird nur der deklarierte Basistyp.

Häufige Fragen

Wann verwende ich welche Option der Namensrichtlinie?

ASP.NET Core Web API verwendet JsonSerializerDefaults.Web, also camelCase. Eine Konsolen-App, die JsonSerializer.Serialize ohne Optionen aufruft, oder Newtonsoft.Json mit Standardeinstellungen behält die Property-Namen; wähle dort Eigenschaftsnamen unverändert.

Warum taucht eine berechnete Property wie public string FullName => ... auf?

Sowohl System.Text.Json als auch Newtonsoft.Json serialisieren öffentliche Properties mit Getter, berechnete Properties landen also ebenfalls in Antworten. Ergänze [JsonIgnore], wenn sie nicht ausgegeben werden sollen.

[JsonPropertyName] am Positionsparameter eines Records benennt den Key zur Laufzeit nicht um.

Ohne Ziel wendet der Compiler das Attribut nur auf den Konstruktorparameter an. Dieses Tool erkennt beide Formen, um die serialisierte Property aber zuverlässig umzubenennen, schreibe [property: JsonPropertyName("...")].

Warum fehlt bei DateTime-Werten das Z?

Ein DateTime mit DateTimeKind.Unspecified wird ohne Offset serialisiert. Brauchst du einen expliziten UTC-Offset, erzeugt DateTimeOffset die Form +00:00.