Web Deploy dirPath Provider
Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, Windows Vista, Windows XP
The dirPath provider synchronizes directory content.
msdeploy -verb:sync -source:dirPath=c:\OriginalSite -dest:dirPath=c:\NewSite
The dirPath provider returns the directory path for the folder and subfolders specified in the -source argument, or synchronizes the source folder to the destination folder specified in the -dest argument. The dirPath provider takes an argument that is the full path of a file system directory (for example, c:\inetpub\wwwroot). UNC paths and mapped network drives are supported. Environment variables like %windir% are supported, but wildcard characters are not. If the path contains spaces, the path must be enclosed in double quotation marks.
In a dump operation, the file paths for the specified directory and the files and folders underneath it are recursively returned. If you also specify the -xml operation setting, the results are returned in XML format and include file attribute information. To view ACL information in the attribute output, use the includeAcls provider setting, as in the following example.
msdeploy -verb:dump -source:dirpath="c:\inetpub\temp",includeAcls=true -xml
In a sync operation, if the source folder does not exist on the destination, the provider creates the folder and any subfolders that have the corresponding files and attributes. If the destination folder already exists, the provider updates only those objects that do not match the source. This means that in some cases only one file or folder will be updated. Folder and file attribute information are also updated to match the source. For example, if the destination folder is not marked as hidden but the source folder is, the destination folder will become hidden. Files on the destination that do not exist on the source will be deleted. The source and destination folders for dirPath do not have to have the same name. If the name of the destination folder differs from that of the source, the name of the destination folder will remain the same, but the contents of the folder will be updated to those of the source.
If you use the dirPath provider for the source and the archiveDir provider for the destination, the archiveDir destination folder must not be inside the folder that you specify for dirPath.
Because the FAT file system cannot preserve NTFS file system ACLs, you should not synchronize files from an NTFS file system to a FAT file system. If you do so, no warning will be issued. Note that, in any case, Windows Server® 2008 (and IIS 7) cannot be installed on FAT32 file systems. For security reasons, the use of IIS 6.0 on FAT file systems is not recommended.
The dirPath provider does not automatically synchronize permissions. If you want to copy permissions, you can set the includeAcls provider setting to true so that ACLs will be included in the synchronization. The permissions are copied as security identifiers (SIDs). If you are using local accounts, the destination computer must have the same accounts that use the same SIDs for the permissions to be set correctly.
By default, includeAcls is false. Files that are created on the destination will inherit their ACLs from the destination.
The dirPath provider has a custom provider setting, ignoreErrors, that is also used by the filePath provider.
The ignoreErrors feature is not available in the Release Candidate (RC) version of the Web Deployment Tool.
ignoreErrors specifies a semicolon-delimited list of file system error codes that will be ignored during an operation. For the errors specified, a warning will be issued, but the operation will continue. If ignoreErrors is not specified, no file system errors will be ignored.
The ignoreErrors provider setting is useful because it lets you ignore errors on folders and files that you can safely ignore or copy later. It lets you avoid the frustration of having a synchronization operation fail because of errors that you consider to be relatively minor.
Usage 1: dirPath=<path>,ignoreErrors=<ErrorNumber>[;<ErrorNumber>;…]
msdeploy -verb:sync -source:dirpath=c:\Site1 -dest:dirpath=c:\Site2,ignoreErrors=0x80070005
<ErrorNumber> is a file system error number. For example, 0x80070005 is the Access Denied error. The "0x" prefix is required. <ErrorNumber> cannot be a range of values. If no error number is specified, no file system errors will be ignored.
If a sync operation attempts to delete a folder in which a file is being used and you have specified
,ignoreErrors=0x80070020(File In Use error) in the command, the file will be skipped, but the directory deletion will fail because the directory is not empty and therefore cannot be deleted.
Beware of possible file corruption on the destination computer when you use the ignoreErrors provider setting under the following conditions.
- A file on the source is different from the file on the destination.
- The file on the source is being used (and is therefore locked.)
- In the command for the sync operation, you specified
,ignoreErrors=0x80070020for the dirPath or filePath providers.
Using ignoreErrors with the contentPath provider
The contentPath provider uses both the filePath and dirPath providers. When you use the contentPath provider, you can take advantage of this relationship by using the following syntax.
Usage 2: contentPath=<path>,dirPath.ignoreErrors=<ErrorNumber>[;<ErrorNumber>;…]
Notice that in this usage, ignoreErrors is preceded by a period.
msdeploy -verb:sync -source:contentPath=c:\Site1 -dest:contentPath=c:\Site2,dirpath.ignoreErrors=0x8000020;0x80070005
The example specifies that the contentPath provider will copy the content of Site1 to Site2. During the copy operation, if any folders in the destination produce File In Use or Access Denied errors, the errors will be ignored, and the operation will continue.
The dirpath provider will automatically pass the ignoreErrors settings to the filePath provider as needed. Although it is not required, you can make this explicit in the command by adding
,filepath.ignoreErrors=0x8000020;0x80070005 to the original command, as the following example shows.
msdeploy -verb:sync -source:contentPath=c:\Site1 -dest:contentPath=c:\Site2,dirpath.ignoreErrors=0x8000020;0x80070005,filepath.ignoreErrors=0x8000020;0x80070005
Related Web Deploy Rules
The following rules are related to the dirPath provider.
Allows files to remain on the destination that are not on the source. This rule is disabled by default.
Ignores the last write times of files and compares them based on checksums when the
Skips updates to files that have a more recent write time. This rule is disabled by default.
These rules can be enabled or disabled by using the
-disableRule operation settings. For more information about these rules and operation settings, see Web Deploy Rules.
These rules and the
-useCheckSum operation setting are not available in the Release Candidate (RC) version of the Web Deployment Tool.
1) Display the file path information from the specified folder.
msdeploy -verb:dump -source:dirPath=c:\Webdeploy\sourcefolder
2) Display the file path information from the specified folder. The specified path contains spaces, so it is enclosed by double quotation marks.
msdeploy -verb:dump -source:dirPath="c:\Web Deploy\source folder"
3) Synchronize the contents of two folders.
msdeploy -verb:sync -source:dirPath=c:\webdeploy\sourcefolder -dest:dirPath=c:\webdeploy\destinationFolder
4) Set the includeAcls provider setting to true to specify that ACLs will be copied from the source to the destination.
msdeploy -verb:sync -source:dirPath=c:\inetpub\wwwroot,includeAcls=true -dest:dirPath=c:\inetpub\wwwroot,computername=Server1