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

Author: mjr4077au

src/PSADT/PSADT.Interop/NETSETUP_JOIN_STATUS.cs

@@ -0,0 +1,33 @@
+namespace PSADT.Interop
+{
+    /// <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("Design", "CA1008:Enums should have zero value", Justification = "There is no zero value in the Win32 API for this.")]
+    [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.Interop/NativeMethods.cs

@@ -3726,6 +3726,37 @@ internal static uint DWRITE_MAKE_OPENTYPE_TAG(char a, char b, char c, char d)
             return (byte)a | ((uint)(byte)b << 8) | ((uint)(byte)c << 16) | ((uint)(byte)d << 24);
         }
 
+        /// <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)).ThrowOnFailure();
+            lpNameBuffer = new(lpNameBufferLocal.ToIntPtr().ThrowIfZeroOrMinusOne(), 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);
+        }
+
         /// <summary>
         /// Lookup table for system information class struct sizes.
         /// </summary>

src/PSADT/PSADT.Interop/NativeMethods.txt

@@ -175,6 +175,9 @@ MsiSummaryInfoGetProperty
 MsiViewExecute
 MsiViewFetch
 MsiViewModify
+NetApiBufferFree
+NetGetJoinInformation
+NETSETUP_JOIN_STATUS
 NtQueryInformationProcess
 NtQueryObject
 NtQuerySystemInformation

src/PSADT/PSADT.Interop/SafeHandles/SafeNetApiBufferFreeHandle.cs

@@ -0,0 +1,38 @@
+using System;
+using PSADT.Interop.Extensions;
+using Windows.Win32;
+using Windows.Win32.Foundation;
+
+namespace PSADT.Interop.SafeHandles
+{
+    /// <summary>
+    /// Provides a safe handle for memory buffers allocated by the Net API, ensuring that resources are properly
+    /// released when no longer needed.
+    /// </summary>
+    /// <remarks>This class inherits from SafeMemoryHandle and is designed to manage the lifetime of unmanaged
+    /// memory buffers allocated by the Net API. When the handle is released, the associated memory is freed using
+    /// NetApiBufferFree to prevent resource leaks.</remarks>
+    /// <param name="handle">The pointer to the memory buffer allocated by the Net API.</param>
+    /// <param name="length">The size, in bytes, of the memory buffer referenced by the handle.</param>
+    /// <param name="ownsHandle">A value indicating whether this instance is responsible for releasing the handle when it is no longer needed.</param>
+    internal sealed class SafeNetApiBufferFreeHandle(IntPtr handle, int length, bool ownsHandle) : SafeMemoryHandle<SafeNetApiBufferFreeHandle>(handle, length, ownsHandle)
+    {
+        /// <summary>
+        /// Releases the handle.
+        /// </summary>
+        /// <returns></returns>
+        protected override bool ReleaseHandle()
+        {
+            if (default == handle)
+            {
+                return true;
+            }
+            unsafe
+            {
+                _ = ((WIN32_ERROR)PInvoke.NetApiBufferFree((void*)handle)).ThrowOnFailure();
+            }
+            handle = default;
+            return true;
+        }
+    }
+}

src/PSADT/PSADT/DeviceManagement/DeviceUtilities.cs

@@ -2,6 +2,7 @@
 using System.IO;
 using System.Runtime.InteropServices;
 using PSADT.Interop;
+using PSADT.Interop.SafeHandles;
 using PSADT.ProcessManagement;
 using Windows.Win32;
 using Windows.Win32.Foundation;
@@ -128,5 +129,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()
+        {
+            _ = NativeMethods.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.Interop;
+
+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; }
+    }
+}