Public/New-ProvisioningPackage.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
function New-ProvisioningPackage {
    <#
    .SYNOPSIS
        Creates a new Windows 10 desktop provisioning package.

    .DESCRIPTION
        The New-ProvisioningPackage command creates a new Windows 10 provisioning
        package designed to automate setting up a new Windows 10 device
        using a small subset of common settings. Packages can be copied to
        a USB drive and inserted during the Windows Out of Box Experience (OOBE)
        that appears when the device is first powered on. Basic package functionality
        consists of assigning a computer name and local administrator credentials.
        Packages can optionally join the computer to a domain and install applications.

        The -ComputerName parameter accepts multiple computer names,
        and one provisioning package will be created for each computer name.
        You can also pipe a list of computer names to New-ProvisioningPackage.
        Each package will rename the device to the respective computer name
        but the packages are otherwise identical.

    .PARAMETER ComputerName
        Specifies one or more computer names. New-ProvisioningPackage will generate
        one package file for each computer name specified, using the computer name
        as the package file name with the .ppkg extension appended.

    .PARAMETER LocalAdminCredential
        Specifies the credentials of a local administrator account to create.

    .PARAMETER DomainName
        Specifies the name of a domain to join. If omitted, the provisioning package
        will set up the device as a workgroup computer.

    .PARAMETER DomainJoinCredential
        Specifies the credentials of a domain account with permission to join
        computers to a domain.

    .PARAMETER Application
        Specifies a list of applications to install during provisioning.
        This parameter accepts an array of values, each of which should be either
        a string or a hashtable.

        If a string is used, it should point to the path of the installer. Note
        that the installer will be run without any command-line arguments.

        If a hashtable is used, it should contain one or more of the following keys:

            - Path (required): Specifies the path to the application installer.
            - Name: Specifies the name of the application. Defaults to
                               the installer filename.
            - Command: Specifies the command executed during provisioning.
                               Defaults to 'cmd /c "<setup.exe>"', where <setup.exe>
                               is replaced with the name of the installer. Include this
                               key when you need to pass command-line arguments to the
                               executable (e.g. to cause an installer to run silently).
            - ContinueInstall: Indicates whether subsequent installations should continue
                               if the current install fails. Defaults to $true.
            - RestartRequired: Indicates whether or not to force a restart after installing
                               this application (and before proceeding with subsequent
                               installations). Defaults to $false.
            - RestartExitCode: Specifies the exit code returned by the installer that
                               indicates a restart is needed to complete installation.
                               Defaults to 3010.
            - SuccessExitCode: Specifies the exit code returned by the installer that
                               indicates the installation was successful. Defaults to 0.

    .PARAMETER Wifi
        Specifies a list of Wi-Fi profiles to configure during provisioning.
        This parameter accepts an array of hashtables, each containing
        one or more of the following keys:

            - Ssid (required): Specifies the Wi-Fi network name or SSID.
            - SecurityKey: If present, specifies the network security key
                               for a WPA2-Personal Wi-Fi network. Omit this
                               key if the network is open (unsecured).
            - AutoConnect: Indicates whether the target device should
                               automatically connect to this network when
                               in range. Defaults to $true.

    .PARAMETER Path
        Specifies the output directory to save the provisioning packages to.

    .PARAMETER Force
        Forces New-ProvisioningItem to overwrite existing files.

    .EXAMPLE
        New-ProvisioningPackage -ComputerName PC01, PC02 -LocalAdminCredential Admin

        Creates two provisioning packages (PC01.ppkg, PC02.ppkg), one for each computer
        specified in the ComputerName parameter. The packages will create a local
        administrator account named "Admin" on each computer.

    .EXAMPLE
        Get-Content computer-names.txt | New-ProvisioningPackage -LocalAdminCredential User
        -Application .\Office\setup.exe -Wifi @{ Ssid = 'Internal'; SecurityKey = 'HouseSpeakerB#' }


        Gets a list of computer names from computer-names.txt and pipes them
        to New-ProvisioningPackage, which generates a new package for each computer name.
        Each package will provision its respective device with a local administrator
        account named "User" and a Wi-Fi profile that connects to the Internal network
        with a security key of "HouseSpeakerB#". The package will also execute the
        ".\Office\setup.exe" installer during the provisioning process.

    .EXAMPLE
        $apps = @(
            'setup.exe',
            @{
                Path = 'C:\install.exe'
                Command = 'cmd /c "install.exe" /quiet'
                RestartRequired = $true
            }
        )
        $wifiProfiles = @(
            @{ Ssid = 'ContosoPrivate'; SecurityKey = 'CompanySecrets' }
            @{ Ssid = 'ContosoPublic' }
        )
        New-ProvisioningPackage -ComputerName Bob-Laptop -LocalAdminCredential admin
        -DomainName CONTOSO -DomainJoinCredential CONTOSO\Admin -Application $apps -Wifi $wifiProfiles


        Creates a provisioning package for computer name "Bob-Laptop". In addition to
        naming the computer, the provisioning package will join the device to the
        CONTOSO domain using the CONTOSO\Admin account and create a local admininistrator
        account named "admin". Two applications are specified for installation:
        setup.exe from the current directory, and C:\install.exe. The latter application
        will be run with the /quiet argument, and the device will restart after installation.
        The package will also configure two Wi-Fi profiles on the target device: the ContosoPrivate
        WPA2-Personal network with a security key of CompanySecrets, and the open ContosoPublic network.

    .NOTES
        For more information about provisioning packages, visit
        https://docs.microsoft.com/en-us/windows/configuration/provisioning-packages/provisioning-packages
    #>


    [CmdletBinding(
        DefaultParameterSetName = 'Workgroup',
        SupportsShouldProcess = $true,
        ConfirmImpact = 'Low'
    )]
    param (
        [Parameter(
            Mandatory = $true,
            Position = 0,
            ValueFromPipeline = $true
        )]
        [ValidatePattern('^[A-Za-z0-9-]{1,63}$',
            ErrorMessage = 'The computer name "{0}" is invalid. ' +
            'Supply a name composed of letters, numbers, and hyphens that is between 1 and 63 characters long.'
        )]
        [string[]]
        $ComputerName,

        [Parameter(
            Mandatory = $true,
            Position = 1
        )]
        [pscredential]
        $LocalAdminCredential,

        [Parameter(
            ParameterSetName = 'Domain',
            Mandatory = $true
        )]
        [string]
        $DomainName,

        [Parameter(
            ParameterSetName = 'Domain',
            Mandatory = $true
        )]
        [pscredential]
        $DomainJoinCredential,

        [object[]]
        $Application,

        [hashtable[]]
        $Wifi,

        [string]
        [PSDefaultValue(Help = 'Current directory')]
        $Path = (Get-Location).Path,

        [switch]
        $Force
    )

    begin {
        $icdPath = Join-Path -Path $PSScriptRoot -ChildPath '..\icd\ICD.exe'
    }

    process {
        $ComputerName | ForEach-Object -Process {
            $currentComputerName = $_
            $params = @{
                ComputerName         = $currentComputerName
                LocalAdminCredential = $LocalAdminCredential
                DomainName           = $DomainName
                DomainJoinCredential = $DomainJoinCredential
                Application          = $Application
                Wifi                 = $Wifi
            }
            $customizationsArgs = Get-CustomizationsArg @params
            $doc = New-CustomizationsXmlDocument @customizationsArgs
            $ppkgPath = Confirm-PackagePath -ComputerName $currentComputerName -Path $Path -Force:$Force

            if ($ppkgPath -and $PSCmdlet.ShouldProcess("Paths: $ppkgPath", "Build Provisioning Package")) {

                # Generate filename and save the XML doc to disk
                $guid = (New-Guid).ToString('D')
                $xmlPath = Join-Path -Path $env:TEMP -ChildPath "$guid.xml"
                Set-XmlContent -XmlDocument $doc -Path $xmlPath -Confirm:$false

                try {
                    # Run ICD.exe to generate the provisioning package
                    $icdArgs = Get-IcdArg -IcdPath $icdPath -XmlPath $xmlPath -PackagePath $ppkgPath -Overwrite $Force
                    $icdLogPath = Join-Path $env:TEMP -ChildPath 'ProvisioningTools-ICD.log'
                    $startProcessArgs = @{
                        FilePath              = $icdPath
                        ArgumentList          = $icdArgs
                        WindowStyle           = 'Hidden'
                        Wait                  = $true
                        Confirm               = $false
                        RedirectStandardError = $icdLogPath
                    }
                    Start-Process @startProcessArgs
                }
                finally {
                    # ICD.exe also generates a .cat file in addition to the .ppkg file.
                    # We don't need it, so delete it, along with our customizations XML
                    $catPath = Join-Path -Path $Path -ChildPath "$($currentComputerName).cat"
                    Remove-Item -Path $catPath -ErrorAction SilentlyContinue -Confirm:$false
                    Remove-Item -Path $xmlPath -ErrorAction SilentlyContinue -Confirm:$false
                }

                if (Test-Path $ppkgPath) {
                    Remove-Item $icdLogPath -ErrorAction SilentlyContinue
                }
                else {
                    Write-Error "Couldn't find the output package. Please see $icdLogPath for details."
                }
            }
        }
    }
}