microsoft / unitysetup.powershell

Powershell module for interfacing with Unity installs and projects.

Unity Setup Powershell Module

This PowerShell module contains tools for managing and automating your Unity installs and projects.

Builds

Master

The master branch is automatically built and deployed to the PowerShell Gallery.

Develop

The develop branch is automatically built and deployed as a prerelease module to the PowerShell Gallery.

Installation

Install-Module UnitySetup -Scope CurrentUser

Using

Cmdlets

Find all of your Unity installs:

Get-UnitySetupInstance

# Example output:
# Version                                          Components Path
# -------                                          ---------- ----
# 2017.1.2f1                       Windows, UWP, UWP_IL2CPP C:\Program Files\Unity-2017.1.2f1\
# 2017.1.3f1                       Windows, UWP, UWP_IL2CPP C:\Program Files\Unity-2017.1.3f1\
# 2017.2.1f1                       Windows, UWP, UWP_IL2CPP C:\Program Files\Unity-2017.2.1f1\
# 2017.3.1f1       Windows, UWP, UWP_IL2CPP, Linux, Vuforia C:\Program Files\Unity-2017.3.1f1\
# 2018.1.0b4              Windows, UWP, UWP_IL2CPP, Vuforia C:\Program Files\Unity-2018.1.0b4\
# 2018.1.0b8                                              All C:\Program Files\Unity-2018.1.0b8\
# 2017.1.0p5                       Windows, UWP, UWP_IL2CPP C:\Program Files\Unity.2017.1.0p5\
# 2017.1.1f1                       Windows, UWP, UWP_IL2CPP C:\Program Files\Unity.2017.1.1f1\
# 2017.1.1p3       Windows, StandardAssets, UWP, UWP_IL2CPP C:\Program Files\Unity.2017.1.1p3\
# 2017.2.0f3              Windows, UWP, UWP_IL2CPP, Vuforia C:\Program Files\Unity.2017.2.0f3\
# 2017.3.0f3         Windows, UWP, UWP_IL2CPP, Mac, Vuforia C:\Program Files\Unity.2017.3.0f3\

Select the Unity installs that you want:

Get-UnitySetupInstance | Select-UnitySetupInstance -Latest
Get-UnitySetupInstance | Select-UnitySetupInstance -Version '2017.1.1f1'
Get-UnitySetupInstance | Select-UnitySetupInstance -Project '.\MyUnityProject'

Find all the Unity projects recursively:

Get-UnityProjectInstance -Recurse

# Example output:
# Version    Path                            ProductName
# -------    ----                            -----------
# 2017.2.0f3 C:\Projects\Project1\OneUnity\  Contoso
# 2017.3.0f3 C:\Projects\Project1\TwoUnity\  Northwind
# 2017.1.1p1 C:\Projects\Project2\           My Cool App
# 2017.1.2f1 C:\Projects\Project3\App.Unity\ TemplateProject

Launch the right Unity editor for a project:

Start-UnityEditor
Start-UnityEditor -Project .\MyUnityProject
Start-UnityEditor -Project .\MyUnityProject -Latest
Start-UnityEditor -Project .\MyUnityProject -Version '2017.3.0f3'

Using the Unity Accelerator:

Start-UnityEditor -Project .\MyUnityProject -CacheServerEndpoint 192.168.0.23 
Start-UnityEditor -Project .\MyUnityProject -CacheServerEndpoint 192.168.0.23:2523 -CacheServerNamespacePrefix "dev"
Start-UnityEditor -Project .\MyUnityProject -CacheServerEndpoint 192.168.0.23 -CacheServerNamespacePrefix "dev" -CacheServerDisableDownload
Start-UnityEditor -Project .\MyUnityProject -CacheServerEndpoint 192.168.0.23 -CacheServerDisableUpload

Launch many projects at the same time:

Get-UnityProjectInstance -Recurse | Start-UnityEditor

