README.md

Require a method to be invoked with named arguments

This project contains a Roslyn code analyzer and an accompanying code-fix provider that let you force named arguments in C#.

How to use it?

Install the nuget package.

Introduce a RequireNamedArgsAttribute attribute to your solution. In other words, place the following C# code in an appropriate spot in your solution.

[AttributeUsage(AttributeTargets.Constructor | AttributeTargets.Method | AttributeTargets.Class | AttributeTargets.Struct)]
class RequireNamedArgsAttribute : Attribute {}

Apply the [RequireNamedArgs] attribute to the methods that should only be called with named arguments. For example:

[RequireNamedArgs]
public static void TellPowerLevel(string name, int powerLevel) {}

// Elsewhere in your code:
// if `TellPowerLevel` method is called with positional arguments,
// the analyzer will emit an error.
TellPowerLevel(name: "Goku", powerLevel: 9001);

Supported method kinds

The analyzer supports requiring named arguments for the following method kinds

• Regular instance and static methods
• Extension methods
• Regular constructors
• Attribute constructors
• Primary constructors

To mark a record's primary constructor, apply [RequireNamedArgs] to the record itself.

[RequireNamedArgs]
record Character(string Name, int PowerLevel) {}

[RequireNamedArgs]
record struct CharacterStruct(string Name, int PowerLevel) {}

// Elsewhere in your code:
// if the primary constructor of `Character` or `CharacterStruct` is called with positional arguments,
// the analyzer will emit an error.
new Character(Name: "Goku", PowerLevel: 9001);
new CharacterStruct(Name: "Goku", PowerLevel: 9001);

Please note, in the code above the attribute only applies to the primary constructors of the records. If a record has additional constructors, you can mark them with this attribute individually in a usual way.

Download and install

Install the RequireNamedArgs nuget package. For example, run the following command in the NuGet Package Manager Console.

Install-Package RequireNamedArgs

This will download all the binaries, and add necessary analyzer references to your project.

Configuration

Starting in Visual Studio 2019 version 16.3, you can configure the severity of analyzer rules, or diagnostics, in an EditorConfig file, from the light bulb menu, and the error list.

You can add the following to the [*.cs] section of your .editorconfig.

[*.cs]
dotnet_diagnostic.RequireNamedArgs.severity = error

The possible severity values are:

• error
• warning
• suggestion
• silent
• none
• default (in case of this analyzer, it's equal to error)

Please take a look at the documentation for a detailed description.

How does it work?

1. This analyzer looks at an invocation expression (e.g., a method call).
2. It then finds the method's definition.
3. If the definition is marked with a [RequireNamedArgs] attribute,
   the analyzer requires every caller to provide names for the invocation's arguments.
4. If the last parameter is params, the analyzer
   doesn't emit the diagnostic, as C# doesn't allow named arguments in this case.

Technical details

The analyzer, code-fix provider, and tests are implemented in F#

Thank you!

• John Koerner for Creating a Code Analyzer using F#
• Dustin Campbell for CSharpEssentials
• Alireza Habibi for CSharpUseNamedArgumentsCodeRefactoringProvider which provided very useful code examples.
• Steve Smith for his article Improve Tests with the Builder Pattern for Test Data.

License

The RequireNamedArgs analyzer and code-fix provider are licensed under the MIT license.
So they can be used freely in commercial applications.