Skip to content

Diagnostics

The generator reports OPT0001 to OPT0012, in the Optionary category. OPT1001 to OPT1005 are MSBuild errors from Optionary’s targets. The generator runs in every project that references Optionary, including through a transitive reference, so these can fire in a consumer of a library too. Except for OPT0001, they are reported against source, so #pragma warning disable works for the warnings.

Id Severity Summary
OPT0001 Warning C# older than 12: nothing is bound
OPT0002 Error Invalid options type
OPT0003 Error Invalid section path
OPT0004 Warning Unsupported member
OPT0005 Warning Key collision
OPT0006 Error Options type can’t be created
OPT0007 Warning Type graph too large
OPT0008 Warning Annotation not expressible in JSON Schema
OPT0009 Warning Schema generation failed
OPT0010 Error Options type declared more than once
OPT0011 Error Key style conflict
OPT0012 Warning ZeroAlloc options validation skipped
OPT1001 Error The runtime is referenced but the generator isn’t loaded
OPT1002 Error Schema fragment item without exactly one schema
OPT1003 Error Schema fragment item with an invalid section path
OPT1004 Error Schema fragment file not found
OPT1005 Error Schema fragment item’s schema isn’t a fragment

The project’s C# version is older than 12. Warning, reported once per compilation by every project that references Optionary (with or without declarations) whose LangVersion is below 12:

Optionary’s source generator needs C# 12 or later, but this project uses C# version, so AddOptionaryConfigurationOptions registers nothing and no configuration schema is generated; set LangVersion to 12 or later to enable it

The registration method is still emitted, so calls to it compile, but its body is empty: no options type is registered and no fragment is written. Set LangVersion to 12 or later. It has no source location, so suppress it with <NoWarn> rather than #pragma.

The type can’t be described as configuration: an interface, a static or abstract class, a struct or enum, an open generic type, or a collection. Declare a class or record class instead.

The section path isn’t valid for the type: it is empty, has an empty segment (A::B), or was derived from a type name that is only a suffix, such as a class called Options. Give the declaration a path: [Optionary("Section")].

A member has a type configuration binding doesn’t support. It is left out of the schema and the binder. A required member that can’t be bound is set to default! so the generated code compiles. See supported types.

Two members bind the same key. Keys ignore case, so Name and NAME collide, as do two members given the same [ConfigurationKeyName]. Only the first is described.

The type can’t be created from configuration: it has no public constructor, several public constructors with parameters and none without, or a constructor parameter that matches no property.

The type graph uses too many distinct types (more than 200), so the schema stops describing them at the member named. Self-expanding generic types report this too.

An annotation has no JSON Schema equivalent (a regular expression that can’t be anchored, for example) and is left out of the schema. The member is still bound.

Schema generation failed unexpectedly for a type. The type has no schema. Please report it.

A type is declared more than once: by both [Optionary] on the class and [assembly: Optionary<T>], or by two assembly attributes. It is reported on the assembly attribute, which contributes nothing. Keep one declaration.

A type is bound with more than one key style, because sections with different key styles reach it. The later declaration is reported and contributes nothing. Use the same KeyStyle for every section that reaches the type, or give the shared type [ConfigurationKeyName] attributes. See key styles.

A [Validate] type has an asynchronous ZeroAlloc.Validation rule, so it isn’t validated with ValidateWithZeroAlloc(): options validation is synchronous. Make the rule synchronous, or validate the type another way.

Optionary is referenced but its generator isn’t loaded. Reported by the _OptionaryCheckGenerator target in Optionary.targets, before CoreCompile, when Optionary.dll is among the resolved references (@(ReferencePath)) and no @(Analyzer) item has the file name Optionary.Analyzers:

Project references Optionary.dll, but Optionary’s source generator (Optionary.Analyzers) isn’t loaded: no @(Analyzer) item is Optionary.Analyzers, so its [Optionary] types get no AddOptionaryConfigurationOptions registration method or configuration schema. Look for a target (in the project, a Directory.Build.targets, or another package) that removes Optionary.Analyzers from @(Analyzer), and build with the .NET 10 SDK or later: the package has generators only for Roslyn 5.0 and later, so an older compiler loads none.

Without the generator nothing is bound and no registration method exists.

It happens when:

  • a target removes Optionary.Analyzers from @(Analyzer); or
  • the compiler is older than Roslyn 5.0, so none of the package’s generator slices matches it.

ExcludeAssets="analyzers" doesn’t cause it: the .NET SDK passes a package’s analyzers to the compiler whatever the reference excludes, so the generator still runs. ExcludeAssets="build" or "all" skips Optionary.targets, and with it this check; see troubleshooting for what you see then.

Remove the target, or build with the .NET 10 SDK or later. See troubleshooting.

An OptionarySchemaFragment item has neither or both of Schema and File. Reported by the _OptionaryReadSchemaFragments target, against the project or targets file that declares the item:

The OptionarySchemaFragment item “section” has neither Schema nor File metadata: set exactly one, Schema to the section’s schema as JSON or File to a JSON file holding it.

A value of only whitespace counts as not set. See contributing a fragment.

An OptionarySchemaFragment item’s Include isn’t a valid section path: it has an empty segment, such as HttpClients::Petstore, HttpClients: or HttpClients: :Petstore. The rules are those of OPT0003 for a path given in a declaration. A transform such as @(OpenApiClient->'Clients:%(ClientName)') reports it for an item whose ClientName is empty.

An OptionarySchemaFragment item’s File doesn’t exist, or can’t be read. The message gives the full path. A relative File is relative to the project, so a package’s targets should use $(MSBuildThisFileDirectory).

An OptionarySchemaFragment item’s schema isn’t a configuration schema fragment. Reported against the file, or for Schema against the project or targets file that declares the item, when the JSON:

  • isn’t valid JSON;
  • isn’t a JSON object (true, false and arrays aren’t accepted);
  • has definitions that aren’t an object, or definition names outside ^[A-Za-z0-9._-]+$; or
  • has a local $ref that doesn’t point at one of its definitions.

The message ends with the problem found. The format is described under fragments. An inline Schema that MSBuild changed, by expanding $(...) or unescaping %XX, can also end up here: see contributing a fragment.