Invoke methods with arbitrary arguments:

Start-UnityEditor -ExecuteMethod Build.Invoke -BatchMode -Quit -LogFile .\build.log -Wait -AdditionalArguments "-BuildArg1 -BuildArg2"

Test the meta file integrity of Unity Projects:

Test-UnityProjectInstanceMetaFileIntegrity # Test project in current folder
Test-UnityProjectInstanceMetaFileIntegrity .\MyUnityProject
Test-UnityProjectInstanceMetaFileIntegrity -Project .\MyUnityProject
Get-UnityProjectInstance -Recurse | Test-UnityProjectInstanceMetaFileIntegrity

# Example output:
# True

Get meta file integrity issues for Unity Projects:

Test-UnityProjectInstanceMetaFileIntegrity .\MyUnityProject -PassThru

# Example output:
# Item                                                              Issue
# ----                                                              -----
# C:\MyUnityProject\Assets\SomeFolder                               Directory is missing associated meta file.
# C:\MyUnityProject\Assets\SomeFolder\SomeShader.shader             File is missing associated meta file.
# C:\MyUnityProject\Assets\SomeFolder\SomeOtherShader.shader.meta   Meta file is missing associated item.
# C:\MyUnityProject\Assets\SomeFolder\SomeNewShader.shader.meta     Meta file guid collision with C:\MyUnityProject\Assets\SomeFolder\SomeOtherShader.shader.meta

Find the installers for a particular version:

Find-UnitySetupInstaller -Version '2017.3.0f3' | Format-Table

# Example output:
#  ComponentType Version       Length LastModified          DownloadUrl
#  ------------- -------       ------ ------------          -----------
#        Windows 2017.3.0f3 553688024 12/18/2017 8:05:31 AM https://download.unity3d.com/download_unity/...
#          Linux 2017.3.0f3 122271984 12/18/2017 8:06:53 AM https://download.unity3d.com/download_unity/...
#            Mac 2017.3.0f3  28103888 12/18/2017 8:06:53 AM https://download.unity3d.com/download_unity/...
#  Documentation 2017.3.0f3 358911256 12/18/2017 8:07:34 AM https://download.unity3d.com/download_unity/...
# StandardAssets 2017.3.0f3 189886032 12/18/2017 8:05:50 AM https://download.unity3d.com/download_unity/...
#          UWP 2017.3.0f3 172298008 12/18/2017 8:07:04 AM https://download.unity3d.com/download_unity/...
#     UWP_IL2CPP 2017.3.0f3 152933480 12/18/2017 8:07:10 AM https://download.unity3d.com/download_unity/...
#        Android 2017.3.0f3 194240888 12/18/2017 8:05:58 AM https://download.unity3d.com/download_unity/...
#            iOS 2017.3.0f3 802853872 12/18/2017 8:06:46 AM https://download.unity3d.com/download_unity/...
#        AppleTV 2017.3.0f3 273433528 12/18/2017 8:06:09 AM https://download.unity3d.com/download_unity/...
#       Facebook 2017.3.0f3  32131560 12/18/2017 8:06:12 AM https://download.unity3d.com/download_unity/...
#        Vuforia 2017.3.0f3  65677296 12/18/2017 8:07:12 AM https://download.unity3d.com/download_unity/...
#          WebGL 2017.3.0f3 134133288 12/18/2017 8:07:19 AM https://download.unity3d.com/download_unity/...

Limit what components you search for:

Find-UnitySetupInstaller -Version 2017.3.0f3 -Components 'Windows','Documentation' | Format-Table

# Example output:
# ComponentType Version       Length LastModified          DownloadUrl
# ------------- -------       ------ ------------          -----------
#       Windows 2017.3.0f3 553688024 12/18/2017 8:05:31 AM https://download.unity3d.com/download_unity/...
# Documentation 2017.3.0f3 358911256 12/18/2017 8:07:34 AM https://download.unity3d.com/download_unity/...

