Getting started?

[xyzzer]

I've spent a few hours trying to do a few basic things and I keep stumbling into issues I'd never experienced with pinvoke.net. It seems like a great project - the final pinvoke library to rule them all, but it seriously needs a simple introduction to get people going. I'm sure people who need to use this library for more extensive projects can somewhat quickly get deeply familiar with how things work, but to a plain old C# dev dev like me it feels kinda like stumbling into a bunch of assembly code. :)

Some issues I've been baffled by:

1. I followed the basic readme instructions - added the NuGet package, added the NativeMethods.txt, added my function/type names and... it seemed like nothing happened. First thing I did was type ShellExecuteEx then press Ctrl+. to add the namespace aaaaand - it wasn't found anywhere. I checked the Microsoft.Windows.SDK namespace expecting any Win32 stuff to fall in there since namespaces of things that go together should at least follow the same naming pattern and - nothing. Ctrl+; - nada. I saw some video "introduction" that I think mentioned Ctrl+T - doesn't seem like a shortcut that exists in my default C# dev VS configuration (I know there are some binding differences depending on how you set it up). I think only accidentally I found stuff in Windows.Win32 namespace under seemingly logical yet non-obvious namespaces after 2 hours of hunting around. I'd expect to be able to at least find some generated files somewhere but they seem nowhere to be seen. Normal people need some tips on where to expect to be able to find these generated types since there's no UI to let you know that anything is happening anywhere.
2. I was trying to use IKnownFolderManager, so I added both IKnownFolderManager and KnownFolderManager to NativeMethods.txt and - the interface seemed fine, but the class itself didn't seem to be implementing it. I guess there may be some pattern to how to cast these or maybe one should show as implementing the other but doesn't work due to some missing metadata, but either way - some samples could be useful.
3. The generated code seems very "unsafe" compared to pinvoke.net. Everything is some PCWSTR this or char* that and it seems like I need to pin things with fixed() or some such. Again, never needed these with pinvoke.net code. Perhaps it did it by itself, perhaps I've been lucky it always worked, but then - it would be helpful to see some examples for how to work with these generated APIs and maybe some explainer on why this is the better way.

I may be able to add more later, but please don't take it as plain ranting - I'm just trying to help make this thing better. :) Us C# folk are simple people. I create a new project form a project template in VS and mostly stick to the code editor tabs and the solution explorer. I'll use Stack Overflow or Copilot to find or generate rough outlines of any new API calls I try to use and usually that just works. In this case - I ended up copying most of the code I needed from Windows API Code Pack because the examples of the things I needed used it and it already wraps more of the APIs I needed in a more (WinForms-like) usable manner than a bunch of Win32 C calls wrapped into pinvoke, but I'll still need to add a few more API calls, so I'll try to figure out how to use CsWin32 before I fall back to pinvoke.net. Maybe I'm just not a typical use case for this library that was recommended to me by a colleague... :)

[ITaluone]

I had the same confusion, but had following error: project architecture was "Any CPU" and nothing was generated. Setting this to e.g. x64 generates the needed code.

But I agree: this does not align well with the given API from pinvoke.net and using unsafe code. Definitive room for improvement 😉

For example:

PInvoke.User32: I can use User32.ShowWindow(IntPtr handle, User32.WindowShowStyle style)
Microsoft.Windows.CsWin32: ShowWindow(HWND hwnd, SHOW_WINDOW_CMD style)

Well, nothing that couldn't be solved on users end, e.g. with Rider you have easy access to the generated files.

It took me a little more time to figure out all parts from the signature of (User32) LoadImage() especially the first parameter SafeHandle.

But I like this approach of generating only the needed stuff, and reduce the overhaul of unused APIs...

[AArnott]

Thanks for your feedback.

had following error: project architecture was "Any CPU" and nothing was generated. Setting this to e.g. x64 generates the needed code.

FYI that isn't typically required. AnyCPU works for most generated APIs. But yes, some APIs are unique per architecture and requires you to commit to one or more specific architectures.

this does not align well with the given API from pinvoke.net

Just an observation, you mention comparing this to pinvoke.net (which is a web site) but then your example is actually comparing PInvoke.User32 (which is a nuget package that is entirely separate from the pinvoke.net web site).
In your example of ShowWindow, the CsWin32-generated method actually has the better signature. Both use an enum, but only the CsWin32 definition uses the more strongly typed HWND struct, which is also interoperable with IntPtr.

with Rider you have easy access to the generated files.

