move to Convention based templates

[SimonCropp]

Parchment 5.0.0

Templates are now found by convention, embedded into your assembly at compile time, and rendered by model type. There is no registration call, no template file to deploy, and no template name to repeat. Model binding is entirely source-generated — the runtime reflection layer is gone.

This is a breaking release. Every consumer needs the migration steps below.

Templates are found by convention

[ParchmentModel] takes no arguments. The template is the AdditionalFiles entry named after the model type — Invoice.docx or Invoice.md — wherever it sits in the project.

// before
[ParchmentModel("Templates/invoice.docx")]
public partial class Invoice { … }

// after — rename the file to Templates/Invoice.docx
[ParchmentModel]
public partial class Invoice { … }

No match is PARCH004; more than one (a .docx and a .md, or namesakes in different folders) is PARCH020. Both are reported rather than guessed at.

Templates are embedded; nothing to register, nothing to deploy

The generator embeds the template into the generated source and registers it from a [ModuleInitializer] when your assembly loads. A TemplateStore materializes it on the model's first render.

// before
var store = new TemplateStore();
Invoice.RegisterWith(store, basePath: AppContext.BaseDirectory);
await store.Render("Invoice", invoice, stream);

// after
var store = new TemplateStore();
await store.Render(invoice, stream);

The generated RegisterWith, TemplatePath and TemplateName members are removed, as is the <ParchmentEmbeddedTemplate> MSBuild item and its manifest-resource staging — every template is embedded now. <ParchmentTemplate> remains, and no longer sets CopyToOutputDirectory.

Rendering is keyed by model type

All name-based overloads are removed. A model has exactly one template; re-registering replaces it.

store.RegisterDocxTemplate<Invoice>("invoice", path);   // before
store.RegisterDocxTemplate<Invoice>(path);              // after

await store.Render("invoice", model, stream);           // before
await store.Render(model, stream);                      // after

If you relied on several templates per model, give each its own model type — a thin wrapper class holding the shared data is enough. Registering against an abstract base still accepts subclass instances at render.

Style documents move to .dotx and are found by convention

A markdown template's style source is resolved in order: TypeName.dotx, else the nearest parchment.dotx walking up the directory tree from the template, else the built-in blank. Declare them as AdditionalFiles like templates; the resolved file is embedded alongside. Two TypeName.dotx matches is the new PARCH021. Docx templates are unaffected — they carry their own styles.

No runtime reflection over models

Every binding model now goes through the generator, which emits its member accessors and per-template maps at compile time. There is no reflection fallback: a model the generator never saw is rejected at registration (and at extraction) with a message naming the fix.

Hand registration is still supported for templates the generator cannot see — content produced at runtime, per-tenant templates. The model just has to be marked:

[ParchmentBindable]
public partial class Invoice { … }

store.RegisterMarkdownTemplate<Invoice>(runtimeMarkdown);
await store.Render(invoice, stream);

A model that cannot carry the attribute (a third-party or generated type) is no longer registrable — wrap it in a thin partial model class.

Trimming and NativeAOT: with the reflection walks gone, model binding is fully static.

New diagnostics

PARCH021	model matches more than one style document
PARCH022	[EditableField] collection element isn't constructable, has no editable members, or nests another editable collection
PARCH023	conflicting [Html] / [Markdown] / [StringSyntax] markers on one member

PARCH022 and PARCH023 were previously runtime registration exceptions; they now fail the build. PARCH019 (render attribute on a static member) is compile-time only — the corresponding ILogger warning at registration is removed.

Fixed

Four model-binding bugs surfaced while making the generator the only path — all of them affected [ParchmentModel] users already:

• Array-typed members emitted accessors for System.Array's own members, producing source that could not compile.
• Dotted map keys were mangled under the netstandard2.0 analyzer build (StringBuilder.AppendJoin binding to the params-object overload).
• Repeating-section element factories used new T(), which cannot compile for element types with required members.
• IDictionary<K,V> members did not bind on the generated path; KeyValuePair is now part of the emitted shape.

Also

• ParchmentExtractor.Extract<T> distinguishes "model was never source-generated" from "model declares no [EditableField] members" instead of reporting the latter for both.
• Internal Resolve* helpers across the runtime and generator moved to the Try* + [NotNullWhen(true)] pattern.