Remaining fallback options

[tmat]

Threads through fallback options to all remaining call sites that do not have them yet.
Obsoletes Document.GetDocumentOptions and DocumentOptionsSet internally (banned API).

Cleans up option types to use uniform patterns

• Use init-only properties instead of constructors, unless the option type has non-optional properties in which case these are passed to the constructor.
• Extension methods GetXyzOptionsAsync(this Document, XyzOptions fallbackOptions) and GetXyzOptionsAsync(this Document, XyzOptionsProvider fallbackOptionsProvider) are defined that read options from document. The former is used when fallbackOptions are readily available, the latter then we need to call a provider to retrieve them.

Language agnostic options

• Use records.
• Option type has Default static property that holds on the default values of all options.
• Extensions method are defined for each option type that reads the options from AnalyzerConfigOptions and IGlobalOptionsService:
  • GetXyzOptions(this AnalyzerConfigOptions, XyzOptions? fallbackOptions)
  • GetXyzOptions(this IGlobalOptionsService)

Language specific options

• Do not use records. VB doesn't support inheriting from a record and therefore we can't use records neither for the base class nor the C# subtype.
• XyzOptions is an abstract class and CSharpXyzOptions and VisualBasicXyzOptions are sealed derived classes.
• Options common to C# and VB are stored in the abstract base class. To avoid repetition when constructing options (via object initializers that assign to init-only properties) the common options are not stored directly on the abstract class but in a nested class CommonOptions. If C# language supported extension constructors we could remove this indirection.
• CommonOptions has Default static property that holds on the default values of the options.
• Language specific derived types have Default property that holds on the default values of all options.
• XyzOptions has GetDefault(HostLanguageServices language) static method that returns language specific instance with default values.

Accessing options from a feature implementation

In general, a feature that is configurable to produce different outputs should take the set of options it depends on as a parameter (of type {FeatureName}Options). Sometimes a feature A calls to feature B and feature B is parameterized by BOptions. Then AOptions type should contain a field/property of type BOptions, since the outcome of A depends on B's options. These options will be serialized as the feature is invoked from the client (if the feature runs OOP) like any other parameters. The granularity of these option types varies. E.g. if a feature X uses mostly the same options as feature Y then it might make more sense to use the same type for both features rather then to define multiple option types.

If a feature depends on options that may vary on per-document basis (e.g. editorconfig options) it is better to retrieve these options from the solution snapshot as the feature traverses the documents it operates on. editorconfig options are part of the solution snapshot and can be retrieved from Document instances via call to AnalyzerConfigOptions Document.GetAnalyzerConfigOptionsAsync(). Then use an extension GetXyzOptions method of AnalyzerConfigOptions to fetch the specific options type. Note that this method takes fallbackOptions. These are values of the corresponding options used when the value of the option is not specified in any editorconfig file that affects the document. Fallback options are global options passed to each feature that might read editorconfig options. Fallback options are generally passed lazily - via a provider interface that allows reading fetching the option set asynchronously and only for a specific language. This is important especially for features that may operate on documents from different projects/languages as we do not want to load options for all languages eagerly.

Accessing options from an analyzer or a code fix (unified across Code Style & Features layers)

Helper types are provided to avoid repetitive code used to access options (usually this code also varies between Code Style layer and other layers):

• AnalyzerOptionsProvider
• CSharpAnalyzerOptionsProvider
• VisualBasicAnalyzerOptionsProvider

The types are structs providing cheap and convenient façades making accessing options from code that executes within various analyzer contexts (SemanticModelAnalysisContext, SyntaxNodeAnalysisContext, SyntaxTreeAnalysisContext, etc.) straightforward and concise. The providers are returned by Get(CSharp|VisualBasic)AnalyzerOptions extension methods defined on the context types.

The types contain properties to read options on as needed basis, they do not have property for every single option.

Similarly CodeFixOptionsProvider, CSharpCodeFixOptionsProvider, VisualBasicCodeFixOptionsProvider are façades that provide options for Code Fixes and are available from extension methods GetCodeFixOptionsAsync defined on Document.

Review

I'd recommend looking at option types like SyntaxFormattingOptions, SimplifierOptions, CodeGenerationOptions, CodeActionOptions, AnalyzerOptionsProvider etc. first in their final form. I iterated quite a bit on shape of these options. Then commit by commit is probably best for rest of the changes.

[tmat]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 4 pipeline(s).

[dibarbet]

that was a long one!