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 |
OPT0001
Section titled “OPT0001”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.
OPT0002
Section titled “OPT0002”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.
OPT0003
Section titled “OPT0003”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")].
OPT0004
Section titled “OPT0004”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.
OPT0005
Section titled “OPT0005”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.
OPT0006
Section titled “OPT0006”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.
OPT0007
Section titled “OPT0007”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.
OPT0008
Section titled “OPT0008”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.
OPT0009
Section titled “OPT0009”Schema generation failed unexpectedly for a type. The type has no schema. Please report it.
OPT0010
Section titled “OPT0010”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.
OPT0011
Section titled “OPT0011”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.
OPT0012
Section titled “OPT0012”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.
OPT1001
Section titled “OPT1001”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.Analyzersfrom@(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.
OPT1002
Section titled “OPT1002”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.
OPT1003
Section titled “OPT1003”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.
OPT1004
Section titled “OPT1004”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).
OPT1005
Section titled “OPT1005”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,falseand arrays aren’t accepted); - has
definitionsthat aren’t an object, or definition names outside^[A-Za-z0-9._-]+$; or - has a local
$refthat doesn’t point at one of itsdefinitions.
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.