Install UnitySetup instances:

# Pipeline is supported, but downloads, then installs, then downloads, etc.
Find-UnitySetupInstaller -Version '2017.3.0f3' | Install-UnitySetupInstance

# This will issue all downloads together, then install each.
Install-UnitySetupInstance -Installers (Find-UnitySetupInstaller -Version '2017.3.0f3')

Manage Unity licenses.

# Get any active licenses
Get-UnityLicense

# Example Output:
# LicenseVersion : 6.x
# Serial         : System.Security.SecureString
# UnityVersion   : 2017.4.2f2
# DisplaySerial  : AB-CDEF-GHIJ-KLMN-OPQR-XXXX
# ActivationDate : 2017-07-13 16:32:16
# StartDate      : 2017-07-12 00:00:00
# StopDate       : 2019-01-01 00:00:00
# UpdateDate     : 2018-05-11 23:47:10

# Activate a license
Start-UnityEditor -Credential <unityAccount> -Serial <unitySerial> -Wait

# Return license
Start-UnityEditor -Credential <unityAccount> -ReturnLicense -Wait

DSC

UnitySetup includes the xUnitySetupInstance DSC Resource. An example configuration might look like:

<#
    Install multiple versions of Unity and several components
#>
Configuration Sample_xUnitySetupInstance_Install {
    param(
        [PSCredential]$UnityCredential,
        [PSCredential]$UnitySerial
    )

    Import-DscResource -ModuleName UnitySetup

    Node 'localhost' {

        xUnitySetupInstance Unity {
            Versions = '2017.4.2f2,2018.1.0f2'
            Components = 'Windows', 'Mac', 'Linux', 'UWP', 'iOS'
            Ensure = 'Present'
        }

        xUnityLicense UnityLicense {
            Name = 'UL01'
            Credential = $UnityCredential
            Serial = $UnitySerial
            Ensure = 'Present'
            UnityVersion = '2017.4.2f2'
            DependsOn = '[xUnitySetupInstance]Unity'   
        }
    }
}

See more by perusing the UnitySetup\Examples folder.

Feedback

To file issues or suggestions, please use the Issues page for this project on GitHub.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

unitysetup.powershell's Issues

PowerShell Core 6 - Find-UnitySetupInstaller Issues

• Fresh PowerShell Core 6 install.
• Windows 10 Falls Creator's Update
• Install-Module UnitySetup -Scope CurrentUser to install UnitySetup.

Running the one example Find-UnitySetupInstaller -Version '2017.3.0f3' | Format-Table outputs:

WARNING: Unable to find installer for the WebGL component.
WARNING: Unable to find installer for the Metro component.
WARNING: Unable to find installer for the StandardAssets component.
WARNING: Unable to find installer for the Windows component.
WARNING: Unable to find installer for the UWP_IL2CPP component.
WARNING: Unable to find installer for the AppleTV component.
WARNING: Unable to find installer for the Vuforia component.
WARNING: Unable to find installer for the Windows_IL2CPP component.
WARNING: Unable to find installer for the Documentation component.
WARNING: Unable to find installer for the iOS component.
WARNING: Unable to find installer for the Mac component.
WARNING: Unable to find installer for the Android component.
WARNING: Unable to find installer for the Linux component.
WARNING: Unable to find installer for the Facebook component.

I'm able to run other commands like Get-UnitySetupInstance.

Installing the module in PowerShell on the same machine works just fine.

ImportPackage does not work on relative paths

ImportPackage in Start-UnityEditor should support relative paths so that the user does not have to resolve their path

powershell-yaml is marked as an external module dependency when it isn't.

Removing it from that list should make publishing verify the module exists on the gallery and install it when installing our module.

Aliases would really help make some of the common commands simpler

Investigate ramifications of aliases.

Proposed:

