Should I not expose private Win32 types?

[Gavin Williams (Gavin-Williams)]

When I use types like HWND or BITMAPINFO, they are private by default. Should I not expose these types? Sometimes I can force them to be public, with this I think...

{
"$schema": "https://aka.ms/CsWin32.schema.json",
"public": true
}

Mostly this has worked, but sometimes it doesn't. Here's a capture of HWND showing that it's private, while underneath you can see that public = true.

So it seems unstable or something depending on unknown factors.

It makes me wonder if I should expose Win32 types at all. If they are private by default, maybe that's for a good reason. And everything should be in a wrapper.

What's the right way here?

[Jevan Saks (jevansaks)]

Generally you should not expose CsWin32 types as public because these kinds of win32 APIs are implementation details of a component, that's why it's private by default. But within some components (E.g. in WinForms) there is more sharing happening and so Jeremy Kuhne (@JeremyKuhne) implemented #1477.

[kami (kaminagakur4)]

Jevan Saks (@jevansaks) answered the "should I", and the source backs up why that's the only sane default: public is a single generator-wide switch, not a per-type one.

Generator.cs:

private SyntaxKind Visibility => this.options.Public ? SyntaxKind.PublicKeyword : SyntaxKind.InternalKeyword;

Every emitter — Generator.TypeDef.cs for handle types like HWND, Generator.Struct.cs for BITMAPINFO, extern methods, constants, COM — reads that one property. So there is no "make HWND public and leave the rest internal". Flipping it exposes your entire projection, which is exactly the argument for the wrapper.

On the other half — "seems unstable depending on unknown factors" — there are two mechanisms that produce what you're seeing, and one line tells you which:

1. Your NativeMethods.json may not be the one being read. Only one settings file is ever consulted, SourceGenerator.cs:

.FirstOrDefault(af => Path.GetFileName(af.Path).EndsWith(NativeMethodsJsonAdditionalFileName, StringComparison.OrdinalIgnoreCase));

FirstOrDefault, and the match is EndsWith. So MyNativeMethods.json counts too, and if more than one candidate lands in AdditionalFiles — linked/shared items, a Directory.Build.props glob, a multi-targeting project pulling in a second copy — one of them wins and the rest are ignored silently. No diagnostic is reported for the losers; the only OptionsParsingError is for malformed JSON. If the winner has no "public": true, everything goes internal while the file you're looking at says otherwise.

The check, no rebuilding required: open any generated file and look at the #pragma warning disable line under the auto-generated banner. Generator.cs picks the header off the setting:

this.fileHeader = this.options.Public ? FileHeader : FileHeaderWithClsArrayAttributeSuppression;

and the second one is the first plus CS3016 ("Arrays as attribute arguments is not CLS-compliant"), used only for internal projections. So:

• CS3016 present in that disable list → the generator ran with public: false, whatever your JSON says. Go find the other settings file.
• CS3016 absent → the setting was picked up, and what you're looking at is Consume metadata as dll #2.

2. Some members are unconditionally public by design. In Generator.TypeDef.cs the operators carry a hardcoded PublicKeyword with the comment // operators MUST be public, while the struct and its Value field follow Visibility. So an internal HWND whose conversion operators show as public is expected output, not a glitch — and in an IDE view that mix is easy to read as "sometimes public, sometimes not".

Worth ruling out #1 first, since it's the one that would explain the same JSON behaving differently across projects.

[Jevan Saks (jevansaks)]

I missed the bug report part of this post. If you want the types to be public and there's a generator bug, please file that as an issue with a repro and we can address it.