VS also provides access to the generated files via the Solution Explorer (albeit it's buried and you have to know where to look):

[ITaluone]

Just an observation, you mention comparing this to pinvoke.net (which is a web site) but then your example is actually comparing PInvoke.User32 (which is a nuget package that is entirely separate from the pinvoke.net web site).

That's what I meant :)

[Gavin-Williams]

Where is that SourceGenerator foldout. I don't have net8 or anything like that in my dependencies.

[AArnott]

Thank you for your feedback, @xyzzer. Keep it coming. Some specific responses below:

I've spent a few hours trying to do a few basic things and I keep stumbling into issues I'd never experienced with pinvoke.net.

Sorry about that. I think pinvoke.net will be cognitively simpler to grasp than CsWin32 for a while yet, while C# folks get more accustomed to source generators. Copy and paste code from the internet has been around for decades vs. source generators for only a few years.

That said, my struggle with pinvoke.net has been poor or inconsistent quality and the need to copy and paste many snippets in order to get all the types declared. And when I'm using many definitions from pinvoke.net, I find they were never meant to work together and I had to unify types, etc.
CsWin32 on the other hand generates everything you need for an API with one word, and when you need multiple APIs they all agree on the interop types to use (modulo #1183, which I'd like to fix).

First thing I did was type ShellExecuteEx then press Ctrl+. to add the namespace aaaaand - it wasn't found anywhere.

The reason this didn't work is because in C# there is no such thing as a method without a type, and Ctrl+. never adds type names in front of methods. Had you typed PInvoke.ShellExecuteEx and then hit Ctrl+. I expect it would have worked.

Ctrl+T on the other hand (or the Navigate To command, however you access it) can find methods by their bare name. This keystroke even works directly from the NativeMethods.txt file. Usually, at least.

I checked the Microsoft.Windows.SDK namespace expecting any Win32 stuff to fall in there since namespaces of things that go together should at least follow the same naming pattern and - nothing.

We avoid CsWin32 dumping a bunch of types into a namespace populated by other existing assemblies, lest type collisions be introduced. I'll see though what we can do to make the namespace more discoverable (e.g. put it into the README more prominently).

I think only accidentally I found stuff in Windows.Win32 namespace under seemingly logical yet non-obvious namespaces after 2 hours of hunting around. I'd expect to be able to at least find some generated files somewhere but they seem nowhere to be seen.

Finding the generated files can be a challenge if you don't already know where to find them. See my response to @ITaluone on how you can find these.
This falls under the category of things that will get easier as folks become familiar with C# source generators.
The README includes an animated gif that shows how to find these generated files. Did you notice that or was it just not helpful?

I was trying to use IKnownFolderManager, so I added both IKnownFolderManager and KnownFolderManager to NativeMethods.txt and - the interface seemed fine, but the class itself didn't seem to be implementing it.

It doesn't need to implement it. Super counter-intuitive I know, but these types are just facades over native objects and COM. This code actually compiles and runs:

IKnownFolderManager f = (IKnownFolderManager)new KnownFolderManager();

Call it C#/.NET magic, but the constructor for KnownFolderManager isn't a typical one... the attributes on the class lead to the constructor actually activating a native COM object, so the cast ends up succeeding at runtime.

And ultimately, the reason CsWin32 doesn't generate an interface on the class to make it clear that it would succeed is that in the win32metadata from which code generation runs, the class is just a struct that doesn't implement the interface. And that in turn is because in the win32 header files (I suspect) there is no such interface implemented on the KnownFolderManager type.

some samples could be useful.

With CsWin32, the generated code will end up with your own C# code looking a lot like native code. So many of the samples that have been accumulating for decades for C/C++ will actually apply for C#. The win32 api docs themselves will also be immensely helpful to you. It is out of scope (for this repo anyway) to re-document all the APIs or create samples for many of them. But this Discussions tab can become a good place to exchange Q&As with folks on how to use specific APIs as they are generated by CsWin32.

The generated code seems very "unsafe" compared to pinvoke.net.

unsafe is your new friend. It turns out that writing unsafe code in C# is often safer than some of the crazy workarounds that I often see on pinvoke.net. pinvoke.net often uses IntPtr instead of native pointers, but IntPtr is a very poor type compared to the richness of SomeStruct*. IntPtr leads folks to have to write a bunch of try/finally blocks that use the Marshal class to copy structs around to and from an IntPtr and allocate/free unmanaged memory, whereas in the common case none of this is necessary when using pointers in C# directly.

This isn't to say unsafe is actually safe, but interop in general is not "safe", and avoiding the C# unsafe keyword shouldn't give you anything like a feeling of safety.

Everything is some PCWSTR this or char* that and it seems like I need to pin things with fixed() or some such. Again, never needed these with pinvoke.net code.

We have a couple of sometimes opposing goals: We want CsWin32 to generate APIs that are true to the underlying win32 APIs and that require little or no marshaling for maximum performance; but we also want the APIs to be user-friendly.
To bridge this gap, we've done a lot of work to make PCWSTR and string interop work as close to automatically as possible. In fact we have defined a lot of conversion operators in the generated APIs to make things easier. That said, we have a ways to go yet.

Like the deprecated PInvoke project we may offer more method overloads to make string work more naturally.
For structs however, we have fewer options. We only want to define a struct once (not twice, to match method overloads) since type equivalence is highly valuable on .NET and defining the same struct twice would make your life a lot harder. And structs that rely on the .NET marshaler incur a large perf penalty and may not even work well in future versions of .NET. For example the marshaler is not available in NativeAOT processes, and we want CsWin32 generated code to work in those environments.

I'll use Stack Overflow or Copilot to find or generate rough outlines of any new API calls I try to use and usually that just works.

One caution to add in general: pinvoke.net or stackoverflow code may appear to work for you, but from what I've observed it is often incorrect. It may work well enough on an x64 machine for your use case, but it may fail in x86 or arm64 processes. For example if the native header had a pointer and your C# declaration replaces that with long, it'll work on x64 but fail on x86. There are many even more subtle bugs than that.
When folks express dismay that CsWin32 generates harder to use methods or structs, it is sometimes something we can improve, but it is also sometimes that CsWin32's declaration is more correct/precise and therefore going to work in all cases where the declaration those users wanted to see would break.

[xyzzer]

pinvoke.net will be cognitively simpler to grasp than CsWin32 for a while yet, while C# folks get more accustomed to source generators

Thanks, it's all helpful. Like I said, just sharing my feedback to help generate more people familiar with how projection generators like this work! ;)

pinvoke.net has been poor or inconsistent quality

Don't disagree there and fully support the idea of CsWin32 and want it to succeed. Multiple examples for same thing on pinvoke.net usually include at least one that works and for simple method wrappers and enums or enum-like constants can at least be pruned to just the needed ones and cast to work with multiple the pinvoke snippets or inconsistent pinvoke declarations can be updated manually to use compatible argument types. Having this consistency from a generator and avoiding sprinkling boilerplate interop snippet sections all over C# projects or dumping them all in a global NativeMethods.cs will be awesome.

Ctrl+T on the other hand (or the Navigate To command, however you access it) can find methods by their bare name

Strange, I'm not finding "Navigate To" anywhere in my VS 2022 commands or keyboard shortcut editor, though I vaguely remember seeing it somewhere in the past. I wonder if it's been replaced with Ctrl+;?

the constructor for KnownFolderManager isn't a typical one... (...) the win32metadata from which code generation runs, the class is just a struct that doesn't implement the interface. And that in turn is because in the win32 header files (I suspect) there is no such interface implemented on the KnownFolderManager type.

Just complaining about it here may help someone find the solution to my problem in the future, so thanks to both of us. ;)
I wonder though if there could be a way to augment some of the information found in the headers and other sources of metadata to make life a bit easier. Maybe by updating the original headers themselves? :)