gusi => Get-UnitySetupInstance
gupi => Get-UnityProjectInstance
sue => Start-UnityEditor

Would enable this

gupi -r | sue

The ability to install versions of Unity would be great!

Can't install without Admin pop up

Add a -Verb param to Install-UnitySetupInstance that forwards to the start-process call so that as an admin I can launch Unity as an admin.

Builds are actually broken

The builds act like they succeeded, but they have not. Looks like AppVeyor updated it's host machines and now some imports don't work.

I'll try to apply the -AllowClobber flag to see if the imports fix the issue.

Find-UnitySetupInstaller can't find Unity 2017.1.2p3 Mac component

I'm trying to install the Mac component for Unity 2017.1.2p3. Finding the Mac installer returns nothing, including no error.

PS C:\Users\bryce> Find-UnitySetupInstaller -Version 2017.1.2p3 -Components Mac
PS C:\Users\bryce> Find-UnitySetupInstaller -Version 2017.1.2p3 -Components Setup


ComponentType : Setup
Version       : 2017.1.2p3
Length        : 541722008
LastModified  : 11/21/2017 5:27:22 AM
DownloadUrl   : https://beta.unity3d.com/download/249a06fbaf10/Windows64EditorInstaller/UnitySetup64-2017.1.2p3.exe

I downloaded the component through the Download Assistant and sniffed the component url: http://download.unity3d.com/download_unity/249a06fbaf10/TargetSupportInstaller/UnitySetup-Mac-Support-for-Editor-2017.1.2p3.exe

A DSC Resource for Unity versions

Now that we can detect installs, find installers, and install unity, we can create a DSC resource for ensuring versions of Unity are installed.

Installs should set path environment vars so capabilities can be detected.

Set/Remove environment variables, eg. {key:"UNITY_2017.4.2f2", value: ""}.

This would make them discoverable in online build systems and leveraged appropriately.

Get-UnitySetupInstance does not find instances of Unity installed via the Unity Hub.

Installed the 2018 beta via the Unity Hub, did not appear when running Get-UnitySetupInstance.

Install-UnitySetupInstance on a narrow PowerShell window -> lots of output spam

1. Open a PowerShell window and slide the right edge so it isn't very wide
2. Run Install-UnitySetupInstance (e.g. Find-UnitySetupInstaller -Version '2017.3.1p1' -Components Setup | Install-UnitySetupInstance)

result: Script attempts to update its progress spinner, ends up printing lots of output:

Installing C:\Users\forrest\.unitysetup\Installers\Unity-2017.3.1p1\UnitySetup64-2017.3.1p1.exe to C:\Program Files\UnitInstalling C:\Users\forrest\.unitysetup\Installers\Unity-2017.3.1p1\UnitySetup64-2017.3.1p1.exe to C:\Program Files\UnitInstalling C:\Users\forrest\.unitysetup\Installers\Unity-2017.3.1p1\UnitySetup64-2017.3.1p1.exe to C:\Program Files\UnitInstalling C:\Users\forrest\.unitysetup\Installers\Unity-2017.3.1p1\UnitySetup64-2017.3.1p1.exe to C:\Program Files\UnitInstalling C:\Users\forrest\.unitysetup\Installers\Unity-2017.3.1p1\UnitySetup64-2017.3.1p1.exe to C:\Program Files\UnitInstalling C:\User...

expected: Progress spinner outputs in place or output is more sparing/organized.

Build Targets have changed and valid options are missing from the validated set.

I'm tempted to drop the BuildTarget ValidateSet so we don't have this dependency that requires this code to change on the Unity whims.

Docs to latest cmd line support: https://docs.unity3d.com/2018.1/Documentation/Manual/CommandLineArguments.html

xUnitySetup DSC resource should be xUnitySetupInstance

This matches more closely to existing patterns and fits in nicely with the upcoming xUnitySetupLicense DSC resource from #83

