update docs

resources/Dependency.json

@@ -0,0 +1,38 @@
+{
+    "Version": 0.1,
+    "Mandatory": {},
+    "Optional": [
+        {
+            "Name": "foobar2000",
+            "Modules": [
+                "foobar2000"
+            ]
+        },
+        {
+            "Name": "foo",
+            "Modules": [
+                "foo",
+                "bar"
+            ]
+        },
+        {
+            "Name": "bar",
+            "Modules": [
+                "bar"
+            ]
+        },
+        {
+            "Name": "Existing",
+            "Modules": [
+                "PowerShellGet"
+            ]
+        },
+        {
+            "Name": "PSGetMixed",
+            "Modules": [
+                "PowerShellGet",
+                "foobar2000"
+            ]
+        }
+    ]
+}

src/Connection/Connect-To.ps1

@@ -130,6 +130,12 @@ function Connect-To {
             }
         }
 
+        # First check the optional modules
+        if (-not (Resolve-Dependency -Name $Type)) {
+            Write-Error -Message (
+                "Could not resolve the optional dependencies defined for {0}" -f $Type
+            ) -ErrorAction 'Stop'
+        }
         switch ($Type) {
             "VMware" {
                 # Disable the yellow certificate warning, since we haven't replaced the SSL certs for vCenter/ESXi

src/PSCredentialStore.psd1

@@ -143,32 +143,7 @@
             # RequireLicenseAcceptance = $false
 
             # External dependent modules of this module
-            ExternalModuleDependencies = @(
+            # ExternalModuleDependencies = @()
-                @{
-                    ModuleName = 'VMware.VimAutomation.Core'
-                    ModuleVersion = '6.5.2.6234650'
-                },
-                @{
-                    ModuleName = 'VMware.VimAutomation.Cis.Core'
-                    ModuleVersion = '6.5.4.6983166'
-                },
-                @{
-                    ModuleName = 'Cisco.UCS.Core'
-                    ModuleVersion = '2.3.1.5'
-                },
-                @{
-                    ModuleName = 'Cisco.UCSManager'
-                    ModuleVersion = '2.5.2.2'
-                },
-                @{
-                    ModuleName = 'WinSCP'
-                    ModuleVersion = '5.17.8.1'
-                },
-                @{
-                    ModuleName = 'DataONTAP'
-                    ModuleVersion = '9.7.1.1'
-                }
-            )
 
         } # End of PSData hashtable
 

src/Private/Resolve-Dependency.Tests.ps1

@@ -0,0 +1,60 @@
+BeforeAll {
+    $ManifestFile = (Get-Item -Path "./src/*.psd1").FullName
+    Import-Module $ManifestFile -Force
+
+    $PrivateFunctions = (Get-ChildItem -Path "./src/Private/*.ps1" | Where-Object {
+            $_.BaseName -notmatch '.Tests'
+        }
+    ).FullName
+    foreach ( $func in $PrivateFunctions) {
+        . $func
+    }
+}
+
+Describe "Resolve-Dependency" {
+    Context "Basic syntax check" {
+        BeforeAll {
+            Mock  Get-ModuleBase {
+                return (Join-Path -Path $PWD -ChildPath '/resources')
+            }
+            Mock Test-Module {
+                return $true
+            }
+        }
+
+        It "Test1: Should not throw" {
+            { Resolve-Dependency -Name 'foobar2000' } | Should -Not -Throw
+        }
+        It "Test2: Output type should be bool" {
+            Resolve-Dependency -Name 'foobar2000' | Should -BeOfType bool
+        }
+    }
+    Context "Enforce Error" {
+        # Return incorrect module base to enforce there is no config file.
+        Mock Get-ModuleBase {
+            if ($IsWindows) { return "C:\" }
+            elseif ($isLinux) { return "/" }
+        }
+        It "Missing dependency file should not cause an error" {
+            { Resolve-Dependency -Name 'awesome' } | Should -Not -Throw
+        }
+
+        It "Missing dependency file should return true" {
+            Resolve-Dependency -Name 'awesome' | Should -Be $true
+        }
+    }
+    Context "Testing input variations" {
+        It "Should return true if all given dependencies exist" {
+            Mock Get-ModuleBase {
+                return (Join-Path -Path $PWD -ChildPath '/resources')
+            }
+            Resolve-Dependency -Name 'Existing' | Should -Be $true
+        }
+        It "Mixed results should return false" {
+            Mock Get-ModuleBase {
+                return (Join-Path -Path $PWD -ChildPath '/resources')
+            }
+            Resolve-Dependency -Name 'PSGetMixed' | Should -Be $false
+        }
+    }
+}

src/Private/Resolve-Dependency.ps1

@@ -0,0 +1,87 @@
+function Resolve-Dependency {
+    <#
+    .SYNOPSIS
+        Tests defined optional dependencies and returns the result as bool.
+
+    .DESCRIPTION
+        Use this function to test for optional modules. You can use it if you provide functions which needs special
+        modules but you don't want to make them required.
+
+        Place a file called Dependency.json in your module root dir. The default format is:
+
+        {
+            "Version": 0.1,
+            "Mandatory": {},
+            "Optional": [
+                {
+                    "Name": "VMware",
+                    "Modules": [
+                        "VMware.VimAutomation.Core"
+                    ]
+                },
+                {
+                    "Name": "CiscoUCS",
+                    "Modules": []
+                }
+            ]
+        }
+
+    .PARAMETER Name
+        Select the dependency item name you defined in the dependency.json.
+    .INPUTS
+        [None]
+
+    .OUTPUTS
+        [bool]
+
+    .EXAMPLE
+        If (-not (Resolve-Dependency -Name 'VMware')) {
+            Write-Error -Message (
+                "Could not resolve the optional dependencies defined for {0}" -f 'VMware'
+            ) -ErrorAction 'Stop'
+        }
+    #>
+
+    [OutputType([bool])]
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [string]$Name
+    )
+
+    begin {
+        $ModuleRootDir = Get-ModuleBase
+        $DepFilePath = Join-Path -Path $ModuleRootDir -ChildPath "Dependency.json"
+        if (Test-Path -Path $DepFilePath) {
+            $Dependency = Get-Content -Path $DepFilePath -Raw -Encoding UTF8 | ConvertFrom-Json
+        }
+        else {
+            Write-Warning ("Could not find the dependency file: {0}" -f $DepFilePath)
+        }
+    }
+
+    process {
+        # ScriptAnalyzer issue workaround (unused var)
+        $null = $Name
+        $SelectedDependency = $Dependency.Optional | Where-Object { $_.Name -match $Name }
+        # return true if there is no dependency defined
+        if ($null -eq $SelectedDependency) {
+            return $true
+        }
+
+        $res = @()
+        foreach ($Module in $SelectedDependency.Modules) {
+            $res += Test-Module -Name $Module
+        }
+        # return false if there was not module at all
+        if (($res -contains $false) -or ($res.Count -eq 0)) {
+            return $false
+        }
+        else {
+            return $true
+        }
+    }
+
+    end {}
+}