Nextended.CodeGen
📚 Vollständige API-Referenz — jeder öffentliche Typ und Member, erzeugt aus der kompilierten Assembly.
Roslyn-Source-Generator — DTOs und Interfaces aus Ihren Entities, stark typisierte Klassen aus JSON/XML, Lookup-Tabellen aus Excel, Dokumentation aus Quelldateien und TypeScript-Deklarationen Ihrer Contracts.
Das Mapping zwischen Entity und DTO wird wahlweise als Extension-Methoden (ToDto()/ToEntity()) oder als partieller Mapperly-Mapper generiert ([AutoGenerateDto(MappingStrategy = DtoMappingStrategy.Mapperly)] oder DefaultMappingSettings.Strategy in der Konfiguration). Methoden, die Sie im eigenen Teil der partiellen Mapper-Klasse deklarieren, überschreiben die generierten. Mapperly braucht die Dateien auf der Platte, also OutputPath und MappingOutputPath setzen und Riok.Mapperly referenzieren.
Installation
dotnet add package Nextended.CodeGenWas das Paket macht
Roslyn-Source-Generator — DTOs und Interfaces aus Ihren Entities, stark typisierte Klassen aus JSON/XML, Lookup-Tabellen aus Excel, Dokumentation aus Quelldateien und TypeScript-Deklarationen Ihrer Contracts.
Die vollständige Referenz — alle Typen, Builder, Optionen und ausführlich kommentierte Codebeispiele — steht auf der englischen Seite:
📖 Nextended.CodeGen — vollständige Referenz (englisch) Ebenso ausführlich und ebenfalls englisch ist das Paket-README:
Fluent-Konfiguration (empfohlen)
Der empfohlene Weg, die Generatoren zu konfigurieren. Statt Attributen an den Entities und einer codegen.json beschreiben eine oder mehrere Konfigurationsklassen, was generiert wird — wie ein ResponseFilter<T> oder ein FluentValidation-Validator. Attribute und codegen.json funktionieren unverändert weiter; die Fluent-Konfiguration verfeinert sie, und mit ihr wird codegen.json optional.
using Nextended.Core.CodeGen;
using Nextended.Core.Enums;
// die DTOs einer Entity
public sealed class ProductDtoConfig : DtoConfig<Product>
{
public ProductDtoConfig()
{
Ignore(x => x.InternalNote);
Property(x => x.Sku).PropertyName("ArticleNumber");
MappingStrategy(DtoMappingStrategy.Mapperly);
// ein zweites DTO derselben Entity (eine View)
View("ProductRow", v => v
.Ignore(x => x.Category, x => x.Tags)
.BaseMembersFirst()
.Order(x => x.Name, x => x.Price)
.ToDtoMethodName("ToRow"));
}
}
// das ganze Projekt: was in der codegen.json stünde, die zu generierenden Typen, Regeln für Gruppen von Typen
public sealed class AppCodeGen : CodeGenConfig
{
public AppCodeGen()
{
Defaults(d => d.Namespace("MyApp.Contracts").OutputPath("./Generated/Dtos/").InitializeCollections());
Dto<Entity>(e => e.Ignore(x => x.TenantId)); // erreicht jedes DTO und jede View jeder Entity
Dto<Category>(); // ohne [AutoGenerateDto]
Dto(typeof(Page<>), p => p.Suffix("Model")); // offene generische Typen über typeof
IgnoreType<LegacyImport>();
ForNamespace("MyApp.Domain.Codes", n => n.Namespace("MyApp.Contracts.Codes"));
ForAssembly("MyApp.Admin", a => a.Defaults(d => d.Namespace("MyApp.Admin.Contracts")));
}
}| Gefunden | automatisch: jede Klasse im Projekt, die von CodeGenConfig oder DtoConfig<T> erbt (beliebiger Namespace, auch partial) |
| Gelesen, nicht ausgeführt | der Generator analysiert den Konstruktor: erlaubt sind Aufrufe der Nextended.Core.CodeGen-API, Konstanten (auch const, nameof, Enum-Werte, konstante Interpolationen), typeof, Member-Selektoren x => x.Member und verschachtelte Lambdas. Alles andere (Variablen, berechnete Werte, if, Schleifen, x => x.A.B) ist ein Fehler NCG020 an genau dieser Stelle — nie still ignoriert |
| Namen | jede Einstellung heißt genau wie die Attribut- bzw. json-Eigenschaft, die sie spiegelt (Namespace, Suffix, PreClassString, PropertyName, InitializeCollections, ...); bool-Einstellungen nehmen ein optionales true |
| Zusätzlich | Ignore/Include (hebt [IgnoreOnGeneration] und PropertiesToIgnore auf), Property, View, Order, OrderLast, BaseMembersFirst, Emit (Datei pro DTO aus einer Vorlage mit {Dto}, {DtoNamespace}, {Source}, ...), ViewDefaults, Facets/Facet, ExcelGeneration, StructureGeneration |
| Reihenfolge | Order(x => x.Id) stellt Member an den Anfang, OrderLast(x => x.CreationTime) ans Ende (jeweils in der angegebenen Reihenfolge, Quell-Membernamen); BaseMembersFirst() sortiert vorher geerbte Member nach vorn. Die Klasse listet die Member in dieser Reihenfolge, ein flaches DTO (View, DeepProperties) wird so serialisiert — [JsonPropertyOrder]-Listen entfallen. Alles andere bleibt in Deklarationsreihenfolge, in jedem Build gleich: ein Typ aus mehreren Dateien (partial) listet seine Member nach Datei (die Dateien eines Ordners vor seinen Unterordnern, nach Name ohne Groß-/Kleinschreibung, wie der Standard-Compile-Glob), dann nach Position; die Reihenfolge, in der Visual Studio, die Kommandozeile oder ein inkrementeller Build die Dateien übergibt, spielt keine Rolle mehr (vor 10.1.63 konnte ein Member einer anderen partial-Datei zwischen Builds vom Ende an den Anfang springen). Gilt auch für TypeScript und die Mapper |
Property(..., p => ...) | Property(x => x.A, p => p.Name("B")) wie Property(x => x.A).Name("B"), gibt aber den DTO-Builder zurück, die Kette geht weiter: .Property(x => x.A, p => ...).Ignore(x => x.C); auch mit Namen Property("A", p => ...) |
| Views und Defaults | ViewDefaults(v => v.Namespace("X").OutputPath("Views/").Ignore("DateCreatedUtc")): Einstellungen und Member-Regeln (nach Namen) für jede View (Attribut- und Fluent-Views, Standard-DTOs nicht). Was die View selbst setzt, gewinnt: ihr View(...), die Eigenschaften, die ihr [AutoGenerateDto] setzt, Member-Regeln an der View oder ihrem Typ. ViewDefaults definiert keine Views (NCG020). Views auch für offene Generics: Dto(typeof(Box<>), b => b.View("BoxRef", v => v.Ignore("Label"))) oder Dto<Box<int>>(b => b.View(...)) mit Selektoren |
| Ignorieren in Views | Ignore(...) einer View ergänzt das Default-PropertiesToIgnore (json/Fluent), PropertiesToIgnore am [AutoGenerateDto] einer View ersetzt es (wie an jedem Attribut). Beim Umstieg von Attributen also nur auflisten, was die View über die Defaults hinaus weglässt |
| Facets | Facets<Shipment>(f => f.Facet(x => x.Eta, o => o.Label("ETA").Type(FacetType.DateRange))) (oder Facet(...) in Dto<T>/DtoConfig<T>) wirkt wie [ProvideFacet] an der Property, ohne den Typ anzufassen; Einstellungen heißen wie die Eigenschaften des Attributs (ValueType<Guid>() zusätzlich). Der Generator schreibt einen Modul-Initialisierer (NextendedFacetRegistrations.g.cs, nur in der Kompilierung), der FacetRegistry.Register(...) aufruft; FacetBuilder und FacetRegistry.GetFacets(type) führen Registrierungen und Attribute zusammen: am Attribut überschreiben die Fluent-Werte nur, was sie setzen; eine Registrierung am Basistyp erreicht abgeleitete Typen; ein generischer Typ gilt für jede Konstruktion. FacetRegistry führt die Modul-Initialisierer der Assemblies des Typs vor dem Lesen aus (Konfiguration in der Assembly des Typs oder einer Basis). Code, der [ProvideFacet] selbst liest, sollte FacetRegistry.GetFacets verwenden. Braucht .NET 5+ und ein Nextended.Core mit FacetRegistry, sonst NCG027 |
| Vorrang | codegen.json → Fluent-Defaults (bleiben Defaults) → Attribute → ForNamespace → Dto<T>/DtoConfig<T>. Mehrere Klassen werden nach vollem Typnamen zusammengeführt; widersprüchliche Werte melden NCG022 |
| Member-Regeln | gelten für das Standard-DTO und die Views des Typs und für die DTOs abgeleiteter Typen. Die spezifischere Regel gewinnt (Suche: View → Typ → Basistypen → Namespace-Regeln): Dto<Entity>(e => e.Ignore(x => x.TenantId)) entfernt TenantId überall, Dto<Currency>(c => c.Include(x => x.TenantId)) holt es für CurrencyDto (und dessen Views) zurück, ebenso v.Include(...) in einer View. Im Unterschied dazu bleibt PropertiesToIgnore des Attributs wie bisher pro DTO (an der Basis wirkt es nur aufs Basis-DTO) — aus Gründen der Abwärtskompatibilität. Eine Regel am abgeleiteten Typ für einen geerbten Member, den das Basis-DTO trägt, wirkt nur in dessen Views (NCG023) |
Dto<T> | verfeinert nur: alles, was T schon bekommt (eigenes Attribut, Attribut der Basis über AutoGenerateDerived, json-Defaults, Namespace-Regeln), bleibt; überschrieben wird nur, was der Aufruf setzt. Dto<T>() an einem Typ ohne jedes DTO nimmt ihn mit den Defaults auf |
| Kurzformen | Name("B") = PropertyName, Attribute("[X]") / Attributes("[X]", "[Y]") = PreClassString, KeepAttributes() = KeepAttributesOnGeneratedClass; die langen Namen bleiben |
| Typisierte Typ-Settings | BaseType<IEntityDto<Guid>>() bzw. BaseType(typeof(IEntityDto<Guid>)) statt BaseType("Volo.Abp.Application.Dtos.IEntityDto<Guid>") → global::Volo.Abp.Application.Dtos.IEntityDto<global::System.Guid>; Interface<IA>()/Interface(typeof(IA)) fügen zu Interfaces hinzu (einmal je Typ; Interfaces("...") ersetzt wie bisher); Excel PropertyTypeOverride<decimal>("Total")/PropertyTypeOverride("Total", typeof(decimal)); TypesToIgnore hat IgnoreType<T>() schon. Gilt in Defaults, Dto<T>, DtoConfig<T>, Dto(typeof), ForNamespace, ViewDefaults, Views. Offene Generics (typeof(EntityDto<>)) mit ihren Typparameter-Namen (EntityDto<TKey>). String-Formen unverändert; BaseType(null) braucht jetzt einen Cast BaseType((string?)null) |
| Typisierte Attribute | Attribute<TAttribute>(args) schreibt ein Attribut aus seinem Typ statt aus einem String: Property(x => x.LoadingPort).Attribute<FacetDisplayAttribute>(Displays.Port) → [global::My.Ui.FacetDisplay("port")], Property(x => x.OriginCountry).Attribute<CountryCodeAttribute>() → [global::My.Ui.CountryCode]. Voller Name aus dem Symbol (global::, Namespace, umgebende Typen, Suffix Attribute entfällt wie bei übernommenen Attributen; generische Attribute [global::Ns.Typed<int>]). Argumente als C#-Literale: Strings/char escaped (auch const, nameof, konstante Interpolationen), long/uint/ulong/float/double mit Suffix (1L, 1.5F, 2.5D), byte/short mit Cast ((byte)7), Enums als global::Ns.E.Member (ohne Member ((global::Ns.E)5)), typeof(X) als typeof(global::Ns.X), Arrays als new int[] { 1, 2 }. Benannte Argumente im Lambda: Attribute<MarkAttribute>(a => { a.Label = "x"; a.Tone = Tone.Loud; }, 1) → [global::Lib.Mark(1, Label = "x", Tone = global::Lib.Tone.Loud)]. Nicht Konstantes (static readonly, Methodenaufrufe) meldet NCG020, die Anweisung entfällt; gegen die Konstruktoren des Attributs wird nicht geprüft (falsche Argumente = Compilerfehler in der generierten Datei). Typisierte Attribute addieren sich in Aufrufreihenfolge (.Attribute<A>().Attribute<B>() schreibt beide, ein doppeltes nur einmal); Attribute(string), Attributes(...) und PreClassString(...) bleiben wie bisher (setzen den Text, der letzte gewinnt): String zuerst und danach typisierte → beides, String nach typisierten → nur der String. Überall, wo es Attribute(string) gibt |
Ohne codegen.json | relative Pfade beziehen sich auf das Projektverzeichnis |
| Diagnosen | NCG020 nicht lesbar · NCG021 unbekannter Member · NCG022 Konflikt zwischen Klassen · NCG023 Regel ohne Wirkung aufs Standard-DTO · NCG024 Emit nicht schreibbar · NCG025 Typ kann kein DTO haben · NCG026 Aufruf unbekannt (Nextended.CodeGen aktualisieren) · NCG027 Facets nicht registrierbar (vor .NET 5 oder Nextended.Core ohne FacetRegistry) |
Voraussetzung: ein Nextended.Core mit Nextended.Core.CodeGen und ein Nextended.CodeGen, der es liest. Ausführlich mit allen Tabellen auf der englischen Referenz; lauffähig im CodeGenFluentSample (kein Attribut, keine json); Entwurf und Begründung: Fluent configuration — design.
TypeScript-Generierung
TypeScript-Deklarationen Ihrer C#-Contracts — DTOs, Enums, OData-Zeilen, SignalR-Payloads —, die dem folgen, was der JSON-Serializer des Servers wirklich schreibt. Gedacht für die Typen, die OpenAPI nicht beschreibt, und für Frontends mit handgeschriebenen src/types/*.ts.
Standardmäßig aus. Ohne eine TypeScript-Generierung mit OutputPath passiert nichts; die Attribute allein bewirken nichts, ein fehlender Abschnitt bricht keinen Build, und TypeScript wird nie in die Kompilierung aufgenommen (es wird auf die Platte geschrieben).
public sealed class AppCodeGen : CodeGenConfig
{
public AppCodeGen()
{
Typescript(t => t
.OutputPath("../frontend/src/types/generated") // relativ zum Projekt (bzw. zur json-Datei)
.EnumValues(TypescriptEnumValues.Number) // Enums als Zahlen (Standard; String = Namen)
.IncludeNamespaces("MyApp.Contracts")
.RootNamespace("MyApp.Contracts") // fällt aus den Ordnern weg
.TypeMap(typeof(PagedResultDto<>), "PagedResult from '../abp'")
.Type<ShipmentDto>(s => s.Name("ApiShipment").Ignore(x => x.InternalNote)));
}
}Dasselbe in codegen.json (ein Eintrag der Liste Typescript, Einstellungen heißen wie die Fluent-Methoden):
{
"Typescript": [
{
"OutputPath": "../frontend/src/types/generated",
"EnumValues": "Number",
"IncludeNamespaces": [ "MyApp.Contracts" ],
"RootNamespace": "MyApp.Contracts",
"TypeMap": { "Volo.Abp.Application.Dtos.PagedResultDto<T>": "PagedResult from '../abp'" },
"Types": { "MyApp.Contracts.ShipmentDto": { "Name": "ApiShipment", "Members": { "InternalNote": { "Ignore": true } } } }
}
]
}Attribute an den Typen: [GenerateTypescript(Name = "...")] wählt einen Typ aus (in jeder Generierung), [TypescriptIgnore] lässt einen Typ oder Member weg, [TypescriptProperty(Name = ..., Type = ..., Optional = true)] stellt einen Member ein. Vorrang wie überall: json → Attribute → Fluent (Type<T>(...) in der Generierung, DtoConfig<T>.Typescript(...) für alle Generierungen und die DTOs von T).
- Auswahl: echte kompilierte Typen (handgeschriebene DTOs, alle Teile partieller Klassen, DTOs auf der Platte) über
IncludeNamespaces(auch in referenzierten Assemblies),IncludeTypes(*-Muster),IncludeBaseTypes/IncludeDerivedFrom,[GenerateTypescript];FromGeneratedDtosnimmt die DTOs dazu, die der Generator im selben Build erzeugt (mit Umbenennungen, Views, Ignores).Exclude*und[TypescriptIgnore]gewinnen. Verwendete Typen folgen (IncludeReferencedTypes). - Serializer: camelCase (Option
PropertyNaming),[JsonPropertyName],[JsonIgnore](WhenWritingNull→ optional); Enums immer mit expliziten Werten, als Zahlen (EnumValuesNumber, Standard) oder Namen (String),[JsonConverter(JsonStringEnumConverter)]am Typ oder an der Property gewinnt; Stilenumoderconst-Objekt + Union-Typ (EnumStyle, passt zuerasableSyntaxOnly);[Flags]mit Zahlen; Dictionary mit Enum-Schlüsseln →Partial<Record<keyof typeof E, V>>. Es gibt keine Presets für Server: ABP und ASP.NET Core ohne Enum-Converter brauchen nur die Standardwerte, ein Server mit global registriertemJsonStringEnumConverterEnumValues(TypescriptEnumValues.String). - Abbildung: alle Zahlen →
number(long/decimaloptionalstring),byte[]→string, Guid/Datum/Zeit →string(optional Aliase ausscalars.ts),object/JsonElement→unknown, jedes Dictionary →Record,KeyValuePair→{ key; value }, Collections →T[],TypeMapfür eigene Abbildungen. - Nullbarkeit und Vererbung:
| nullaus NRT/Nullable<T>,?nur per Option/Attribut;interface X extends Baseohne Wiederholung, Generics mit Constraints,[JsonPolymorphic]/[JsonDerivedType]→ diskriminierte Union (XBase+ UnionX). - Optionale Member mit Standardwert:
OptionalDefaultValues(Generierung oder je Typ, FluentOptionalDefaultValues()) macht Member mit einem Standardwert optional: Initialisierer außernull/default(= 10,= "",= []), Standardwert eines Record-Parameters oder[DefaultValue].required,[Required]und[JsonRequired]bleiben Pflicht,.Optional(false)ebenso. Gedacht für Request-DTOs; enthält eine Generierung auch Antworten, je Typ setzen. - Member-Filter per Attribut:
IncludeMembersWithAttributes(Generierung oder je Typ; FluentIncludeMembersWithAttribute<T>()) erzeugt nur Member mit einem dieser Attribute (voller oder einfacher Name,Attributeoptional), z. B. Options-Klassen, deren übrige Member Geheimnisse sind:Type<WhiteLabelingOptions>(o => o.IncludeMembersWithAttribute<PublicConfigurationAttribute>()).Property(...).Include()holt einen Member zurück, eine leere Liste am Typ schaltet den Filter der Generierung dort ab. - Typ-Auswahl per Attribut:
IncludeTypesWithAttributes(json, FluentIncludeTypesWithAttributes("Name")bzw.IncludeTypesWithAttribute<T>(ersterParameter)) wählt jeden Typ mit einem dieser Attribute, im Projekt und in allen referenzierten Assemblies außer denen des Frameworks;"Name=Wert"prüft zusätzlich das erste Konstruktor-Argument. So nimmt ein Frontend-Typen-Projekt die generierten DTOs der referenzierten Contracts-Projekte:IncludeTypesWithAttribute<GeneratedCodeAttribute>("Nextended.CodeGen")(ohne Argument passtGeneratedCodeauch auf Ressourcen-Klassen und Clients anderer Generatoren).Exclude*gewinnt. DTOs, die der Generator im selben Lauf erzeugt, sind noch nicht in der Kompilierung: die bringtFromGeneratedDtos(zusammen zählen sie einmal). - Unions ohne
[JsonPolymorphic]:DerivedTypesan einem Basistyp (Namen,*-Muster;"*"= alle nicht abstrakten, nicht generischen abgeleiteten Klassen der Kompilierung und der Assembly der Basis) macht ihn zur Union:Type<PlaceDto>(p => p.DerivedTypes("*"))→PlaceDtoBase+type PlaceDto = AddressPlaceDto | CountryPlaceDto | PortPlaceDto. Bei generierten DTOs passen auch die Entity-Namen (DtoConfig<Place>.Typescript(t => t.DerivedType<AddressPlace>())). Eine nicht abstrakte Basis gehört selbst zur Union. Diskriminator nur, wenn der Server einen schreibt:"PortPlace=port"bzw.DerivedType<PortPlace>("port")mitDiscriminator("kind")(Standard$type), für OData z. B.Discriminator("@odata.type").[JsonDerivedType]am Typ gewinnt. - Dateien: Ordner je Namespace oder flach, eine Datei je Typ, relative
import type,index.ts, Header (// <auto-generated>+/* eslint-disable */, eigener Text mitHeader,""= keiner; ESLint 9 meldet eineslint-disableohne Wirkung, ohne die Zeile meldetno-empty-object-typeInterfaces, die nur eine Basis erweitern: den Ordner in die ESLint-ignoresaufnehmen), immer\n, deterministisch; unveränderte Dateien werden nicht neu geschrieben, veraltete über ein Manifest (.nextended-typescript) gelöscht — Dateien außerhalb des Manifests werden nie angefasst. Gleichnamige Typen kollidieren nicht. - Build und CI: geschrieben wird bei jedem Generator-Lauf (auch in der IDE), aber nicht, solange eine Quelldatei Syntaxfehler hat (
NCG031).dotnet build -p:NextendedCodeGenTypescriptCheck=trueschreibt nichts und schlägt mitNCG032fehl, wenn das generierte TypeScript veraltet ist; alternativ normal bauen undgit diff --exit-code.
Zwei Serializer: ABP und OData
Ein Server antwortet oft über zwei Serializer, die dieselben C#-Typen verschieden schreiben:
| ABP / ASP.NET Core MVC (System.Text.Json) | OData (Microsoft.AspNetCore.OData) | |
|---|---|---|
| Enums | Zahlen ("state": 1), außer ein JsonStringEnumConverter ist registriert | Member-Namen ("state": "Booked", Flags "Mail, Push") |
| Member-Namen | camelCase | die EDM-Namen: camelCase mit EnableLowerCamelCase(), sonst wie deklariert |
| abgeleitete Typen | nur der deklarierte Typ, außer Polymorphie ist konfiguriert | die Member des Laufzeittyps; eine abgeleitete Instanz trägt "@odata.type" |
Eine Generierung beschreibt einen Serializer. Für beide zwei Generierungen mit eigenem OutputPath (ein Ordner je Generierung, das Manifest gehört einer Generierung):
Typescript(t => t.OutputPath("../frontend/src/types/generated").EnumValues(TypescriptEnumValues.Number).Include<ShipmentDto>()); // Zahlen
Typescript(t => t.OutputPath("../frontend/src/types/odata") // Namen
.EnumValues(TypescriptEnumValues.String).PropertyNaming(TypescriptNaming.AsIs).Include<Shipment>());In codegen.json zwei Einträge in "Typescript" mit "EnumValues": "Number" bzw. "EnumValues": "String". Innerhalb einer Generierung folgt ein einzelner Member dem anderen Serializer per [JsonConverter(typeof(JsonStringEnumConverter))] an der Property oder .Property(x => x.State).Type("keyof typeof ShipmentState").
Beispiel: CodeGenTsSample (drei Generierungen, mit tsc --strict geprüft). Alle Einstellungen, die Abbildungstabelle und die Diagnosen: TypeScript generation (englisch).
DTO-Einstellungen im Überblick
Alle mit Beispielen auf der englischen Referenz. Ohne Angabe bleibt die Ausgabe wie bisher.
| Einstellung | Wo | Wirkung |
|---|---|---|
KeepEnumFlagsAndUnderlyingType | DtoGeneration | generierte Enums behalten [Flags] und den zugrunde liegenden Typ (: short) |
KeepAttributesOnGeneratedClass, PreClassString | [AutoGenerateDto] eines Enums | Attribute des Quell-Enums bzw. Text über dem Enum (z. B. ein JsonConverter) |
KeepPropertyAttributesOnGeneratedClass, PreClassString einer Property | Attribut | wirken auf alle Member der Klasse, auch skalare und Enum-Member |
InitializeCollections | DtoGeneration | nicht-nullbare Collection-Properties starten mit [] |
TypesToIgnore | DtoGeneration | Typen (und über AutoGenerateDerived erfasste abgeleitete Typen) ohne DTO |
DeleteStaleFiles | DtoGeneration, Fluent Defaults(d => d.DeleteStaleFiles()) | löscht in jedem Ordner, in den die DTO-Generierung in diesem Lauf schreibt, die .cs-Dateien, die dieser Lauf nicht geschrieben hat und die mit der Kopfzeile // <auto-generated/> beginnen (jede DTO-, View-, Mapping- und ComGuids-Datei). Nichts anderes: keine handgeschriebenen Dateien, keine Unterordner, keine Ordner ohne Datei dieses Laufs. Übersprungen bei Syntaxfehlern, NCG020 und Fehlern der DTO-Generierung. Jedes Projekt braucht eigene Ausgabeordner. Standard aus |
GeneratedCodeAttribute | DtoGeneration und je StructureGenerations/ExcelGenerations-Eintrag; Fluent Defaults(d => d.GeneratedCodeAttribute(false)), StructureGeneration(s => ...), ExcelGeneration(e => ...) | [global::System.CodeDom.Compiler.GeneratedCode("Nextended.CodeGen", null)] auf jedem generierten Typ (DTO-Klassen/Records, Interfaces, Enums, Mapperly-Mapper, ComGuids, Structure- und Excel-Klassen, Facet-Registrierung), direkt unter dem XML-Kommentar. Nicht doppelt, wenn der Typ es über KeepAttributes oder PreClassString/PreInterfaceString schon trägt; die über viele Dateien verteilte partial-Klasse MappingExtensions bekommt es nicht (nur einmal pro Typ erlaubt). Standard an: das Update schreibt einmalig eine Zeile pro Typ in alle generierten Dateien; mit false bleiben sie byte-identisch |
GeneratedCodeVersion | wie oben | schreibt die Paketversion des Generators statt null ins Attribut; Standard aus (sonst ändert jedes Update alle Dateien) |
SkipReverseMapping | DefaultMappingSettings | nur Quelle → DTO, kein AssignTo/ToNet zurück |
MapDerivedTypes | DefaultMappingSettings | Mapperly: Member eines Basistyps werden auf das DTO des Laufzeittyps gemappt (MapDerivedType) |
Namespace | [AutoGenerateDto], View | eigener Namespace eines DTOs oder einer View; generierter Code anderer Namespaces (Mapping-Dateien, Generic-Constraints, Casts auf das Basis-DTO) nennt es voll qualifiziert, ohne global using oder Alias |
DTO-Views: mehrere DTOs einer Entity
Das erste [AutoGenerateDto] eines Typs beschreibt sein Standard-DTO. Jedes weitere [AutoGenerateDto] am selben Typ erzeugt ein weiteres DTO, eine View: eine andere Form für einen anderen Client (alte API, Listenzeile, Export) mit eigenem Mapping. Ein Typ mit nur einem Attribut erzeugt genau das, was er bisher erzeugt hat.
[AutoGenerateDto(AutoGenerateDerived = true)] // Standard: QuotationDto
[AutoGenerateDto(GeneratedClassName = "QuotationAbp", // View: QuotationAbpDto
PropertyNames = ["DateCreatedUtc=CreationTime", "DateUpdatedUtc=LastModificationTime"],
UseViews = ["PortAbp", "HubCode", "QuotationStatusAbp"])]
public class Quotation : GuidBaseEntity { /* ... */ }
// eine View für alle Code-Entities: einmal an der gemeinsamen Basisklasse
[AutoGenerateDto(AutoGenerateDerived = true)]
[AutoGenerateDto(GeneratedClassName = "HubCode", PropertiesToIgnore = ["DateCreatedUtc", "DateUpdatedUtc"])]
public abstract class CodeEntity : GuidBaseEntity { /* ... */ }
var abp = quotation.ToQuotationAbpDto(); // das Standard-DTO bleibt quotation.ToDto()GeneratedClassName | Pflicht für eine View, zugleich ihr Schlüssel für UseViews und GenerationPropertySetting.View |
| Member | alle öffentlichen Properties inklusive geerbter (flach, kein Basis-DTO), minus eigenes PropertiesToIgnore; auch bei abstraktem Typ eine konkrete Klasse |
PropertyNames | "Quelle=Ziel"-Paare, benennen Member dieses DTOs um, auch geerbte; gewinnt gegen GenerationPropertySetting.PropertyName |
UseViews | Member, deren Typ (oder dessen Basistyp) eine der genannten Views deklariert, bekommen diese View statt des Standard-DTOs (auch in Collections und an Standard-DTOs) |
OutputPath | eigener Ausgabepfad für die Datei dieses DTOs |
[GenerationPropertySetting(View = "...")] | mehrfach erlaubt; eine Einstellung für eine View ersetzt dort die ohne View |
| Mapping | je View eigenes Mapping: To<ViewKlasse>() (oder ToDtoMethodName), Extensions oder Mapperly (<ViewKlasse>Mapper); eine View eines abstrakten Typs bzw. eines Basistyps mappt nur in Richtung View |
| Gemeinsame View | mehrere Entities teilen eine View über eine gemeinsame Basisklasse; gleichnamige Views unabhängiger Entities werden gemeldet (NCG011) und weggelassen |
| Diagnosen | NCG010 View ohne Namen, NCG011/NCG012 Name bzw. Mapping-Methode vergeben, NCG013 unbekannte View in UseViews, NCG014 ungültiger PropertyNames-Eintrag |
Die neuen Einstellungen liest der Generator per Name, er braucht also keine bestimmte Nextended.Core-Version; das eigene Projekt braucht eine Nextended.Core-Version, die sie deklariert. Ausführlich mit erzeugtem Code: DTO views (englisch).
Generische Typen: ein Typ mit generiertem DTO wird auch als Typargument ersetzt, in Membern, Basisklassen und Constraints (HolderDto<AddressDto>, where TUnit : UnitDto). Ist ein Typparameter auf einen Typ mit DTO eingeschränkt, bekommen die Mapping-Methoden einen zweiten Typparameter für die DTO-Seite (AssignTo<TUnit, TUnitDto>).
Generierung ohne Ausgabepfad (im Speicher)
Ist OutputPath null (json, Attribut oder Fluent), kommt der generierte Code nur in die Kompilierung, auf die Platte wird nichts geschrieben.
- Richtung. Die generierten Typen gibt es im Projekt, in dem der Generator läuft, und in den Projekten, die es referenzieren, sonst nirgends. Ein Source Generator kann Code nur der Kompilierung hinzufügen, in der er läuft; in ein anderes Projekt schreiben kann er nicht. Sollen die DTOs in einem Contracts-Projekt liegen, läuft die Generierung dort (es referenziert die Entities), oder
OutputPathzeigt in einen Ordner dieses Projekts (relativ, etwa../MyApp.Contracts/Dtos/). - Dateinamen. Die Dateien heißen wie auf der Platte. Erzeugt ein Lauf zwei gleichnamige Dateien (
OfferDtoinA.Contractsund inB.Contracts), behält die erste ihren Namen, eine spätere kommt als<Namespace>.<Dateiname>dazu (B.Contracts.OfferDto.g.cs), danach mit Nummer. Nur der Name der hinzugefügten Quelle ändert sich, nie ein Namespace oder eine Klasse; mitOutputPathbleiben die Namen auf der Platte unberührt. - Mapperly. Die Mapperly-Strategie braucht
OutputPathundMappingOutputPath: Mapperly sieht keinen Code, den ein anderer Source Generator hinzufügt, ohne sie enthält die Mapper-Datei ein#error(Mapperly instead of extension methods). Die Extension-Methoden funktionieren im Speicher. - TypeScript. Die TypeScript-Generierung liest die Kompilierung ohne generierten Code;
IncludeNamespaces,IncludeTypesundIncludeBaseTypesfinden DTOs im Speicher daher nicht.FromGeneratedDtos: true(FluentFromGeneratedDtos()) nimmt sie dazu. - Code ansehen. In Visual Studio unter Abhängigkeiten > Analysetools > Nextended.CodeGen > Nextended.CodeGen.MainGenerator, in Rider unter Dependencies > Source Generators, oder als Dateien mit:
<PropertyGroup>
<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
<CompilerGeneratedFilesOutputPath>GeneratedFiles</CompilerGeneratedFilesOutputPath>
</PropertyGroup>Die ausgegebenen Dateien sind eine Kopie zum Lesen; die Kompilierung verwendet sie nicht.
Ausführbares Beispiel
Im Repository liegt ein vollständiger, startbarer AppHost:
git clone https://github.com/fgilde/Nextended.git
cd Nextended/Tests/TestProjects/CodeGenSample
dotnet runUnterstützte Frameworks
netstandard2.0
Plattform
Build-time (analyzer)
Abhängigkeiten
- Nextended.Core
- Microsoft.CodeAnalysis.CSharp
- ClosedXML
Links
Lizenz
MIT — siehe LICENSE.