This isn't to say unsafe is actually safe, but interop in general is not "safe", and avoiding the C# unsafe keyword shouldn't give you anything like a feeling of safety.

I know. I often feel particularly anxious when reading the Win32 documentation and seeing some of it mentioning who's allocating memory and who's responsible for freeing up blocks of memory passed into/out of a particular function and remembering I almost never pay much attention to do the right thing and in typical C# carefree way - just leave it up to when it starts being a problem at some point in the future that usually never happens since most of these APIs just generate small strings which takes ages to manifest as a noticeable, problematic leak. :)

... we may offer more method overloads to make string work more naturally.
For structs however, we have fewer options. We only want to define a struct once ...

I wonder if you could add something in the documentation attached to the generated wrappers showing an example of a default way to translate between .NET and unsafe types. I guess it could be problematic since some of these require more information than the metadata itself provides. Maybe there are just a few categories and you could also include a disclaimer to suggest checking the documentation to determine which way is the right way...

As-is - I have code that works, but I am a bit clueless of whether it's done right and until it starts causing problems I probably won't have the time to study the details of and best practices of using pinvoke and marshalling. This takes a WinAPI CodePack ShellObject generated for shell:AppsFolder and tries to invoke shell's "open" verb on it and has worked OK in my testing... so far. :) Am I "holding it right" or is there a better or simpler way?

internal static void Open(ShellObject shellObject)
{
    var appUserModelId = shellObject.Properties.GetProperty("System.AppUserModel.ID").ValueAsObject.ToString();
    var url = $"shell:AppsFolder\\{appUserModelId}";

    unsafe
    {
        fixed (char* urlPtr = url)
        fixed (char* verbPtr = "open")
        {
            ShellExecute(
                new HWND(),
                new PCWSTR(verbPtr),
                new PCWSTR(urlPtr),
                new PCWSTR(),
                new PCWSTR(),
                SW_SHOWNORMAL);
        }
    }
}

