Add more examples to the docs (#1597)

jevansaks · web-flow · commit d8a1abcfc0ad · 2025-12-18T14:12:25.000-08:00
diff --git a/docfx/docs/Examples.md b/docfx/docs/Examples.md
@@ -2,17 +2,7 @@
 
 When, for example, marshaling is enabled and `useSafeHandles` is `true`, the code can be different than that in C++. Here we show a few code examples of using CsWin32.
 
-```json
-{
-  "$schema": "https://aka.ms/CsWin32.schema.json",
-  "useSafeHandles": false,
-  "comInterop": {
-    "preserveSigMethods": ["*"]
-  }
-}
-```
-
-## Scenario 1: Retrieving the last-write time
+## Retrieving the last-write time
 
 Based on: [Retrieving the Last-Write Time](https://learn.microsoft.com/en-us/windows/win32/sysinfo/retrieving-the-last-write-time)
 
@@ -29,7 +19,6 @@ MAX_PATH
 ```cs
 static void Main(string[] args)
 {
-    SafeHandle hFile;
     Span<char> szBuf = stackalloc char[(int)PInvoke.MAX_PATH];
 
     if (args.Length is not 1)
@@ -38,7 +27,7 @@ static void Main(string[] args)
         return;
     }
 
-    hFile = PInvoke.CreateFile(
+    using SafeHandle hFile = PInvoke.CreateFile(
         args[0],
         (uint)GENERIC_ACCESS_RIGHTS.GENERIC_READ,
         FILE_SHARE_MODE.FILE_SHARE_READ,
@@ -52,8 +41,6 @@ static void Main(string[] args)
 
     if (GetLastWriteTime(hFile, szBuf))
         Console.WriteLine("Last write time is: {0}\n", szBuf.ToString());
-
-    hFile.Close();
 }
 
 static unsafe bool GetLastWriteTime(SafeHandle hFile, Span<char> lpszString)
@@ -77,7 +64,7 @@ static unsafe bool GetLastWriteTime(SafeHandle hFile, Span<char> lpszString)
 }
 ```
 
-## Scenario 2: Retrieving information about all of the display monitors
+## Retrieving information about all of the display monitors
 
 ```
 EnumDisplayMonitors
@@ -130,7 +117,7 @@ static unsafe BOOL MonitorEnumProc(HMONITOR hMonitor, HDC hdcMonitor, RECT* lprc
 }
 ```
 
-## Scenario 3: Use of SHCreateItemFromParsingName
+## Use of SHCreateItemFromParsingName
 
 ```
 IShellItem
@@ -185,3 +172,152 @@ static unsafe void Main(string[] args)
     psi->Release();
 }
 ```
+
+## Using COM classes (NetFwMgr, INetFwMgr)
+
+In this example we see how to activate a COM class and call methods on it via its primary interface. When marshalling
+is enabled, we can use C# cast to do the "QueryInterface" that you would have seen in a native C++ sample.
+
+```
+NetFwMgr
+INetFwMgr
+IEnumVARIANT
+INetFwAuthorizedApplication
+```
+
+### Marshalling enabled (built-in COM Interop, not AOT-compatible)
+
+```cs
+var fwMgr = (INetFwMgr)new NetFwMgr();
+var authorizedApplications = fwMgr.LocalPolicy.CurrentProfile.AuthorizedApplications;
+var aaObjects = new object[authorizedApplications.Count];
+var applicationsEnum = (IEnumVARIANT)authorizedApplications._NewEnum;
+applicationsEnum.Next((uint)authorizedApplications.Count, aaObjects, out uint fetched);
+foreach (var aaObject in aaObjects)
+{
+    var app = (INetFwAuthorizedApplication)aaObject;
+    Console.WriteLine("---");
+    Console.WriteLine($"Name: {app.Name.ToString()}");
+    Console.WriteLine($"Enabled: {(bool)app.Enabled}");
+    Console.WriteLine($"Remote Addresses: {app.RemoteAddresses.ToString()}");
+    Console.WriteLine($"Scope: {app.Scope}");
+    Console.WriteLine($"Process Image Filename: {app.ProcessImageFileName.ToString()}");
+    Console.WriteLine($"IP Version: {app.IpVersion}");
+}
+```
+
+### Marshalling enabled (COM wrappers, AOT compatible)
+
+Note that in COM wrappers mode, the generated interfaces have get_ methods instead of properties. Some parameters
+are also ComVariant instead of object because source generated COM does not support as much automatic marshalling
+as built-in COM does.
+
+```cs
+var fwMgr = NetFwMgr.CreateInstance<INetFwMgr>();
+var authorizedApplications = fwMgr.get_LocalPolicy().get_CurrentProfile().get_AuthorizedApplications();
+var aaObjects = new ComVariant[authorizedApplications.get_Count()];
+var applicationsEnum = (IEnumVARIANT)authorizedApplications.get__NewEnum();
+applicationsEnum.Next((uint)authorizedApplications.get_Count(), aaObjects, out uint fetched);
+foreach (var aaObject in aaObjects)
+{
+    var app = (INetFwAuthorizedApplication)ComVariantMarshaller.ConvertToManaged(aaObject)!;
+
+    Console.WriteLine("---");
+    Console.WriteLine($"Name: {app.get_Name().ToString()}");
+    Console.WriteLine($"Enabled: {(bool)app.get_Enabled()}");
+    Console.WriteLine($"Remote Addresses: {app.get_RemoteAddresses().ToString()}");
+    Console.WriteLine($"Scope: {app.get_Scope()}");
+    Console.WriteLine($"Process Image Filename: {app.get_ProcessImageFileName().ToString()}");
+    Console.WriteLine($"IP Version: {app.get_IpVersion()}");
+
+    aaObject.Dispose();
+}
+```
+
+## Use PNP APIs (shows omitted optional params and cbSize-d struct)
+
+This sample shows how to call an API where we've omitted some optional params -- note that we must
+use named parameters when passing parameters past the omitted optional ones. This also shows how to
+use Span APIs, and in this case one where we first call the API to get the buffer size, create the buffer
+and then call again to populate the buffer.
+
+```
+SetupDiGetClassDevs
+SetupDiEnumDeviceInfo
+SetupDiGetDeviceInstanceId
+```
+
+```cs
+using SafeHandle hDevInfo = PInvoke.SetupDiGetClassDevs(
+    Flags: SETUP_DI_GET_CLASS_DEVS_FLAGS.DIGCF_ALLCLASSES | SETUP_DI_GET_CLASS_DEVS_FLAGS.DIGCF_PRESENT);
+
+var devInfo = new SP_DEVINFO_DATA { cbSize = (uint)sizeof(SP_DEVINFO_DATA) };
+
+uint index = 0;
+while (PInvoke.SetupDiEnumDeviceInfo(hDevInfo, index++, ref devInfo))
+{
+    PInvoke.SetupDiGetDeviceInstanceId(hDevInfo, in devInfo, RequiredSize: out uint requiredSize);
+
+    Span<char> instanceIdSpan = new char[(int)requiredSize];
+    PInvoke.SetupDiGetDeviceInstanceId(hDevInfo, in devInfo, instanceIdSpan);
+
+    Console.WriteLine($"Device {devInfo.ClassGuid} Instance ID: {instanceIdSpan.ToString()}");
+}
+```
+
+## Pass struct as a Span<byte>
+
+In this short example, we see how to pass a struct to a method that accepts a `Span<byte>`. `new Span<SHFILEINFOW>(ref fileInfo)` lets us
+get a `Span<SHFILEINFOW>` and then `MemoryMarshal.AsBytes` reinterprets that same Span as a `Span<byte>` with the expected size. The cswin32
+method will pass the Span's length to the native method as the "cb" count bytes parameter.
+
+```cs
+SHFILEINFOW fileInfo = default;
+PInvoke.SHGetFileInfo(
+    "c:\\windows\\notepad.exe",
+    FILE_FLAGS_AND_ATTRIBUTES.FILE_ATTRIBUTE_NORMAL,
+    MemoryMarshal.AsBytes(new Span<SHFILEINFOW>(ref fileInfo)),
+    SHGFI_FLAGS.SHGFI_DISPLAYNAME);
+```
+
+## Omitting optional out/ref parameters
+
+APIs with optional `in` parameters are tagged with `[Optional]` attribute and such parameters can be omitted, but APIs
+with optional `out` or `ref` parameters must always be passed. When the native method has these as `[optional]` and you need
+to pass _some_ but not all of those parameters, you can pass "null" to the native method using `ref Unsafe.NullRef<T>()`.
+
+This sample also shows passing `null` for SafeHandle-typed parameters which are not optional per the SDK headers but the
+implementation allows for them to be null.
+
+This sample shows a number of advanced COM marshalling scenarios
+
+### Marshalling enabled (COM wrappers, AOT compatible)
+
+```cs
+// CoCreateInstance CLSID_WbemLocator
+IWbemLocator locator = WbemLocator.CreateInstance<IWbemLocator>();
+
+var ns = new SysFreeStringSafeHandle(Marshal.StringToBSTR(@"ROOT\Microsoft\Windows\Defender"), true);
+locator.ConnectServer(ns, new SysFreeStringSafeHandle(), new SysFreeStringSafeHandle(), new SysFreeStringSafeHandle(), 0, new SafeFileHandle(), null, out IWbemServices services);
+
+unsafe
+{
+    PInvoke.CoSetProxyBlanket(
+            services,
+            10, // RPC_C_AUTHN_WINNT is 10
+            0,  // RPC_C_AUTHZ_NONE is 0
+            pServerPrincName: null,
+            dwAuthnLevel: RPC_C_AUTHN_LEVEL.RPC_C_AUTHN_LEVEL_CALL,
+            dwImpLevel: RPC_C_IMP_LEVEL.RPC_C_IMP_LEVEL_IMPERSONATE,
+            pAuthInfo: null,
+            dwCapabilities: EOLE_AUTHENTICATION_CAPABILITIES.EOAC_NONE);
+}
+
+var className = new SysFreeStringSafeHandle(Marshal.StringToBSTR("MSFT_MpScan"), true);
+IWbemClassObject? classObj = null; // out param
+
+services.GetObject(className, WBEM_GENERIC_FLAG_TYPE.WBEM_FLAG_RETURN_WBEM_COMPLETE, null, ref classObj, ref Unsafe.NullRef<IWbemCallResult>());
+
+classObj.GetMethod("Start", 0, out IWbemClassObject pInParamsSignature, out IWbemClassObject ppOutSignature);
+
+```
diff --git a/test/GenerationSandbox.BuildTask.Tests/COMTests.cs b/test/GenerationSandbox.BuildTask.Tests/COMTests.cs
@@ -4,20 +4,25 @@
 #pragma warning disable IDE0005
 #pragma warning disable SA1201, SA1512, SA1005, SA1507, SA1515, SA1403, SA1402, SA1411, SA1300, SA1313, SA1134, SA1307, SA1308, SA1202
 
+using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.Marshalling;
 using Microsoft.Win32.SafeHandles;
 using Windows.System;
 using Windows.UI.Composition;
 using Windows.Win32;
+using Windows.Win32.Devices.DeviceAndDriverInstallation;
 using Windows.Win32.Foundation;
 using Windows.Win32.Graphics.Direct2D;
 using Windows.Win32.Graphics.Direct2D.Common;
 using Windows.Win32.Graphics.Direct3D;
 using Windows.Win32.Graphics.Direct3D11;
 using Windows.Win32.Graphics.Dxgi.Common;
+using Windows.Win32.NetworkManagement.WindowsFirewall;
 using Windows.Win32.Storage.FileSystem;
 using Windows.Win32.System.Com;
+using Windows.Win32.System.Ole;
 using Windows.Win32.System.WinRT.Composition;
 using Windows.Win32.System.Wmi;
 using Windows.Win32.UI.Shell;
@@ -26,8 +31,10 @@
 namespace GenerationSandbox.BuildTask.Tests;
 
 [Trait("WindowsOnly", "true")]
-public partial class COMTests
+public partial class COMTests(ITestOutputHelper outputHelper)
 {
+    private ITestOutputHelper outputHelper = outputHelper;
+
     [Fact]
     public async Task CanInteropWithICompositorInterop()
     {
@@ -228,4 +235,58 @@ public void IWbemServices_GetObject_Works()
 
         Assert.NotNull(pInParamsSignature);
     }
+
+    [Fact]
+    [Trait("TestCategory", "FailsInCloudTest")]
+    public void CanCallINetFwMgrApis()
+    {
+        Assert.SkipUnless(RuntimeInformation.IsOSPlatform(OSPlatform.Windows), "Test calls Windows-specific APIs");
+
+        var fwMgr = NetFwMgr.CreateInstance<INetFwMgr>();
+        var authorizedApplications = fwMgr.get_LocalPolicy().get_CurrentProfile().get_AuthorizedApplications();
+
+        var aaObjects = new ComVariant[authorizedApplications.get_Count()];
+
+        var applicationsEnum = (IEnumVARIANT)authorizedApplications.get__NewEnum();
+        applicationsEnum.Next((uint)authorizedApplications.get_Count(), aaObjects, out uint fetched);
+
+        foreach (var aaObject in aaObjects)
+        {
+            var app = (INetFwAuthorizedApplication)ComVariantMarshaller.ConvertToManaged(aaObject)!;
+
+            this.outputHelper.WriteLine("---");
+            this.outputHelper.WriteLine($"Name: {app.get_Name().ToString()}");
+            this.outputHelper.WriteLine($"Enabled: {(bool)app.get_Enabled()}");
+            this.outputHelper.WriteLine($"Remote Addresses: {app.get_RemoteAddresses().ToString()}");
+            this.outputHelper.WriteLine($"Scope: {app.get_Scope()}");
+            this.outputHelper.WriteLine($"Process Image Filename: {app.get_ProcessImageFileName().ToString()}");
+            this.outputHelper.WriteLine($"IP Version: {app.get_IpVersion()}");
+
+            aaObject.Dispose();
+        }
+    }
+
+    [Fact]
+    [Trait("TestCategory", "FailsInCloudTest")]
+    public unsafe void CanCallPnPAPIs()
+    {
+        Assert.SkipUnless(RuntimeInformation.IsOSPlatform(OSPlatform.Windows), "Test calls Windows-specific APIs");
+
+        using SafeHandle hDevInfo = PInvoke.SetupDiGetClassDevs(
+            Flags: SETUP_DI_GET_CLASS_DEVS_FLAGS.DIGCF_ALLCLASSES | SETUP_DI_GET_CLASS_DEVS_FLAGS.DIGCF_PRESENT);
+
+        var devInfo = new SP_DEVINFO_DATA { cbSize = (uint)sizeof(SP_DEVINFO_DATA) };
+
+        uint index = 0;
+        while (PInvoke.SetupDiEnumDeviceInfo(hDevInfo, index++, ref devInfo))
+        {
+            // NOTE: Omitting DeviceInstanceId requires naming the RequiredSize parameter.
+            PInvoke.SetupDiGetDeviceInstanceId(hDevInfo, in devInfo, RequiredSize: out uint requiredSize);
+
+            Span<char> instanceIdSpan = new char[(int)requiredSize];
+            PInvoke.SetupDiGetDeviceInstanceId(hDevInfo, in devInfo, instanceIdSpan);
+
+            this.outputHelper.WriteLine($"Device {devInfo.ClassGuid} Instance ID: {instanceIdSpan.ToString()}");
+        }
+    }
 }
diff --git a/test/GenerationSandbox.BuildTask.Tests/NativeMethods.txt b/test/GenerationSandbox.BuildTask.Tests/NativeMethods.txt
@@ -76,4 +76,11 @@ InitializeProcThreadAttributeList
 UpdateProcThreadAttribute
 DeleteProcThreadAttributeList 
 PROC_THREAD_ATTRIBUTE_MACHINE_TYPE
-FwpmProviderAdd0
+FwpmProviderAdd0
+INetFwMgr
+NetFwMgr
+IEnumVARIANT
+INetFwAuthorizedApplication
+SetupDiGetClassDevs
+SetupDiEnumDeviceInfo
+SetupDiGetDeviceInstanceId
diff --git a/test/GenerationSandbox.Tests/ComRuntimeTests.cs b/test/GenerationSandbox.Tests/ComRuntimeTests.cs
@@ -9,14 +9,18 @@
 using Windows.Win32.Graphics.Direct2D;
 using Windows.Win32.Graphics.Direct2D.Common;
 using Windows.Win32.Graphics.Dxgi.Common;
+using Windows.Win32.NetworkManagement.WindowsFirewall;
 using Windows.Win32.System.Com;
+using Windows.Win32.System.Ole;
 using Windows.Win32.System.Wmi;
 using Windows.Win32.UI.Shell;
 using Windows.Win32.UI.WindowsAndMessaging;
 using IServiceProvider = Windows.Win32.System.Com.IServiceProvider;
 
-public class ComRuntimeTests
+public class ComRuntimeTests(ITestOutputHelper outputHelper)
 {
+    private ITestOutputHelper outputHelper = outputHelper;
+
     [Fact]
     [Trait("TestCategory", "FailsInCloudTest")]
     public void RemotableInterface()
@@ -182,4 +186,32 @@ public void CanCallIDispatchOnlyMethods()
 
         _ = folderView.Application; // Throws InvalidOleVariantTypeException "Specified OLE variant is invalid"
     }
+
+    [Fact]
+    [Trait("TestCategory", "FailsInCloudTest")]
+    public void CanCallINetFwMgrApis()
+    {
+        Assert.SkipUnless(RuntimeInformation.IsOSPlatform(OSPlatform.Windows), "Test calls Windows-specific APIs");
+
+        var fwMgr = (INetFwMgr)new NetFwMgr();
+        var authorizedApplications = fwMgr.LocalPolicy.CurrentProfile.AuthorizedApplications;
+
+        var aaObjects = new object[authorizedApplications.Count];
+
+        var applicationsEnum = (IEnumVARIANT)authorizedApplications._NewEnum;
+        applicationsEnum.Next((uint)authorizedApplications.Count, aaObjects, out uint fetched);
+
+        foreach (var aaObject in aaObjects)
+        {
+            var app = (INetFwAuthorizedApplication)aaObject;
+
+            this.outputHelper.WriteLine("---");
+            this.outputHelper.WriteLine($"Name: {app.Name.ToString()}");
+            this.outputHelper.WriteLine($"Enabled: {(bool)app.Enabled}");
+            this.outputHelper.WriteLine($"Remote Addresses: {app.RemoteAddresses.ToString()}");
+            this.outputHelper.WriteLine($"Scope: {app.Scope}");
+            this.outputHelper.WriteLine($"Process Image Filename: {app.ProcessImageFileName.ToString()}");
+            this.outputHelper.WriteLine($"IP Version: {app.IpVersion}");
+        }
+    }
 }
diff --git a/test/GenerationSandbox.Tests/NativeMethods.txt b/test/GenerationSandbox.Tests/NativeMethods.txt
@@ -100,4 +100,8 @@ RPC_C_IMP_LEVEL
 IShellFolderViewDual
 SID_STopLevelBrowser
 IShellBrowser
-_SVGIO
+_SVGIO
+INetFwMgr
+NetFwMgr
+IEnumVARIANT
+INetFwAuthorizedApplication