Should be able to find all installers for all versions of unity in one call

Right now Find-UnitySetupInstaller requires you to specify a version. It'd be great if I could specify -Latest or neither to find all versions.

• Should patch and beta versions be included by default if no args are passed?
• Should we add flags to control the versions you'll search for, use param sets to avoid Version being specified.
• Should we add a Find-UnitySetupVersion which finds available versions which could be piped to 'Find-UnitySetupInstaller'?

Running Install Script Multiple Times Fails Installing Any

Running a command like Find-UnitySetupInstaller -Version '2017.1.2f1' | Install-UnitySetupInstance and Find-UnitySetupInstaller -Version '2017.1.1p1' | Install-UnitySetupInstance at the same time was causing issues with both versions being unable to install properly.

Both Unity install folders end up looking like Unity projects. Which was quite weird.

Suggested to allow for downloading all the setup files in parallel and / or up front. Lock installation to only a single one at a time.

Patch builds off the front page for a version are not found by Find-UnitySetupInstaller

My Example:

C:\WINDOWS\system32> $installers = Find-UnitySetupInstaller -Version 2017.2.0p3 -Components Setup -Verbose
VERBOSE: GET https://unity3d.com/unity/qa/patch-releases?version=2017.2 with 0-byte payload
VERBOSE: received 73560-byte response of content type text/html; charset=utf-8
VERBOSE: GET https://unity3d.com/unity/qa/patch-releases?version=2017.2 with 0-byte payload
VERBOSE: received 73560-byte response of content type text/html; charset=utf-8
Could not find archives for Unity version 2017.2.0p3
At C:\Users\jowitt\Documents\WindowsPowerShell\Modules\UnitySetup\3.0.80\UnitySetup.psm1:257 char:9
+         throw "Could not find archives for Unity version $Version"
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : OperationStopped: (Could not find ...sion 2017.2.0p3:String) [], RuntimeException
    + FullyQualifiedErrorId : Could not find archives for Unity version 2017.2.0p3

Looks like the regex against the page urls is failing now.

Start-Process call format for launching Unity Setup throws error when Set-PSDebug -Trace set to 2

in script do:
Set-PSDebug -Trace 2

Call Install-UnitySetupInstance

Bug - the line $process = Start-Process @startProcessArgs
has issues when Trace set to 2.

Cannot convert value to type System.String.
At C:\Program Files\WindowsPowerShell\Modules\UnitySetup\4.0.97\UnitySetup.psm1:487 char:13

•         $process = Start-Process @startProcessArgs
  

•         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : InvalidArgument: (:) [], RuntimeException
  • FullyQualifiedErrorId : InvalidCastFromAnyTypeToString

perhaps consider using:
Start-Process @startPRocessARgs -OutVariable $result | Out-Null

PSScriptAnalyzer has warnings

Running Invoke-ScriptAnalyzer UnitySetup\UnitySetup.psm1 results in

RuleName                            Severity     ScriptName Line  Message
--------                            --------     ---------- ----  -------
PSUseShouldProcessForStateChangingF Warning      UnitySetup 492   Function ’Start-UnityEditor’ has verb that could change
unctions                                         .psm1            system state. Therefore, the function has to support
                                                                  'ShouldProcess'.
PSAvoidUsingWriteHost               Warning      UnitySetup 303   File 'UnitySetup.psm1' uses Write-Host. Avoid using
                                                 .psm1            Write-Host because it might not work in all hosts, does not
                                                                  work when there is no host, and (prior to PS 5.0) cannot be
                                                                  suppressed, captured, or redirected. Instead, use
                                                                  Write-Output, Write-Verbose, or Write-Information.
PSAvoidUsingWriteHost               Warning      UnitySetup 309   File 'UnitySetup.psm1' uses Write-Host. Avoid using
                                                 .psm1            Write-Host because it might not work in all hosts, does not
                                                                  work when there is no host, and (prior to PS 5.0) cannot be
                                                                  suppressed, captured, or redirected. Instead, use
                                                                  Write-Output, Write-Verbose, or Write-Information.
