microsoft · Josh Wittner (jwittner) · Apr 3, 2018 · Feb 15, 2018 · Feb 16, 2018 · Feb 16, 2018
diff --git a/README.md b/README.md
@@ -22,20 +22,25 @@ Install-Module UnitySetup -Scope CurrentUser
 
 ## Using
 
+### Cmdlets
 Find all of your Unity installs:
 ```powershell
 Get-UnitySetupInstance
 
 # Example output:
-# InstallationVersion InstallationPath
-# ------------------- ----------------
-# 2017.2.1f1          C:\Program Files\Unity-2017.2.1f1\Editor\
-# 2017.1.0p5          C:\Program Files\Unity.2017.1.0p5\Editor\
-# 2017.1.1f1          C:\Program Files\Unity.2017.1.1f1\Editor\
-# 2017.1.1p3          C:\Program Files\Unity.2017.1.1p3\Editor\
-# 2017.2.0f3          C:\Program Files\Unity.2017.2.0f3\Editor\
-# 2017.3.0f3          C:\Program Files\Unity.2017.3.0f3\Editor\
-# 5.5.4p3             C:\Program Files (x86)\Unity.5.5.4p3\Editor\
+# Version                                        Components Path
+# -------                                        ---------- ----
+# 2017.1.2f1                       Setup, Metro, UWP_IL2CPP C:\Program Files\Unity-2017.1.2f1\
+# 2017.1.3f1                       Setup, Metro, UWP_IL2CPP C:\Program Files\Unity-2017.1.3f1\
+# 2017.2.1f1                       Setup, Metro, UWP_IL2CPP C:\Program Files\Unity-2017.2.1f1\
+# 2017.3.1f1       Setup, Metro, UWP_IL2CPP, Linux, Vuforia C:\Program Files\Unity-2017.3.1f1\
+# 2018.1.0b4              Setup, Metro, UWP_IL2CPP, Vuforia C:\Program Files\Unity-2018.1.0b4\
+# 2018.1.0b8                                            All C:\Program Files\Unity-2018.1.0b8\
+# 2017.1.0p5                       Setup, Metro, UWP_IL2CPP C:\Program Files\Unity.2017.1.0p5\
+# 2017.1.1f1                       Setup, Metro, UWP_IL2CPP C:\Program Files\Unity.2017.1.1f1\
+# 2017.1.1p3       Setup, StandardAssets, Metro, UWP_IL2CPP C:\Program Files\Unity.2017.1.1p3\
+# 2017.2.0f3              Setup, Metro, UWP_IL2CPP, Vuforia C:\Program Files\Unity.2017.2.0f3\
+# 2017.3.0f3         Setup, Metro, UWP_IL2CPP, Mac, Vuforia C:\Program Files\Unity.2017.3.0f3\
 ```
 
 Select the Unity installs that you want:
@@ -50,12 +55,12 @@ Find all the Unity projects recursively:
 Get-UnityProjectInstance -Recurse
 
 # Example output:
-# ProjectPath                                    UnityInstanceVersion
-# -----------                                    --------------------
-# C:\Projects\Project1\OneUnity\                 2017.2.0f3
-# C:\Projects\Project1\TwoUnity\                 2017.3.0f3
-# C:\Projects\Project2\                          2017.1.1p1
-# C:\Projects\Project3\App.Unity\                2017.1.2f1
+# Version    Path
+# -------    ----
+# 2017.2.0f3 C:\Projects\Project1\OneUnity\                 
+# 2017.3.0f3 C:\Projects\Project1\TwoUnity\                 
+# 2017.1.1p1 C:\Projects\Project2\                          
+# 2017.1.2f1 C:\Projects\Project3\App.Unity\                
 ```
 Launch the right Unity editor for a project:
 ```powershell