One caution to add in general: pinvoke.net or stackoverflow code may appear to work for you, but from what I've observed it is often incorrect. It may work well enough on an x64 machine for your use case, but it may fail in x86 or arm64 processes. For example if the native header had a pointer and your C# declaration replaces that with long, it'll work on x64 but fail on x86. There are many even more subtle bugs than that.

This is exactly something I'd like to learn myself how to do better with. Most of my C# is for my own use, for prototypes or other controlled environments where I can support the users directly, but if I were to transition to write more production code with C# - I'd like to equip myself with knowledge on how to do it right. x86 may be staying mostly in the past, but arm64 seems like more and more of something needing consideration. Now where do I go to learn how to handle these things right? Does CsWin32 pick the right library version for a specific platform I'm compiling? What does it do for AnyCPU - pick x86 by default or do the library names just match or...?

Thanks for responding and helping make C# devs' lives (even) easier... eventually. :)
I'd love to help contribute to that if only by providing feedback and expanding consideration for the breadth of diverse perspectives of different categories of users of CsWin32.

[xyzzer]

The README includes an animated gif that shows how to find these generated files. Did you notice that or was it just not helpful?

I may have overlooked it earlier. The font size is a bit too small to follow for the pace of things presented when shrunk to fit in the browser window. Maybe breaking it down to a few Win+Shift+S's with descriptions of what's going on could make it easier.

[AArnott]

Strange, I'm not finding "Navigate To" anywhere in my VS 2022 commands

Oh, I forgot it was renamed to "Go To All".

Maybe by updating the original headers themselves? :)

That possibility does come up occasionally. I'm not sure it has ever been actually done in reaction to CsWin32 or win32metadata requirements. Changing win32 headers requires a great deal of care and review. But hacking something into win32metadata or CsWin32 can be done in half a day.

I almost never pay much attention to do the right thing and in typical C# carefree way

😵

Am I "holding it right" or is there a better or simpler way?

Yes, that looks fine.

I wonder if you could add something in the documentation attached to the generated wrappers showing an example of a default way to translate between .NET and unsafe types.

That's a good idea. CsWin32 can probably tell when it's generating structs that require careful handling, even if it can't automate that handling for you. So at the very least, it could add a <remarks> doc comment with a link to an online document with a growing set of examples that can help you get by.

arm64 seems like more and more of something needing consideration. Now where do I go to learn how to handle these things right? Does CsWin32 pick the right library version for a specific platform I'm compiling? What does it do for AnyCPU - pick x86 by default or do the library names just match or...?

CsWin32 should always emit code that will work in all your target environments. There are active bugs in this area, but on the whole it gets it right far more than I would trust pinvoke.net to do so. I'm quite an advanced C# programmer myself, yet there are very subtle interop/architecture concerns where I still lean heavily on interop experts to get it right, and our goal is for CsWin32 to embody all the very best from the experts so that we all can just use the APIs with only memory management to worry about.

As for AnyCPU, some APIs can't be declared when you're platform target is Any CPU (though you may never see that caveat disclosed on pinvoke.net, it is nonetheless true) because the APIs/structs themselves are actually defined differently in the header files across architectures. CsWin32 will generate for Any CPU any API you ask for that it can, but if you ask for it to generate something that requires a specific architecture, it'll emit a warning or error. At that point, you'll have to commit your project to one or more architectures, at which point CsWin32 will happily generate unique p/invoke methods and structs for each target architecture, and you can just code your app, typically without any arch-specific checks of your own.

I'd love to help contribute to that if only by providing feedback and expanding consideration for the breadth of diverse perspectives of different categories of users of CsWin32.

Yes, please do. I really appreciate your candor and enthusiasm.

The font size is a bit too small to follow for the pace of things presented when shrunk to fit in the browser window

I wondered about that. I'll see what I can do to fix it.

[Balkoth]

With CsWin32, the generated code will end up with your own C# code looking a lot like native code. So many of the samples that have been accumulating for decades for C/C++ will actually apply for C#.

Seems like you would count this as a positive, while i view this as a big negative. If C# developers wanted to write code that looks like C++, they can just switch to C++ and call it a day.

While with previous P/Invoke, C# devs could get away with basic C++ knowledge, using CsWin32 for the same task seems impossible if you are not an expert in both languages.

To me right now CsWin32 seems like a monster that only Microsoft employees can use, because there is little to no public documentation to CsWin32 available.

I am all for a library that can work with modern .net and PublishAot, so i hope someday there will be docs and samples available.