PSAvoidUsingWriteHost               Warning      UnitySetup 314   File 'UnitySetup.psm1' uses Write-Host. Avoid using
                                                 .psm1            Write-Host because it might not work in all hosts, does not
                                                                  work when there is no host, and (prior to PS 5.0) cannot be
                                                                  suppressed, captured, or redirected. Instead, use
                                                                  Write-Output, Write-Verbose, or Write-Information.

Support *nix platforms

PowerShell Core is now cross-platform. We should investigate supporting the *nix world, including Mac.

Mac

• Find-UnitySetupInstaller
• Get-UnityProjectInstance
• Get-UnitySetupInstance
• Install-UnitySetupInstance
• Select-UnitySetupInstance
• Uninstall-UnitySetupInstance
• Start-UnityEditor
• ConvertTo-UnitySetupComponent
• Get-UnityLicense

Linux

• Find-UnitySetupInstaller
• Get-UnityProjectInstance
• Get-UnitySetupInstance
• Install-UnitySetupInstance
• Select-UnitySetupInstance
• Uninstall-UnitySetupInstance
• Start-UnityEditor
• ConvertTo-UnitySetupComponent
• Get-UnityLicense

Examples Component Installing Over Unity.exe

Attempting to download 2017.1.1p1 with this command: Find-UnitySetupInstaller -Version '2017.1.2f1' | Install-UnitySetupInstance.

Installer gets to UnityExampleProjectSetup-2017.1.1p1.exe and installs fine. Noticed after this install the Unity install directory is overwritten with the example scene. Unity.exe is now deleted and thus the installation is now borked.

Components should be discovered for existing UnitySetupInstances

Need a provider for PackageManagement

UnityGet would be available on the PSGallery and would provide Unity installations through the standard PackageManagement module.

exiting Unity launched from PowerShell spews "leaked weakptr" to PowerShell console

1. Run Start-UnityEditor to run the Unity.
2. Close Unity after it launches.
   result: Extra output is written to the console:

Checking for leaked weakptr:
  Found no leaked weakptrs.
##utp:{"type":"MemoryLeaks","allocatedMemory":25398947,"memoryLabels":[{"Default":3148},{"NewDelete":6397012},{"Manager":224},{"Texture":480},{"TextureCache":-480},{"FMOD":640},{"Physics":1},{"Serialization":29792},{"Terrain":224},{"String":39656},{"DynamicArray":30073},{"HashMap":18846208},{"Curl":1528},{"PoolAlloc":-224},{"Sprites":8},{"CloudService":-2360},{"VR":1704},{"EditorGui":280},{"EditorUtility":35680},{"AssetImporter":32},{"RestService":72},{"EditorGi":5785},{"UnityConnect":9376},{"Collab":720},{"Upm":-632}]}

expected: No additional output.

Formatting is out of whack with VS Code auto formatter

When applying the auto-formatting in VS Code, there are a ton of changes. Make a PR that updates the formatting so that auto-formatting doesn't change the document so much.

Start-UnityEditor should accept a path by default

I should be able to enter Start-UnityEditor "path to unity project" and it should start as if I 'cd' there and use Start-UnityEditor without any args.

Start-UnityEditor should pipeline projects not setup instances.

It's more likely that we have many projects we want to start than it is to have many installs for one project. It makes this easy and possible:

Get-UnityProjectInstance -Recurse | Start-UnityEditor

Install-UnitySetupInstance could be more asyncronous

Right now it downloads them one at a time then installs all. It should download them all asynchronously, when the main installer for the platform is done it should install that, then it should install components as they finish downloading.

Get-UnityProjectInstance should provide the components required for a project

Not sure if this is possible, but it would make installing the right components necessary for a project simpler. Right now to encompass everything we have install everything.

