Web Deploy PowerShell Cmdlets
by Owais Shaikh
Web Deploy V3.0 ships with PowerShell cmdlets for carrying out most of the tasks supported by the Web Deploy API [Microsoft.Web.Deployment]. You can read more about this API here. These cmdlets are in the snapin named WDeploySnapin3.0 which is installed and registered as a snapin on a typical or higher install of web deploy. To use these cmdlets either add the snapin every time the PowerShell console is started or add the snapin to the PowerShell profile which will make all consoles automatically load the snapin.
To add when PowerShell console is loaded, run the following command in the console window:
Add-PSSnapin WDeploySnapin3.0
To add it to the PowerShell profile:
- If you already have a PowerShell profile, go to step 4.
- Create a WindowsPowerShell folder under <My Documents>.
- Create a file called Microsoft.PowerShell_profile.ps1
- Add this line to the PowerShell profile file: 'Add-PSSnapin WDeploySnapin3.0'
A few points to note:
- PowerShell console runs in 64 bit on 64 bit systems and runs in .Net 2.0 except until Windows8. If you face issues because of one or both of these refer to the troubleshooting section for solutions.
- All cmdlets that create a Web Deploy package create parameters for the most common tasks and the cmdlets that consume it accept parameter values.
- There is only one removal cmdlet for deleting a site or an app beneath it.
- Web Deploy has parameters but they are orthogonal to PowerShell cmdlet parameters. When parameters are referred to in this document, it implies cmdlet parameters. Web Deploy parameters have been specifically called out as Web Deploy parameters.
I. Publish Settings File
All of the cmdlets given below have the ability to execute against a remote artifact such as a remote server or a remote database. These require more than just the credentials. For e.g. you need the remote server name, the remote database connection string, whether you want to allow publishing to a server with a test certificate etc. For ease of use, transfer of credential information from server admin to consumer etc. a new file type has originated which groups these settings together. This file is called the publish settings file ending in .publishsettings. This is used by Visual Studio for publishing as well as by WebMatrix.
To be able to create such a file for consumption by other cmdlets and to edit it New-WDPublishSettings cmdlet can be used. If no filename is specified it will create a new file in your documents directory with the name <new guid>.publishsettings. This path will be displayed when the file is created. If a filename is specified and the file does not exist it will be created as described above in the folder specified by the path, however the path to the file must be valid. If the file exists only the values for the attributes that you specified while running the command will be modified, except for the attributes in the file which are unknown and will get removed
Example: This example gets a credential object and then passes it to the new publish settings file cmdlet along with other parameters
$cred = Get-Credential
New-WDPublishSettings -ComputerName owais-1 -Site Site1 -Credentials $cred -AllowUntrusted -SiteUrl "https://www.mywebsite.com" -FileName C:\pprofiles\mywebsite.publishsettings -AgentType wmsvc
Get-WDPublishSettings cmdlet allows to load values from a publish setting file into PublishSettings object.
$publishsettings=Get-WDPublishSettings C:\pprofiles\mywebsite.publishsettings
II. Backup
All backup cmdlets have a positional parameter (it's the second one except for backup-wdserver where it is the first positional parameter) called output. This takes a path to the folder where you want the backup created. Backup is always a Web Deploy zip package. You can read more about Web Deploy Packages at Package Provider. If no path is specified the backups are created in a folder named 'Web Deploy Backups' under the user's documents folder. The backups are named as machinename_nameofproviderused_[Siteorapporfoldername(Optional)]_timestamp.zip.
All these cmdlets will work locally by default unless remote server information is provided by passing in a publish settings file for SourcePublishSettings parameter.
A. IIS
All IIS cmdlets will work against installed IIS version 7 or higher
1. Server
Backup-WDServer
Description: This without any arguments backs up the current server where this command is run. It uses the well-known webserver provider for this operation. Hence the package created contains all the artifacts that would be contained in a webserver package. You can read more about this provider here.
Cmdlet Parameters: ConfigOnly parameter allows you to exclude all content while SkipFileList and SkipFolderList parameters allow you to selectively exclude one or more files or folders from the package.
Examples:
This will back up everything of the web server except for the content:
Backup-WDServer -SourcePublishSettings c:\profiles\myserver.publishsettings -ConfigOnly
Create a list of the files that should be skipped. This is standard regular expressions.
$list = @('\\site2\\iisstart.htm','\\site2\\welcome.png')
Backup-WDServer –SkipFileList $list
You can also change this to skip all files under site2 by changing the list to $list=@('\site2\')
2. Site
Backup-WDSite
Description: This will back up an IIS site along with its settings and content using apphostconfig provider. You can read more about this provider here.
Cmdlet Parameters: The name of the site specified by the site parameter or by the publish settings file is backed up. Site parameter value overrides publish settings specification for site name.
ConfigOnly can be used to create a backup with no content. If the site uses a non-default app pool then to make this package work on other servers that might not have the same application pool, use the switch parameter includeAppPool. This will bundle the application pool into the package.
Auto generated Web Deploy parameters: Two types of parameters are created:
- A parameter to enable the user to change the name of the site where the site backup will be applied.
- Another parameter to enable the user to change the physical path of the site and every web application under that site.
So if I have a site with three apps beneath I will get 4 physical path parameters apart and one site name parameter.
Examples:
Backup-WDSite "Default Web Site" -ConfigOnly
Backup-WDSite MySite –IncludeAppPool
Backup-WDSite MySite -SkipFileList $list
3. Web Application
Backup-WDApp
Description: This will back up a web application using iisApp provider. Read more about this provider here. Here is a good article that explains what a web application is and what is the difference between a site, an app and a virtual directory in IIS.
Cmdlet Parameters: The name of the app specified by the application parameter or by the publish settings file is backed up. If none of them is specified it throws an error. Application parameter value overrides publish settings specification for site name. SkipFileList and SkipFolderList parameters allow you to selectively exclude one or more files or folders from the package.
Auto generated Web Deploy parameters: A Parameter for changing the name of the app or site during restore or install is created.
$list = @('\\iisstart\.htm')
Backup-WDApp "Default web site/app" -SkipFileList $list
B. Database
1. MSSql
Backup-WDSqlDatabase
Description: This will back up a Microsoft SQL Server Database using the dbfullsql provider. This provider uses SMO to script out the database and exposes more than 100 provider settings to control the way the database is scripted. This is covered in detail here.
Cmdlet Parameters: The connection string specified by the Database parameter or SQLServerDBConnectionString in the publish settings file is backed up. Database parameter value overrides publish settings specification for SQLServerDBConnectionString. The provider settings exposed by this dbfullsql provider can be passed using SourceSettings parameter. One very commonly used setting is scriptdropsfirst which scripts if object exists drop object scripts. Another provider setting from the SMO scripting options is to set scriptdata to false to just extract schema.
Auto generated Web Deploy parameters: A parameter is created for changing the database connection string during restore or install
Examples:
New-WDPublishSettings -ComputerName serverName -MSSqlConnectionString "Data Source=localhost;Initial Catalog=MyDb;User id=MyDbUser;Password=MyPassword" -FileName d:\SQLdb.PublishSettings -Credential serverName\Administrator
Backup-WDSQLDatabase -SourcePublishSettings D:\SQLdb.PublishSettings
Backup-WDSQLDatabase -Database "Data Source=localhost;Initial Catalog=MyDb;User id=MyDBUser;Password=MyPassword" -SourceSettings @{ copyAllUsers='false'; scriptDropsFirst='true'; }
2. MySql
Backup-WDMySQLDatabase
Description: This will back up a MySql Server Database using the dbmysql provider. This provider uses mysqldump to script out the database. This is covered in detail here.
Cmdlet Parameters: The connection string specified by the Database parameter or mySQLDBConnectionString in the publish settings file is backed up. Database parameter value overrides publish settings specification for mySQLDBConnectionString. The provider settings can be passed using SourceSettings parameter. The commonly used settings are includeData and includeSchema. By default these are set to true.
Auto generated Web Deploy parameters: A parameter is created for changing the database connection string during restore or install
New-WDPublishSettings -ComputerName serverName -MySqlConnectionString "Data Source=localhost;database=MyDb;Uid=MyDbUser;pwd=MyPassword" -FileName d:\MySQLdb.PublishSettings -Credential serverName\Administrator
Backup-WDMySQLDatabase -Database 'Server=localhost;Database=MyDb;Uid=MyDbUser;pwd=MyPassword’
Backup-WDMySqlDatabase –SourcePublishSettings d:\mysqldb.publishsettings
III. Restore
All restore cmdlets take the Web Deploy package to restore as the first positional parameter.
WebDeploy supports the concept of parameterization of the packages, which lets you change few aspects during restore (without modifying package). For example during restore, you can choose to specify value of database connection string which is different from what is inside the package using WebDeploy parameters (you need to have connection string parameter present in the package.)
Depending upon how package was built, Web Deploy package might have one or more parameters. These restore cmdlets inspect the package and add dynamic PowerShell parameters to the collection. So if a package has a Web Deploy parameter named "Parameter1" then you will find a PowerShell parameter with the name "Parameter1". However dynamic parameters have their own issues in PowerShell and this will only work if packages don't have a space in their name or in the path to the file.
Alternatively, all these restore cmdlets also have a "Parameters" parameter which allows you to manually specify new parameter values during restore. This "Parameters" parameter takes PowerShell Dictionary object for the name value pairs of Web Deploy parameters.
To find out the Web Deploy parameters defined in any Web Deploy package you can simply open the zip file in Windows Explorer and examine the parameters.xml file present in the root of the package. Any Web Deploy parameter that does not have a default value or a value needs a value to be specified. Add all of these parameters in an xml file and pass it in as the value for ParameterValuesFile parameter. You can generate this file as given in here or manually. The format is
<parameters>
<setParameter name="name1" value="value1" />
<setParameter name="name2" value="value2" />
</parameters>
Get-WDParameters cmdlet can read this file and convert it into WebDeploy parameters object (dictionary), which is accepted by all restore cmdlets.
If any package is restored without specifying a value for the parameters within, the default behavior would be overwrite the resources from which the package was originally created. For e.g. if I create a package from site1 using backup-wdsite site1, then when I restore this package using the restore cmdlet without providing any values to the parameters in this package, site1 will be overwritten with whatever the package contains, content as well as config. Same is true for all restore cmdlets.
All these cmdlets restore locally except when destination publish settings file is specified, in which case the same exact operation would occur against a remote server via Web Management Service (WMSvc) or the Web Deployment Agent service.
A. IIS
1. Server
Restore-WDServer
Description: Restores a web server package. Common usage is to back up a server before making a change and in case of failure the server can be reverted by applying the Web Deploy backup package created before making the changes.
$folderList = @(‘\\app_data’)
Restore-WDServer D:\OWAIS-1_WebServer_20120419121214.zip -DestinationPublishSettings c:\destinationServer.publishSettings –SkipFolderList $folderList
2. Site
Restore-WDSite
Description: Restores an IIS Site package. If the package has two parameters named "Site Physical Path" and "Site Name" they will be exposed as SitePhysicalPath and SiteName dynamic powershell parameter. This command will create a new site site1 with physical path c:\site1. If no value is specified for these parameters, restore will apply to the same site and content, overwriting any changes you might have in the site.
Parameters: You might want to use skipfolderlist and skipfilelist to exclude some folders and/or files from being copied in site contents.
Restore-WDSite C:\defaultsite.zip -SitePhysicalPath c:\site1 -SiteName site1
Restore-WDSite -Package 'D:\Users\Administrator\Documents\Web Deploy Backups\IIS-Server_AppHostConfig_Default Web Site_20120417100827.zip' -skipFolderList @('App_Data') -verbose
3. App
Restore-WDApp
Description: This will restore a web application. Backup-WDApp creates package with one parameter to change the name of the app at install time. This can be used to restore the app to a different app during restore. The site must exist when deploying to an app under a site. App will be created by this package but site will not be created.
Examples:
Restore-WDApp C:\myappbackup.zip -ApplicationPathParam1 "Default web site\app1"
B. Database
Restore-WDDatabase
Description: If the database does not exist, this will create a new database called customers (as long as the current user has permissions for this operation) and execute the script on it. If this is run without any values for dynamic Web Deploy parameters the original database from which this package was created will be overwritten. Note that if scriptDropsFirst setting was not used when creating the package, then applying to a database with conflicting existing content will fail. This cmdlet may be used to restore either an MSSql or MySQL backup. You can only restore a MS SQL database with a backup created using Backup-WDSQLDatabase and My SQL database with a backup created using Backup-WDMySqlDatabase.
Examples:
Backup-WDSqlDatabase "server=.\sqlexpress;integrated security=SSPI;database=customers" "C:\dbbackup.zip"
Restore-WDDatabase c:\dbbackup.zip –DatabaseConnectionStringParam1 "server=.\sqlexpress;integrated security=SSPI;database=customers_copy"
Backup-WDMySqlDatabase "server=localhost;uid=someuser;pwd=somepwd;database=coolDb" "C:\dbbackup.zip"
Restore-WDDatabase c:\dbbackup.zip –DatabaseConnectionStringParam1 "server=localhost;uid=someuser;pwd=somepwd;database=coolDb_copy"
C. Generic Package
Restore-WDPackage
Description: This cmdlet can be used to apply any Web Deploy package. There are several ways to create or obtain a Web Deploy package, such as by downloading an open source Application Gallery package, creating a package in Visual Studio, using the msdeploy.exe command-line tool (more info), or using the Backup-WD* cmdlets noted earlier in the document. For e.g. for installing wordpress on an IIS Server Default web site as an app named wordpress download the wordpress package from the app gallery into a folder called packages. All the default values for the wordpress package parameters will work as is but just need to specify the values for two required parameters: admin and non admin mysql password.
Parameters:
Restore-WDPackage c:\Packages\wordpress.zip -DBAdminPassword mysecretserverpassword –DBPassword mysqllocalpassword
IV. Remove
Remove-WDSite -Site NonWorkingSite
This command will delete the site named nonworkingsite's definition in applicationHost.config as well as the site's directory contents
V. Get & Set App pool Framework
These cmdlets let you read and change the apppool .net framework version.
Get-WDAppPoolFx "default web site"
managedRuntimeVersion
---------------------
v2.0
Set-WDAppPoolFx "default web site" -AppPoolFrameworkVersion v4.0
Get-WDAppPoolFx "default web site"
managedRuntimeVersion
---------------------
v4.0
VI. Set WDACL
This cmdlet can be used to set acls on the content of a site. For e.g. Lets say I have a site, site1 and I am trying to give user u1 read access.
First I check the current permissions.
$ret = Get-Acl C:\site1
$ret.Access
I don’t see u1 in the list. Let me give the user u1 access as follows
Set-WDAcl "site1" -SetAclUser u1
Check whether this worked
$ret = Get-Acl C:\site1
$ret.Access
I see that u1 has been given read access as below. [I have not pasted the other permissions on this folder. Just the u1 part]
FileSystemRights : Read, Synchronize
AccessControlType : Allow
IdentityReference : MOSHAIKH1\u1
IsInherited : False
InheritanceFlags : ContainerInherit, ObjectInherit
PropagationFlags : None
VII. Invoke
You can invoke commands or scripts on a remote system using destinationpublishsettings and the see the results of the remote execution in real time. You have to be an admin on the remote system to be able to execute runcommand provider remotely. You can read more about this provider here. The default maximum time MWD Api waits for the given script or command to finish is 5 seconds. If you want to increase this time of execution, you can specify higher values for waitInterval and waitAttempts as shown in the example below.
A. Script
Invoke-WDScript C:\my.cmd –Verbose
This will execute the script and you will be able to see the output of the command if you run it with verbose.
B. Command
$settings = @ { waitInterval = 3000; waitAttempts = 25;}
Invoke-WDCommand "dir c:\mydirectory /s/b" -DestinationSettings $settings
This will execute the command and no output will be displayed since verbose was not specified. However this will wait for 3 seconds between every time lapse and will do 25 iterations of wait. In all, the process execution will continue at the most for 75 seconds.
VIII. Sync
These cmdlets take a source and a destination and synchronize between them. The source is never modified. The reason I am using the word source instead of client is because client and server are very confusing terms in synchronization. You can potentially sync the local server with a remote server. In this case the remote server is the source and local server is the destination. Alternatively you can be executing the PowerShell cmdlet on machine 1 and syncing machines 2 and 3. In order to use a remote source and / or destination you need to provide a publish settings file which can be created using the first cmdlet mentioned in this doc. All the sync cmdlets also support sourceSettings and destinationSettings parameters to be able to selectively set provider settings for either the source or destination or both.
A. IIS
1. Server
I want to sync two IIS 7.5 servers, Owais-1 and Owais-2. I will first create a publishsettings file for each and then sync the servers. Since I did not specify my credentials this will succeed if I am an admin on those two systems.
New-WDPublishSettings -ComputerName owais-1 -AgentType MSDepSvc -FileName c:\owais1.publishsettings
Publish settings file created at: 'c:\owais1.publishsettings'.
New-WDPublishSettings -ComputerName owais-2 -AgentType MSDepSvc -FileName c:\owais2.publishsettings
Publish settings file created at: 'c:\owais2.publishsettings'.
Sync-WDServer -SourcePublishSettings c:\owais1.publishSettings -DestinationPublishSettings c:\owais2.publishSettings
2. Site
In the following command, the site2 will get created if it did not exist and I have also changed the physical path (the contents will thus get copied to the new folder c:\site2) and the binding of the site.
Sync-WDSite site1 Site2 -SitePhysicalPath c:\site2 -SiteBinding "*:8078:" -IncludeAppPool
3. App
I have an application running under default web site. I want to move this under Site1. The following command will do it.
Sync-WDApp "Default Web Site/drupal" "site1/drupal"
Now that I have tested my new drupal app works I will delete the original drupal app under default web site.
Remove-WDSite "Default Web Site/drupal"
B. Database
The previous cmdlets have shown how you can backup and restore a database using a Web Deploy package, however you can also sync a database to or from a .sql script or sync directly to another database instance using the Sync-WDSQLDatabase and Sync-WDMySQLDatabase cmdlets.
1. MSSql
Sync-WDSQLDatabase "server=.\sqlexpress;uid=sa;pwd=********;database=umbracodb" "server=.\sqlexpress;uid=sa;pwd=************;database=sometestdb"
This will create a new database called sometestdb (if it does not exist already) and synchronize schema and data.
Sync-"server=.\sqlexpress;uid=sa;pwd=********;database=umbracodb" c:\umbraco.sql
This will script out the umbracodb database into umbraco.sql at the path given above.
2. MySql
Sync-WDMySQLDatabase "server=localhost;uid=root;pwd=********;database=wordpress265" "server=localhost;uid=root;pwd=************;database=wordpress265_new"
This will create a new database called wordpress265_new (if it does not exist already) and synchronize schema and data.
Sync-WDMySQLDatabase "server=localhost;uid=root;pwd=***************;database=wordpress265" c:\wordpress.sql
This will script out the wordpress265 database into wordpress.sql at the path given above.
C. Everything else
For general purpose sync not covered by other cmdlets given above, you can use Sync-WDManifest cmdlet. This is a general manifest provider sync supported by the MWD API. You can read more about it here. Manifest is a collection of providers, provider paths and provider settings in an xml file. The structure is that the root node of the xml file is considered the name of a provider for the purpose of the current sync. Hence it cannot be the name of any of the well-known providers as given in the list here. Then it can have child nodes with the element name matching the provider you want to include in the sync. A path attribute represents the path of that provider and it is mandatory. Then add attribute value pairs for each provider setting that you want to leverage for the current sync operation.
This cmdlet needs two manifests: One for the source and one for the destination. The manifest is always executed in the order specified. If the provider supports a commit operation such as apphostconfig provider which works with IIS Sites, the commit is not called unless the sync is complete. Hence if you have a provider that expects a site to exist after a provider that creates it, then this will fail since the site has not been committed yet. In the following example I will synchronize an app and include a database that the app uses along with it in the manifest.
Source Manifest:
<demoManifest>
<iisApp path="Site1" />
<dbfullsql path="server=.\sqlexpress;integrated security=SSPI;database=customers" />
</demoManifest>
Destination Manifest:
<demoManifest> <iisApp path="Site2" /> <dbfullsql path="server=.\sqlexpress;integrated security=SSPI;database=customers_demo_cpy" /></demoManifest>Sync-WDManifest C:\sourceManifest.xml C:\destManifest.xmlWARNING: Cannot connect to the database 'customers_demo_cpy'.Retrying operation 'Add' on object dbFullSql (server=.\sqlexpress;uid=sa;database=customers_demo_cpy). Attempt 1 of 5.Manifest : C:\sourceManifest.xmlManifest-Dest : C:\destManifest.xmlTimeTaken : 0:10Errors : 0Warnings : 0BytesCopied : 0ObjectsDeleted : 0ObjectsUpdated : 0ObjectsAdded : 3TotalChanges : 3ParameterChanges : 0