@@ -78,7 +83,6 @@ Find-UnitySetupInstaller -Version '2017.3.0f3' | Format-Table
 #          Setup 2017.3.0f3 553688024 2017-12-18 08:15:20 https://netstorage.unity3d.com/unity/...
 #  Documentation 2017.3.0f3 358911256 2017-12-18 08:18:37 https://netstorage.unity3d.com/unity/...
 # StandardAssets 2017.3.0f3 189886032 2017-12-18 08:15:52 https://netstorage.unity3d.com/unity/...
-# ExampleProject 2017.3.0f3 258824680 2017-12-18 08:15:39 https://netstorage.unity3d.com/unity/...
 #          Metro 2017.3.0f3 172298008 2017-12-18 08:17:44 https://netstorage.unity3d.com/unity/...
 #     UWP_IL2CPP 2017.3.0f3 152933480 2017-12-18 08:17:55 https://netstorage.unity3d.com/unity/...
 #        Android 2017.3.0f3 194240888 2017-12-18 08:16:06 https://netstorage.unity3d.com/unity/...
@@ -110,6 +114,29 @@ Find-UnitySetupInstaller -Version '2017.3.0f3' | Install-UnitySetupInstance
 Install-UnitySetupInstance -Installers (Find-UnitySetupInstaller -Version '2017.3.0f3')
 ```
 
+### DSC
+UnitySetup includes the xUnitySetupInstance DSC Resource. An example configuration might look like:
+
+```powershell
+<#
+    Install multiple versions of Unity and several components
+#>
+Configuration Sample_xUnitySetupInstance_Install {
+
+    Import-DscResource -ModuleName UnitySetup
+
+    Node 'localhost' {
+
+        xUnitySetupInstance Unity {
+            Versions = '2017.3.1f1,2018.1.0b9'
+            Components = 'Setup', 'Mac', 'Linux', 'Metro', 'iOS'
+            Ensure = 'Present'
+        }
+    }
+}
+```
+
+See more by perusing the `UnitySetup\Examples` folder.
 
 # Feedback
 To file issues or suggestions, please use the [Issues](https://github.com/Microsoft/unitysetup.powershell/issues) page for this project on GitHub.

diff --git a/UnitySetup/DSCResources/xUnitySetupInstance/xUnitySetupInstance.psm1 b/UnitySetup/DSCResources/xUnitySetupInstance/xUnitySetupInstance.psm1
@@ -0,0 +1,201 @@
+
+<#
+.Synopsis
+    Returns the status of Unity installs and the set of their overlapping components.
+.Parameter Versions
+    The versions of Unity to test for.
+#>
+function Get-TargetResource {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [parameter(Mandatory = $true)]
+        [System.String]
+        $Versions
+    )
+    Write-Verbose "Begin executing Get on $Versions"
+
+    [string[]]$splitVersions = $Versions -split ',' | ForEach-Object { $_.Trim() }
+
+    $setupInstances = Get-UnitySetupInstance | Where-Object { $splitVersions -contains $_.Version }
+    $result = @{
+        "Versions" = $setupInstances | Select-Object -ExpandProperty Version | Sort-Object -Unique
+        "Ensure"   = if ($setupInstances.Count -gt 0) { 'Present'} else { 'Absent' }
+    }
+
+    Write-Verbose "Found versions: $($result['Versions'])"
+
+    if ( $setupInstances.Count -gt 0 ) {
+        $components = $setupInstances[0].Components;
+        for ( $i = 1; $i -lt $setupInstances.Count; $i++) {
+            $components = $components -band $setupInstances[$i].Components; 
+        }
+
+        $result["Components"] = $components
+    }
+
+    $result
+
+    Write-Verbose "Found overlapping components: $($result['Components'])"
+    Write-Verbose "End executing Get on $Versions"
+}
+
+<#
+.Synopsis
+    Installs or uninstalls the specified Versions of Unity and corresponding Components.
+.Parameter Versions
+    What versions are we concered with?
+.Parameter Ensure
+    Should we ensure they're there or ensure they're not?
+.Parameter Components
+    What components are we concerned with?
+.Notes
+    Only uninstalls whole versions of Unity. Ensuring components doesn't
+    mean other components weren't previously installed and aren't still available.
+#>
+function Set-TargetResource {
+    [CmdletBinding()]
+    param
+    (
+        [parameter(Mandatory = $true)]
+        [System.String]
+        $Versions,
+
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = 'Present',
+
+        [System.String[]]
+        $Components = @('All')
+    )
+
+    Write-Verbose "Begin executing Set to Ensure $Versions with $Components are $Ensure"
+
+    [string[]]$splitVersions = $Versions -split ',' | ForEach-Object { $_.Trim() }
+
+    switch ($Ensure) {
+        'Present' {
+            foreach ($version in $splitVersions) {
+                $findArgs = @{ 
+                    'Version'    = $version
+                    'Components' = ConvertTo-UnitySetupComponent $Components 
+                }
+
+                $installArgs = @{ 'Cache' = "$env:TEMP\.unitysetup" }
+
+                $setupInstances = Get-UnitySetupInstance | Select-UnitySetupInstance -Version $version
+                if ($setupInstances.Count -gt 0) {
+                    $findArgs["Components"] = ($findArgs.Components -band (-bnot ($setupInstances[0].Components -band $findArgs.Components)))
+                    $installArgs["Destination"] = $setupInstances[0].Path
+                }
+
+                # No missing components for this version
+                if ( $findArgs.Components -eq 0 ) { 
+                    Write-Verbose "All components of $version were installed"
+                    continue; 
+                }
+
+                Write-Verbose "Finding $($findArgs["Components"]) installers for $version"
+                $installArgs["Installers"] = Find-UnitySetupInstaller @findArgs -WarningAction Stop
+                if ( $installArgs.Installers.Count -gt 0 ) {
+                    Write-Verbose "Starting install of $($installArgs.Installers.Count) components for $version"
+                    Install-UnitySetupInstance @installArgs
+                    Write-Verbose "Finished install of $($installArgs.Installers.Count) components for $version"
+                }
+            }
+        }
+        'Absent' {
+            $setupInstances = Get-UnitySetupInstance | Where-Object { $splitVersions -contains $_.Version }
+            Write-Verbose "Found $($setupInstances.Count) instance(s) of $splitVersions"
+
+            if ( $setupInstances.Count -gt 0 ) {
+                Write-Verbose "Starting uninstall of $($setupInstances.Count) versions of Unity"
+                Uninstall-UnitySetupInstance -Instances $setupInstances
+                Write-Verbose "Finished uninstall of $($setupInstances.Count) versions of Unity"
+            }
+        }
+    }
+
+    Write-Verbose "End executing Set to Ensure $Versions with $Components are $Ensure"
+}
+
+<#
+.Synopsis
+    Test if the Unity installs are in the desired state.
+.Parameter Versions
+    What versions are we concered with?
+.Parameter Ensure
+    Should we ensure they're there or ensure they're not?
+.Parameter Components
+    What components are we concerned with?
+.Notes
+    This test is not strict. Versions and Components not described are not considered.
+#>
+function Test-TargetResource {
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [parameter(Mandatory = $true)]
+        [System.String]
+        $Versions,
+
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = 'Present',
+
+        [System.String[]]
+        $Components = @('All')
+    )
+
+    Write-Verbose "Begin executing Test to verify $Versions with $Components are $Ensure"
+
+    [string[]]$splitVersions = $Versions -split ',' | ForEach-Object { $_.Trim() }
+
+    $result = $true
+    switch ( $Ensure ) {
+        'Present' {
+            $setupComponents = ConvertTo-UnitySetupComponent $Components
+            foreach ($version in $splitVersions) {
+                Write-Verbose "Starting test for $version"
+                $setupInstances = Get-UnitySetupInstance | Select-UnitySetupInstance -Version $version
+                Write-Verbose "Found $($setupInstances.Count) instance(s) of $version"
+
+                if ($setupInstances.Count -eq 0) {
+                    Write-Verbose "Found $version missing."
+                    $result = $false
+                    break 
+                }
+
+                $availableComponents = ($setupInstances[0].Components -band $setupComponents)
+                if ($availableComponents -ne $setupComponents) { 
+                    $missingComponents = ConvertTo-UnitySetupComponent ($setupComponents -bxor $availableComponents)
+                    Write-Verbose "Found $version missing $($missingComponents)"
+                    $result = $false 
+                    break
+                }
+            }
+        }
+        'Absent' { 
+            foreach ($version in $splitVersions) {
+                $setupInstances = Get-UnitySetupInstance | Select-UnitySetupInstance -Version $version
+                Write-Verbose "Found $($setupInstances.Count) instance(s) of $version"
+
+                if ($setupInstances.Count -gt 0) {
+                    Write-Verbose "Found $version installed."
+                    $result = $false 
+                    break
+                }
+            }
+        }
+    }
+
+    $result
+
+    Write-Verbose "End executing Test to verify $Versions with $Components are $Ensure"
+}
+
+
+Export-ModuleMember -Function *-TargetResource
+
diff --git a/UnitySetup/DSCResources/xUnitySetupInstance/xUnitySetupInstance.schema.mof b/UnitySetup/DSCResources/xUnitySetupInstance/xUnitySetupInstance.schema.mof
@@ -0,0 +1,9 @@
+
+[ClassVersion("1.0.0.0"), FriendlyName("xUnitySetupInstance")]
+class xUnitySetupInstance : OMI_BaseResource
+{
+    [Key, Description("Comma separated list of Unity versions. ")] string Versions;
+    [Write, Description("Ensure present or absent?"), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] string Ensure;
+    [Write, Description("What components to ensure are present?")] string Components[];
+};
+
diff --git a/UnitySetup/Examples/Sample_xUnitySetupInstance.ps1 b/UnitySetup/Examples/Sample_xUnitySetupInstance.ps1
@@ -0,0 +1,28 @@
+<#
+    Create a custom configuration by passing in necessary values
+#>
+Configuration Sample_xUnitySetupInstance {
+    param 
+    (       
+        [System.String]
+        $Versions = '2017.3.0f3,2018.1.0b9',
+
+        [ValidateSet('Present', 'Absent')]
+        [System.String]
+        $Ensure = 'Present',
+
+        [System.String[]]
+        $Components = @('Setup', 'Linux', 'Metro', 'Mac', 'iOS')
+    )
+
+    Import-DscResource -ModuleName UnitySetup
+
+    Node 'localhost' {
+
+        xUnitySetupInstance Unity {
+            Versions   = $Versions
+            Components = $Components
+            Ensure     = $Ensure
+        }
+    }
+}
diff --git a/UnitySetup/Examples/Sample_xUnitySetupInstance_Install.ps1 b/UnitySetup/Examples/Sample_xUnitySetupInstance_Install.ps1
@@ -0,0 +1,16 @@
+<#
+    Install multiple versions of Unity and several components
+#>
+Configuration Sample_xUnitySetupInstance_Install {
+
+    Import-DscResource -ModuleName UnitySetup
+
+    Node 'localhost' {
+
+        xUnitySetupInstance Unity {
+            Versions   = '2017.3.1f1,2018.1.0b9'
+            Components = 'Setup', 'Mac', 'Linux', 'Metro', 'iOS'
+            Ensure     = 'Present'
+        }
+    }
+}
diff --git a/UnitySetup/Examples/Sample_xUnitySetupInstance_Uninstall.ps1 b/UnitySetup/Examples/Sample_xUnitySetupInstance_Uninstall.ps1
@@ -0,0 +1,15 @@
+<#
+    Uninstall multiple versions of Unity
+#>
+Configuration Sample_xUnitySetupInstance_Install {
+
+    Import-DscResource -ModuleName UnitySetup
+
+    Node 'localhost' {
+
+        xUnitySetupInstance Unity {
+            Versions = '2017.3.1f1,2018.1.0b9'
+            Ensure   = 'Absent'
+        }
+    }
+}