Running Install-UnitySetupInstance with -Verb RunAs should elevate to admin before running any of the installers

This would make it easy to wrap all the installs with one UAC prompt when performing locally.

Undescriptive Error for Start-UnityEditor

When you try to start a unity editor for a project that has an uninstalled unity version, you get an error that doesn't make it clear that you must install the corresponding unity version.

Input:
Start-UnityEditor -Project C:\Users\defreed\Source\Repos\Test\

Output:
Start-UnityEditor : Could not find Unity.exe under setup instance path:
At line:1 char:1

• Start-UnityEditor -Project C:\Users\defreed\Source\Repos\Test\

•   + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Start-UnityEditor
  

PS Script Analyzer throws error over ConvertTo-SecureString -AsPlainText

RuleName                            Severity     ScriptName Line  Message
--------                            --------     ---------- ----  -------
PSAvoidUsingConvertToSecureStringWi Error        UnitySetup 1015  File 'UnitySetup.psm1' uses ConvertTo-SecureString with
thPlainText                                      .psm1            plaintext. This will expose secure information. Encrypted
                                                                  standard strings should be used instead.

No fallback to latest version of unity

If you pull an existing project without a project version, unitysetup should start the project in the most recent unity version on your pc

Start-UnityEditor silently fails with -version with valid format that does not exist

repro: Start-UnityEditor -Version "2017.22.2f3"

Start-UnityEditor reports non-zero exit code from Unity incorrectly.

Start-UnityEditor -BatchMode -Wait -Quit -Project <project>

fails because the exit code is not set, it's not non-zero, we're running into an issue with Start-Process.

Start-UnityEditor should install missing Versions

If the version is not installed, the function should perform the -MissingVersionAction, which can be any of Confirm, ConfirmVersion, Install, Fallback, Error

MissingVersionAction, defaults to Confirm.

Example 'Confirm' output:

Would you like to?

[A] Install the missing version or [B] launch with latest version or [C] Specify a version or [D] Cancel.
C
What version?
>

Using ConfirmVersion skips the initial prompt, and asks just what version you'd like to use. Install auto installs without asking. Latest launches with the latest installed version. Error results in the exception we see now.

Note that defaulting to Confirm means a major version bump to account for the change in behavior. We could default to Error and make this a minor version bump. We could export a variable to control the default - $UnitySetupMissingVersionActionPreference so that people can change their default.

Start-BitsTransfer cannot be leveraged in some instances

in Install-UnitySetupInstance
the line
Start-BitsTransfer -Source $downloadSource -Destination $downloadDest

fails if it's executed from a Visual Studio Team Services build agent with as the VSTS Agent runs as a service.
2018-08-03T17:31:03.2273217Z DEBUG: 472+ >>>> Start-BitsTransfer -Source $downloadSource -Destination $downloadDest
2018-08-03T17:31:03.7159554Z Start-BitsTransfer : The operation being requested was not performed because the user has not logged on to the
2018-08-03T17:31:03.7159834Z network. The specified service does not exist. (Exception from HRESULT: 0x800704DD)
2018-08-03T17:31:03.7160174Z At C:\Program Files\WindowsPowerShell\Modules\UnitySetup\4.0.97\UnitySetup.psm1:472 char:13

Either credentials need to be supplied to the call (and piped through as params) or it should use webclient to download the installer
(New-Object System.Net.WebClient).DownloadFile([string]$downloadSource, [string]$downloadDest)

I'm testing this E2E now.

Examples for Find-UnitySetupInstaller don't work

They refer to the unavailable UnitySetupComponentType type.

QA "p" releases are not being found

