Skip to content

MSBuild properties

These properties and items are Optionary’s public MSBuild API. They change only in a major version. Set them in the project file or in a Directory.Build.props:

<PropertyGroup>
<!-- Permissive: unknown keys under Optionary sections aren't flagged -->
<OptionarySchemaStrict>false</OptionarySchemaStrict>
</PropertyGroup>
Property Default Effect
OptionarySchema on false writes no schema files, no Visual Studio segments and no editor settings, and removes the files an earlier build wrote.
OptionarySchemaHost detected true or false overrides which projects are hosts. Left empty, test projects (IsTestProject) and applications (OutputType Exe or WinExe, or an Android application) are.
OptionarySchemaStrict true false leaves Optionary’s sections open (no propertyNames check) in the application schema.
OptionarySchemaIncludeSchemaStore true false leaves SchemaStore’s appsettings.json schema out of the application schema.
OptionarySchemaCopyToOutput true false keeps a host’s application schema in obj/: it isn’t copied to the output directory or published. For hosts that embed their configuration (MAUI, Uno).
OptionarySchemaRequired false true lists required members in each fragment’s required. The generator reads this one, so it changes the fragments in every project that sets it.
OptionaryReferenceDocumentation on false doesn’t pass referenced packages’ XML documentation files to the generator, so types declared with [assembly: Optionary<T>] get no descriptions from them.
Property Default Effect
OptionarySchemaVisualStudio on false adds no JsonSchemaSegment items for Visual Studio; the schema files are still written.
OptionaryScaffoldEditorSettings off true writes Optionary’s mappings into .vscode/settings.json when a host builds. See VS Code.
OptionaryEditorSettingsDirectory git root The folder that holds .vscode. Relative paths are relative to the project. By default, the nearest ancestor with a .git entry, or the project folder.
Property Default Effect
RootNamespace SDK The namespace of the generated registration method, used verbatim. Empty or whitespace puts it in the global namespace.
OptionaryZeroAllocValidation on false leaves ZeroAlloc.Validation’s registrations to the project: the registration method doesn’t call ValidateWithZeroAlloc().
LangVersion SDK C# 12 or later is required. Below that the registration method is empty and OPT0001 is reported.
Item Metadata Effect
OptionarySchemaFragment Schema or File, exactly one Include is a section path. Schema is the schema of the section’s value as inline JSON, File a JSON file holding it (relative to the project), in the fragment format. It becomes the project’s fragment for that section, like one the generator writes. A package’s buildTransitive targets can add it. See contributing a fragment.
Item Metadata Effect
AdditionalFiles OptionaryReferenceDocumentation="true" Marks an XML documentation file the generator reads descriptions from, for types declared with [assembly: Optionary<T>]. Optionary adds these itself for package references; add your own for other files.
File Written by What it is
$(BaseIntermediateOutputPath)appsettings.schema.json hosts The application schema, at a stable path (normally obj/appsettings.schema.json). Copied to $(OutDir) and published unless OptionarySchemaCopyToOutput is false.
$(IntermediateOutputPath)appsettings.schema.json multi-target hosts The application schema for each target framework after the first.
$(IntermediateOutputPath)ConfigurationSchema.json libraries The library schema, packed at the package root.
$(IntermediateOutputPath)<project>.OptionarySchemaFragments.cs projects with OptionarySchemaFragment items The fragments’ attributes, when GenerateAssemblyInfo or GenerateAssemblyMetadataAttributes is false; otherwise they are in the SDK’s AssemblyInfo.cs.

A framework that builds on Optionary can set OptionarySchemaHost, OptionarySchemaCopyToOutput and OptionaryZeroAllocValidation from its own targets. Optionary reads them when the schema is computed, not at evaluation, so a value set anywhere during evaluation counts, and setting them has no effect in a project that doesn’t reference Optionary. Dovetail does this from its application detection and its embedded-configuration and ZeroAlloc switches.