Rename method of the Win32_Directory class

Article
01/06/2021

The Rename WMI class method renames the directory entry file specified in the object path. A rename is not supported if the destination is on another drive or if overwriting an existing logical file is required.

This topic uses Managed Object Format (MOF) syntax. For more information about using this method see Calling a Method.

Syntax

uint32 Rename(
   string FileName
);

Parameters

FileName: Fully qualified new name of the file (or directory). Example: c:\temp\newfile.txt.

Return value

Returns a value of 0 (zero) if the file was successfully renamed, and any other number to indicate an error.

0: The request was successful.
2: Access was denied.
8: An unspecified failure occurred.
9: The name specified was not valid.
10: The object specified already exists.
11: The file system is not NTFS.
12: The platform is not Windows.
13: The drive is not the same.
14: The directory is not empty.
15: There has been a sharing violation.
16: The start file specified was not valid.
17: A privilege required for the operation is not held.
21: A parameter specified is not valid.

Remarks

To rename a folder, first bind to the folder in question and then call the Rename method. As the sole parameter to the method, pass the new name for the folder as a complete path name. For example, if the folder in the C:\Scripts\Logs\Backup is to be renamed C:\Scripts\Archive, you must pass C:\Scripts\Archive as the complete folder name. Passing only the folder name - Archive - results in an Invalid path error.

The Win32_Directory class does not provide a one-step method for moving folders. Instead, moving a folder generally involves two steps:

1. Copying the folder to its new location 2. Deleting the original folder

The one exception to this two-step process involves moving a folder to a new location on the same drive. For example, suppose you want to move C:\Temp to C:\Scripts\Temporary Files\Archive. As long as the current location and the new location are on the same drive, you can move the folder by simply calling the Rename method and passing the new location as the method parameter. This approach effectively allows you to move the folder in a single step. However, the script fails if the current drive and the new drive are different. An attempt to rename C:\Temp to D:\Temp fails with a "Drive not the same" error.

Examples

The following code uses the Rename method to move the folder C:\Scripts to C:\Admins\Documents\Archive\VBScript.

strComputer = "." 
Set objWMIService = GetObject("winmgmts:" _ 
    & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2") 
 
Set colFolders = objWMIService.ExecQuery _ 
    ("Select * from Win32_Directory where name = 'c:\\Scripts'") 
 
For Each objFolder in colFolders 
    errResults = objFolder.Rename("C:\Admins\Documents\Archive\VBScript") 
Next

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Namespace	Root\CIMV2
MOF	CIMWin32.mof
DLL	CIMWin32.dll