Add in C#-based method to retrieve domain information as part of CIM code removal.

Author: mjr4077au

src/PSADT/PSADT.LibraryInterfaces/LmJoin.cs

@@ -0,0 +1,32 @@
+namespace PSADT.LibraryInterfaces
+{
+    /// <summary>
+    /// Specifies the status of a computer's membership in a workgroup or domain.
+    /// </summary>
+    /// <remarks>This enumeration is typically used to indicate whether a computer is joined to a domain, a
+    /// workgroup, or is unjoined. The values correspond to the possible states returned by network management APIs when
+    /// querying the join status of a system.</remarks>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1707:Identifiers should not contain underscores", Justification = "This is named as per the Win32 API.")]
+    public enum NETSETUP_JOIN_STATUS
+    {
+        /// <summary>
+        /// Domain join status of the machine is unknown.
+        /// </summary>
+        NetSetupUnknownStatus = Windows.Win32.NetworkManagement.NetManagement.NETSETUP_JOIN_STATUS.NetSetupUnknownStatus,
+
+        /// <summary>
+        /// Machine is not joined to a domain or to a workgroup.
+        /// </summary>
+        NetSetupUnjoined = Windows.Win32.NetworkManagement.NetManagement.NETSETUP_JOIN_STATUS.NetSetupUnjoined,
+
+        /// <summary>
+        /// Machine is joined to a workgroup.
+        /// </summary>
+        NetSetupWorkgroupName = Windows.Win32.NetworkManagement.NetManagement.NETSETUP_JOIN_STATUS.NetSetupWorkgroupName,
+
+        /// <summary>
+        /// Machine is joined to a domain.
+        /// </summary>
+        NetSetupDomainName = Windows.Win32.NetworkManagement.NetManagement.NETSETUP_JOIN_STATUS.NetSetupDomainName,
+    }
+}

src/PSADT/PSADT.LibraryInterfaces/NativeMethods.txt

@@ -155,6 +155,10 @@ MsiGetLastErrorRecord
 MsiGetSummaryInformation
 MsiOpenDatabase
 MsiSummaryInfoGetProperty
+NERR_Success
+NetApiBufferFree
+NetGetJoinInformation
+NETSETUP_JOIN_STATUS
 NtQueryInformationProcess
 NtQueryObject
 NtQuerySystemInformation

src/PSADT/PSADT.LibraryInterfaces/NetApi32.cs

