Prefer ExactSpelling=true on [DllImport] for known APIs

[elinor-fung]

On Windows, setting ExactSpelling=true on the DllImport attribute prevents the runtime from looking for alternate function names (suffix based on CharSet), giving a slight performance benefit by avoiding this search.

There is a fair amount of nuance associated with the behaviour of ExactSpelling and under which scenarios there would actually be a performance benefit. In order to avoid noise, this rule can be scoped to check for a database of Win32 APIs that use the suffixes and provide a warning and fix for those cases where it matters.

// Flag ExactSpelling=false
[DllImport("kernel32.dll", CharSet=CharSet.Unicode)]
private static extern bool SetEnvironmentVariableW(string name, string? value);

// OK - not in database of APIs
[DllImport("MyLibrary.dll", CharSet=CharSet.Unicode)]
private static extern void Foo();

Recommend:

[DllImport("kernel32.dll", CharSet=CharSet.Unicode, ExactSpelling = true)]
private static extern bool SetEnvironmentVariableW(string name, string? value);

Category: Performance
Default: Enabled

cc @terrajobst @stephentoub @AaronRobinsonMSFT @jkoritzinsky

[stephentoub]

Is there any concern here that someone following this guidance will introduce bugs, e.g. because they were actually relying on the behavior? Can an auto-fixer do more than just add "ExactSpelling = true", e.g. would it be able to update the function name appropriately in case adding ExactSpelling would be introducing a bug?

I expect we have a bunch of places where we don't follow this guidance in dotnet/runtime. What does a fix look like there, and how much overhead should we expect to see removed? If it's meaningful enough to add an analyzer for, it would more so seem to be something we should fix in dotnet/runtime for .NET 5.

[AaronRobinsonMSFT]

Is there any concern here that someone following this guidance will introduce bugs, e.g. because they were actually relying on the behavior?

The biggest one is for Win32 APIs that use the A/W suffix. Detecting that might be possible, but the heuristic would be fragile. We could have an exhaustive Win32 API list where this applies. I haven't observed new Win32 APIs applying these suffixes anymore so it might actually be stable.

[EgorBo]

I believe there is an issue somewhere to turn off A/W probing for non-windows OSs so ExactSpelling=true will be just a noise for them.

[elinor-fung]

Good call about non-Windows - certainly would not want that noise.

Looking more at how we look for an entry point, it does have a bit more subtlety than I had realized. On Windows, if ExactSpelling=false and:

• CharSet=CharSet.Unicode, we always look for both the specified name and the name with the W suffix
  • Even if the specified name is found as an exact match to an entry point, we look for the W suffix. If found, the W suffix function is used.
  • It may not be clear to the user that they are actually relying on the suffix-appending behaviour, so ExactSpelling=true, would also require adding the W suffix,
• CharSet=CharSet.Ansi, we look for the specified name (no suffix) first and only try the suffix if it is not found
  • If the specified name is already the exact entry point name, setting ExactSpelling=true wouldn't make any difference.
  • Setting ExactSpelling=true would only matter if the user is actually relying on the suffix-appending behaviour - and it would require updating to add the A suffix.

Given the above, I'm a little less convinced that this should warrant a rule/fixer.

Rule or not, I'd agree we should do a pass over dotnet/runtime. Aside from places that just don't need the suffix behaviour, I also see some places where functions explicitly have the W suffix in the entry point name (e.g. FooW), but don't set ExactSpelling=true, so the runtime always looks for a duplicated suffix (e.g. FooWW)...

[jkotas]

Given the above, I'm a little less convinced that this should warrant a rule/fixer.

You build the database of OS APIs and do the rule/fixer for those only.