NetBios: fixes #434, added two functions to common.

CHANGELOG.md

@@ -5,6 +5,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- NetBios
+  - Fixes configuring network adapters in a disconnected or disabled state - fixes [Issue #434](https://github.com/dsccommunity/NetworkingDsc/issues/434).
+
 ## [8.2.0] - 2020-10-16
 
 ### Changed

source/DSCResources/DSC_NetBios/DSC_NetBios.psm1

@@ -10,6 +10,9 @@ Import-Module -Name (Join-Path -Path $modulePath -ChildPath 'DscResource.Common'
 # Import Localization Strings
 $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
 
+# Base registry key path for NetBios settings
+$script:hklmInterfacesPath = 'HKLM:\SYSTEM\CurrentControlSet\Services\NetBT\Parameters\Interfaces'
+
 #region check NetBiosSetting enum loaded, if not load
 try
 {
@@ -78,37 +81,37 @@ function Get-TargetResource
     <#
         If a wildcard was specified for the InterfaceAlias then
         more than one adapter may be returned. If more than one
-        adapter is returned then the NetBiosSetting value should
-        be returned for the first adapter that does not match
-        the desired value. This is to ensure that when testing
-        the resource state it will return a mismatch if any adapters
-        don't have the correct setting.
+        adapter is returned then the NetBios setting value will
+        be evaluated for all matching adapters. If there is a
+        mismatch, a wrong value is returned to signify the
+        resource is not in the desired state.
     #>
-    foreach ($netAdapterItem in $netAdapter)
+    if ($netAdapter -is [System.Array])
     {
-        $netAdapterConfig = $netAdapterItem | Get-CimAssociatedInstance `
-            -ResultClassName Win32_NetworkAdapterConfiguration `
-            -ErrorAction Stop
-
-        $tcpipNetbiosOptions = $netAdapterConfig.TcpipNetbiosOptions
+        [System.String[]] $settingResults = @()
 
-        if ($tcpipNetbiosOptions)
-        {
-            $interfaceSetting = $([NetBiosSetting].GetEnumValues()[$tcpipNetbiosOptions])
-        }
-        else
+        foreach ($netAdapterItem in $netAdapter)
         {
-            $interfaceSetting = 'Default'
+            $settingResults += Get-NetAdapterNetbiosOptionsFromRegistry -NetworkAdapterGUID $netAdapterItem.GUID -Setting $Setting
+
+            Write-Verbose -Message ($script:localizedData.CurrentNetBiosSettingMessage -f $netAdapterItem.NetConnectionID, $settingResults[-1])
         }
 
-        Write-Verbose -Message ($script:localizedData.CurrentNetBiosSettingMessage -f $netAdapterItem.Name, $interfaceSetting)
+        [System.String[]] $wrongSettings = $settingResults | Where-Object -FilterScript {
+            $_ -ne $Setting
+        }
 
-        if ($interfaceSetting -ne $Setting)
+        if (-not [System.String]::IsNullOrEmpty($wrongSettings))
         {
-            $Setting = $interfaceSetting
-            break
+            $Setting = $wrongSettings[0]
         }
     }
+    else
+    {
+        $Setting = Get-NetAdapterNetbiosOptionsFromRegistry -NetworkAdapterGUID $netAdapter.GUID -Setting $Setting
+    }
+
+    Write-Verbose -Message ($script:localizedData.CurrentNetBiosSettingMessage -f $InterfaceAlias, $Setting)
 
     return @{
         InterfaceAlias = $InterfaceAlias
@@ -160,43 +163,39 @@ function Set-TargetResource
             -Message ($script:localizedData.InterfaceNotFoundError -f $InterfaceAlias)
     }
 
-    foreach ($netAdapterItem in $netAdapter)
+    if ($netAdapter -is [System.Array])
     {
-        $netAdapterConfig = $netAdapterItem | Get-CimAssociatedInstance `
-            -ResultClassName Win32_NetworkAdapterConfiguration `
-            -ErrorAction Stop
-
-        if ($Setting -eq [NetBiosSetting]::Default)
+        foreach ($netAdapterItem in $netAdapter)
         {
-            Write-Verbose -Message ($script:localizedData.ResetToDefaultMessage -f $netAdapterItem.Name)
+            $currentValue = Get-NetAdapterNetbiosOptionsFromRegistry -NetworkAdapterGUID $netAdapterItem.GUID -Setting $Setting
 
-            # If DHCP is not enabled, SetTcpipNetbios CIM Method won't take 0 so overwrite registry entry instead.
-            $setItemPropertyParameters = @{
-                Path  = "HKLM:\SYSTEM\CurrentControlSet\Services\NetBT\Parameters\Interfaces\Tcpip_$($NetAdapterConfig.SettingID)"
-                Name  = 'NetbiosOptions'
-                Value = 0
-            }
-            $null = Set-ItemProperty @setItemPropertyParameters
-        }
-        else
-        {
-            Write-Verbose -Message ($script:localizedData.SetNetBiosMessage -f $netAdapterItem.Name, $Setting)
+            # Only make changes if necessary
+            if ($currentValue -ne $Setting)
+            {
+                Write-Verbose -Message ($script:localizedData.SetNetBiosMessage -f $netAdapterItem.NetConnectionID, $Setting)
 
-            $result = $netAdapterConfig |
-                Invoke-CimMethod `
-                    -MethodName SetTcpipNetbios `
-                    -ErrorAction Stop `
-                    -Arguments @{
-                        TcpipNetbiosOptions = [uint32][NetBiosSetting]::$Setting.value__
-                    }
+                $netAdapterConfig = $netAdapterItem | Get-CimAssociatedInstance `
+                    -ResultClassName Win32_NetworkAdapterConfiguration `
+                    -ErrorAction Stop
 
-            if ($result.ReturnValue -ne 0)
-            {
-                New-InvalidOperationException `
-                    -Message ($script:localizedData.FailedUpdatingNetBiosError -f $netAdapterItem.Name, $result.ReturnValue, $Setting)
+                Set-NetAdapterNetbiosOptions -NetworkAdapterObject $netAdapterConfig `
+                                             -InterfaceAlias $netAdapterItem.NetConnectionID `
+                                             -Setting $Setting
             }
         }
     }
+    else
+    {
+        Write-Verbose -Message ($script:localizedData.SetNetBiosMessage -f $netAdapter.NetConnectionID, $Setting)
+
+        $netAdapterConfig = $netAdapter | Get-CimAssociatedInstance `
+                    -ResultClassName Win32_NetworkAdapterConfiguration `
+                    -ErrorAction Stop
+
+        Set-NetAdapterNetbiosOptions -NetworkAdapterObject $netAdapterConfig `
+                                     -InterfaceAlias $netAdapter.NetConnectionID `
+                                     -Setting $Setting
+    }
 }
 
 <#
@@ -233,4 +232,154 @@ function Test-TargetResource
     return Test-DscParameterState -CurrentValues $currentState -DesiredValues $PSBoundParameters
 }
 
+<#
+    .SYNOPSIS
+        Returns the NetbiosOptions value for a network adapter.
+
+    .DESCRIPTION
+        Most reliable method of getting this value since network adapters
+        can be in any number of states (e.g. disabled, disconnected)
+        which can cause Win32 classes to not report the value.
+
+    .PARAMETER NetworkAdapterGUID
+        Network Adapter GUID
+
+    .PARAMETER Setting
+        Setting value for this resource which should be one of
+        the following: Default, Enable, Disable
+#>
+function Get-NetAdapterNetbiosOptionsFromRegistry
+{
+    [OutputType([System.String])]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidatePattern("^\{[a-zA-Z0-9]{8}\-[a-zA-Z0-9]{4}\-[a-zA-Z0-9]{4}\-[a-zA-Z0-9]{4}\-[a-zA-Z0-9]{12}\}$")]
+        [System.String]
+        $NetworkAdapterGUID,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Default','Enable','Disable')]
+        [System.String]
+        $Setting
+    )
+
+    # Changing ErrorActionPreference variable since the switch -ErrorAction isn't supported.
+    $currentErrorActionPreference = $ErrorActionPreference
+    $ErrorActionPreference = 'SilentlyContinue'
+
+    $registryNetbiosOptions = Get-ItemPropertyValue -Name 'NetbiosOptions' `
+                    -Path "$($script:hklmInterfacesPath)\Tcpip_$($NetworkAdapterGUID)"
+
+    $ErrorActionPreference = $currentErrorActionPreference
+
+    if ($null -eq $registryNetbiosOptions)
+    {
+        $registryNetbiosOptions = 0
+    }
+
+    switch ($registryNetbiosOptions)
+    {
+        0
+        {
+            return 'Default'
+        }
+
+        1
+        {
+            return 'Enable'
+        }
+
+        2
+        {
+            return 'Disable'
+        }
+
+        default
+        {
+            # Unknown value. Returning invalid setting to trigger Set-TargetResource
+            [System.String[]] $invalidSetting = 'Default','Enable','Disable' | Where-Object -FilterScript {
+                $_ -ne $Setting
+            }
+
+            return $invalidSetting[0]
+        }
+    }
+} # end function Get-NetAdapterNetbiosOptionsFromRegistry
+
+<#
+    .SYNOPSIS
+        Configures Netbios on a Network Adapter.
+
+    .DESCRIPTION
+        Uses two methods for configuring Netbios on a Network Adapter.
+        If an interface is IPEnabled, the CIMMethod will be invoked.
+        Otherwise the registry key is configured as this will satisfy
+        network adapters being in alternative states such as disabled
+        or disconnected.
+
+    .PARAMETER NetworkAdapterObject
+        Network Adapter Win32_NetworkAdapterConfiguration Object
+
+    .PARAMETER InterfaceAlias
+        Name of the network adapter being configured. Example: Ethernet
+
+    .PARAMETER Setting
+        Setting value for this resource which should be one of
+        the following: Default, Enable, Disable
+#>
+function Set-NetAdapterNetbiosOptions
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.Object]
+        $NetworkAdapterObject,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $InterfaceAlias,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Default','Enable','Disable')]
+        [System.String]
+        $Setting
+    )
+
+    Write-Verbose -Message ($script:localizedData.SetNetBiosMessage -f $InterfaceAlias, $Setting)
+
+    # Only IPEnabled interfaces can be configured via SetTcpipNetbios method.
+    if ($NetworkAdapterObject.IPEnabled)
+    {
+        $result = $NetworkAdapterObject |
+            Invoke-CimMethod `
+                -MethodName SetTcpipNetbios `
+                -ErrorAction Stop `
+                -Arguments @{
+                    TcpipNetbiosOptions = [uint32][NetBiosSetting]::$Setting.value__
+                }
+
+        if ($result.ReturnValue -ne 0)
+        {
+            New-InvalidOperationException `
+                -Message ($script:localizedData.FailedUpdatingNetBiosError -f $InterfaceAlias, $result.ReturnValue, $Setting)
+        }
+    }
+    else
+    {
+        <#
+            IPEnabled=$false can only be configured via registry
+            this satisfies disabled and disconnected states
+        #>
+        $setItemPropertyParameters = @{
+            Path  = "$($script:hklmInterfacesPath)\Tcpip_$($NetworkAdapterObject.SettingID)"
+            Name  = 'NetbiosOptions'
+            Value = [NetBiosSetting]::$Setting.value__
+        }
+        $null = Set-ItemProperty @setItemPropertyParameters
+    }
+} # end function Set-NetAdapterNetbiosOptions
+
 Export-ModuleMember -Function *-TargetResource

source/DSCResources/DSC_NetBios/en-US/DSC_NetBios.strings.psd1

@@ -4,7 +4,6 @@ ConvertFrom-StringData @'
     GettingNetBiosSettingMessage = Getting NetBIOS configuration for Interface '{0}'.
     InterfaceDetectedMessage = Interface '{0}' detected with Index number {1}.
     SettingNetBiosSettingMessage = Setting NetBIOS configuration for Interface '{0}'.
-    ResetToDefaultMessage = NetBIOS configuration for Interface '{0}' will be reset to default.
     SetNetBiosMessage = NetBIOS configuration for Interface '{0}' will be set to '{1}'.
     TestingNetBiosSettingMessage = Testing NetBIOS configuration for Interface '{0}'.
     CurrentNetBiosSettingMessage = Current NetBIOS configuration for Interface '{0}' is '{1}'.