@@ -0,0 +1,55 @@
+using System;
+using PSADT.LibraryInterfaces.SafeHandles;
+using PSADT.LibraryInterfaces.Utilities;
+using Windows.Win32;
+using Windows.Win32.Foundation;
+
+namespace PSADT.LibraryInterfaces
+{
+    /// <summary>
+    /// Provides interop methods for querying network join information on Windows systems.
+    /// </summary>
+    /// <remarks>This class contains static methods that wrap native Windows networking APIs. It is intended
+    /// for internal use and is not thread-safe. Callers are responsible for managing any unmanaged resources returned
+    /// by these methods, such as releasing buffer handles to prevent memory leaks.</remarks>
+    internal static class NetApi32
+    {
+        /// <summary>
+        /// Retrieves the join status and name of the domain or workgroup for the specified computer.
+        /// </summary>
+        /// <remarks>The caller must release the buffer referenced by lpNameBuffer to avoid memory leaks.
+        /// This method throws an exception if the underlying Windows API call fails.</remarks>
+        /// <param name="lpServer">The name of the remote server to query, or null to specify the local computer. The name must begin with \\
+        /// if specified.</param>
+        /// <param name="lpNameBuffer">When this method returns, contains a handle to a buffer that receives the name of the domain or workgroup.
+        /// The caller is responsible for releasing this handle.</param>
+        /// <param name="BufferType">When this method returns, contains a value that indicates the join status of the computer.</param>
+        /// <returns>A WIN32_ERROR value that indicates the result of the operation. Returns NERR_Success if successful.</returns>
+        internal static WIN32_ERROR NetGetJoinInformation(string? lpServer, out SafeNetApiBufferFreeHandle lpNameBuffer, out Windows.Win32.NetworkManagement.NetManagement.NETSETUP_JOIN_STATUS BufferType)
+        {
+            WIN32_ERROR res = (WIN32_ERROR)PInvoke.NetGetJoinInformation(lpServer, out PWSTR lpNameBufferLocal, out BufferType);
+            if (res != PInvoke.NERR_Success)
+            {
+                throw ExceptionUtilities.GetExceptionForLastWin32Error(res);
+            }
+            unsafe
+            {
+                lpNameBuffer = new((IntPtr)lpNameBufferLocal.Value, lpNameBufferLocal.Length, true);
+            }
+            return res;
+        }
+
+        /// <summary>
+        /// Retrieves information about the join status of the local computer to a domain or workgroup.
+        /// </summary>
+        /// <param name="lpNameBuffer">When this method returns, contains a handle to a buffer that receives the name of the domain or workgroup.
+        /// The caller is responsible for freeing this buffer.</param>
+        /// <param name="BufferType">When this method returns, contains a value that specifies the join status of the local computer.</param>
+        /// <returns>A WIN32_ERROR value that indicates the result of the operation. Returns ERROR_SUCCESS if the information is
+        /// retrieved successfully; otherwise, returns a system error code.</returns>
+        internal static WIN32_ERROR NetGetJoinInformation(out SafeNetApiBufferFreeHandle lpNameBuffer, out Windows.Win32.NetworkManagement.NetManagement.NETSETUP_JOIN_STATUS BufferType)
+        {
+            return NetGetJoinInformation(null, out lpNameBuffer, out BufferType);
+        }
+    }
+}

src/PSADT/PSADT.LibraryInterfaces/SafeHandles/SafeMemoryHandle.cs

@@ -65,7 +65,8 @@ internal TSelf FromStructure<T>(T structure, bool fDeleteOld, int offset = 0) wh
         internal string? ToStringUni(int offset = 0)
         {
             ConfirmStateValidity(offset);
-            return Marshal.PtrToStringUni(handle + offset);
+            string? ret = Marshal.PtrToStringUni(handle + offset);
+            return !string.IsNullOrWhiteSpace(ret) ? ret : null;
         }
 
         /// <summary>

src/PSADT/PSADT.LibraryInterfaces/SafeHandles/SafeNetApiBufferFreeHandle.cs

@@ -0,0 +1,47 @@
+using System;
+using PSADT.LibraryInterfaces.Utilities;
+using Windows.Win32;
+using Windows.Win32.Foundation;
+
+namespace PSADT.LibraryInterfaces.SafeHandles
+{
+    /// <summary>
+    /// Provides a safe handle for buffers allocated by Windows network management APIs that must be freed using
+    /// NetApiBufferFree.
+    /// </summary>
+    /// <remarks>This handle ensures that the associated unmanaged memory is released using NetApiBufferFree
+    /// when the handle is disposed or finalized. Use this class to safely manage buffers returned by Windows network
+    /// management functions that require explicit deallocation.</remarks>
+    /// <param name="handle">The pointer to the unmanaged buffer to be managed by the handle.</param>
+    /// <param name="length">The length, in bytes, of the buffer referenced by the handle.</param>
+    /// <param name="ownsHandle">true to reliably release the handle during finalization; otherwise, false.</param>
+    internal sealed class SafeNetApiBufferFreeHandle(IntPtr handle, int length, bool ownsHandle) : SafeMemoryHandle<SafeNetApiBufferFreeHandle>(handle, length, ownsHandle)
+    {
+        /// <summary>
+        /// Releases the handle associated with the unmanaged resource.
+        /// </summary>
+        /// <remarks>This method is called by the runtime to free the unmanaged memory buffer when the
+        /// handle is no longer needed. If the handle is already invalid or zero, the method returns true without
+        /// performing any operation. An exception is thrown if the underlying buffer cannot be freed
+        /// successfully.</remarks>
+        /// <returns>true if the handle is released successfully; otherwise, false.</returns>
+        protected override bool ReleaseHandle()
+        {
+            if (handle == default || IntPtr.Zero == handle)
+            {
+                return true;
+            }
+            WIN32_ERROR res;
+            unsafe
+            {
+                res = (WIN32_ERROR)PInvoke.NetApiBufferFree((void*)handle);
+            }
+            if (res != PInvoke.NERR_Success)
+            {
+                throw ExceptionUtilities.GetExceptionForLastWin32Error(res);
+            }
+            handle = default;
+            return true;
+        }
+    }
+}