PS C:\Users\bryce> Find-UnitySetupInstaller -Version 2017.3.0p4 -Components Setup
Could not find archives for Unity version 2017.3.0p4
At C:\Users\bryce\OneDrive\Documents\WindowsPowerShell\Modules\UnitySetup\2.1.43\UnitySetup.psm1:204 char:9
+         throw "Could not find archives for Unity version $Version"
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : OperationStopped: (Could not find ...sion 2017.3.0p4:String) [], RuntimeException
    + FullyQualifiedErrorId : Could not find archives for Unity version 2017.3.0p4

It seems to fail on any "p" releases. I got the version numbers from the Patch Releases page. Other release types seem to be working correctly.

uninstall while Unity is running appears to succeed, but leaves behind some files

1. Run the Unity editor
2. Uninstall the version that you are running (e.g. Get-UnitySetupInstance | Select-UnitySetupInstance -Version 2017.3.1f1 | Uninstall-UnitySetupIns tance)
   result: Command appears to complete successfully, but some of the files in Program Files are left behind.
   expected: It would be nice to detect that the Unity process is running and error out without attempting to uninstall.

Module appears to exporting cmdlets from powershell-yaml.

Functions
Select-UnitySetupInstance Start-UnityEditor Get-UnitySetupInstance Find-UnitySetupInstaller Install-UnitySetupInstance Get-UnityProjectInstance ConvertFrom-Yaml ConvertTo-Yaml

Need support for handling Unity licenses.

Add necessary activation/return flags to Start-UnityEditor.
Create DSC resource xUnitySetupLicense.

No way to accept API update in `Start-UnityEditor`

Add a new parameter AcceptAPIUpdate and pipe it to Unity.

Start-UnityEditor should parse and summarize errors when Unity exits

Our build process launches the Unity editor using the Start-UnityEditor. We often end up with errors such as "Start-UnityEditor : Unity quit with non-zero exit code: 1." when our build fails.

It can be time-consuming to search a large Unity log for errors. It would be awesome if Start-UnityEditor could understand Unity's log file and pull out error messages and summarized them in its error output.

New-UnitySetupComponent is misleading

Suppressing the analyzer warning is a clear indication of that.
Change to ConvertTo-UnitySetupComponent.

The path for UnitySetupInstances should be the install folder

Right now it returns the Editor subfolder within the install folder, that makes installing using the detected paths pretty annoying and isn't probably what people expect.

Start-UnityEditor fails with unclear error when run with invalid Unity path

You see this error:

Cannot convert the "System.Object[]" value of type "System.Object[]" to type "UnityInstance".
At C:\Users\jowitt\Documents\WindowsPowerShell\Modules\UnitySetup\1.4.29\UnitySetup.psm1:260 char:9
+         $Instance =  Get-UnitySetupInstance | Select-UnitySetupInstan ...
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [], RuntimeException
    + FullyQualifiedErrorId : ConvertToFinalInvalidCastException

Could not find Unity Editor for version
At C:\Users\jowitt\Documents\WindowsPowerShell\Modules\UnitySetup\1.4.29\UnitySetup.psm1:270 char:9
+         throw "Could not find Unity Editor for version $version"
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : OperationStopped: (Could not find Unity Editor for version :String) [], RuntimeException
    + FullyQualifiedErrorId : Could not find Unity Editor for version

Fails to find Metro installer for 2018.2.1f1

Looks like the installer name changed and we need support for the new location.

Find-UnitySetupInstaller -Version 2018.2.1f1 -Components Metro

Would be nice to make error handling for missing components better.

I think I'm going to write-warning and then you can control the warning action for the cmdlet.

*-UnitySetup API should align with Package/Module APIs already well known.

• Find-UnitySetupInstaller -> Find-UnitySetupInstance, should find all versions if called without flags.
• Install-UnitySetupInstance -> Shouldn't require installers from Find.
• Get-UnitySetupInstance -> Should support filters from Select-UnitySetupInstance
• Select-UnitySetupInstance -> Drop cmdlet entirely
• Update-UnitySetupInstance -> Should install latest version, use flags to signal patch or beta allowed.