src/PSADT/PSADT/DeviceManagement/DeviceUtilities.cs

@@ -2,6 +2,7 @@
 using System.IO;
 using PSADT.LibraryInterfaces;
 using PSADT.LibraryInterfaces.Extensions;
+using PSADT.LibraryInterfaces.SafeHandles;
 using PSADT.ProcessManagement;
 using Windows.Win32;
 using Windows.Win32.Foundation;
@@ -88,5 +89,19 @@ public static DateTime GetSystemBootTime()
         {
             return DateTime.Now - GetSystemUptime();
         }
+
+        /// <summary>
+        /// Retrieves the current domain join status and associated domain or workgroup name of the local computer.
+        /// </summary>
+        /// <returns>A <see cref="DomainStatus"/> object containing the join status and the name of the domain or workgroup the
+        /// computer is joined to.</returns>
+        public static DomainStatus GetDomainStatus()
+        {
+            _ = NetApi32.NetGetJoinInformation(out SafeNetApiBufferFreeHandle? nameBuffer, out Windows.Win32.NetworkManagement.NetManagement.NETSETUP_JOIN_STATUS bufferType);
+            using (nameBuffer)
+            {
+                return new((NETSETUP_JOIN_STATUS)bufferType, nameBuffer.ToStringUni());
+            }
+        }
     }
 }

src/PSADT/PSADT/DeviceManagement/DomainStatus.cs

@@ -0,0 +1,36 @@
+using PSADT.LibraryInterfaces;
+
+namespace PSADT.DeviceManagement
+{
+    /// <summary>
+    /// Represents the domain or workgroup join status of a computer, including the associated domain or workgroup name
+    /// if applicable.
+    /// </summary>
+    /// <remarks>Use this type to determine whether a computer is joined to a domain, a workgroup, or is
+    /// unjoined, and to retrieve the corresponding domain or workgroup name when available. This record is
+    /// immutable.</remarks>
+    public sealed record DomainStatus
+    {
+        /// <summary>
+        /// Initializes a new instance of the DomainStatus class with the specified join status and domain or workgroup
+        /// name.
+        /// </summary>
+        /// <param name="joinStatus">The status indicating whether the computer is joined to a domain, a workgroup, or is unjoined.</param>
+        /// <param name="domainOrWorkgroupName">The name of the domain or workgroup associated with the current join status, or null if not applicable.</param>
+        public DomainStatus(NETSETUP_JOIN_STATUS joinStatus, string? domainOrWorkgroupName)
+        {
+            JoinStatus = joinStatus;
+            DomainOrWorkgroupName = domainOrWorkgroupName;
+        }
+
+        /// <summary>
+        /// Gets the status of the computer's domain or workgroup join operation.
+        /// </summary>
+        public NETSETUP_JOIN_STATUS JoinStatus { get; }
+
+        /// <summary>
+        /// Gets the name of the domain or workgroup to which the computer belongs.
+        /// </summary>
+        public string? DomainOrWorkgroupName { get; }
+    }
+}