Registry.SetValue Method (String, String, Object, RegistryValueKind)
Sets the name/value pair on the specified registry key, using the specified registry data type. If the specified key does not exist, it is created.
Assembly: mscorlib (in mscorlib.dll)
static member SetValue : keyName:string * valueName:string * value:Object * valueKind:RegistryValueKind -> unit
- Type: System.String
The full registry path of the key, beginning with a valid registry root, such as "HKEY_CURRENT_USER".
- Type: System.String
The name of the name/value pair.
- Type: System.Object
The value to be stored.
- Type: Microsoft.Win32.RegistryValueKind
The registry data type to use when storing the data.
value is a null reference (Nothing in Visual Basic).
keyName does not begin with a valid registry root.
keyName is longer than the maximum length allowed (255 characters).
The type of value did not match the registry data type specified by valueKind, therefore the data could not be converted properly.
The RegistryKey is read-only, and thus cannot be written to; for example, it is a root-level node, or the key has not been opened with write access.
The user does not have the permissions required to create or modify registry keys.
Starting with the .NET Framework version 4, the valueName parameter is no longer restricted to a maximum of 255 characters; however, the keyName parameter continues have the 255-character restriction.
Because many values can be stored in each key in the registry, you must use the valueName parameter to specify the particular value you want to set.
A registry key can contain one value that is not associated with any name. When this unnamed value is displayed in the registry editor, the string "(Default)" appears instead of a name. To set this unnamed value, specify either a null reference (Nothing in Visual Basic) or the empty string ("") for valueName.
If valueName does not exist in the key, it is created and the associated value is set to value.
If keyName specifies a subkey that does not exist, the subkey is created in the specified root. For example, in Visual Basic the string "HKEY_CURRENT_USER\MyTestKey" creates the subkey "MyTestKey" in the HKEY_CURRENT_USER root. The string "HKEY_CURRENT_USER\MyTestKey\Key2\Key3" creates the nested subkeys "MyTestKey", "MyTestKey\Key2", and "MyTestKey\Key2\Key3".
Valid root names include HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, HKEY_PERFORMANCE_DATA, HKEY_CURRENT_CONFIG, and HKEY_DYN_DATA.
The SetValue method opens a registry key, sets the value, and closes the key each time it is called. If you need to modify a large number of values, the RegistryKey.SetValue method might provide better performance. The RegistryKey class also provides methods that allow you to add an access control list (ACL) to a registry key, to test the data type of a value before retrieving it, and to delete keys.
If the type of the specified value does not match the specified valueKind, and the data cannot be converted, ArgumentException is thrown. For example, you can store a System.Int64 as a RegistryValueKind.DWord, but only if its value is less than the maximum value of a System.Int32. You cannot store a single string value as a RegistryValueKind.MultiString.
On Windows 98 and Windows Millennium Edition (Windows Me), the registry is not Unicode, and not all Unicode characters are valid for all code pages. A Unicode character that is invalid for the current code page is replaced by the best available match. No exception is thrown.
The following code example stores values of several data types in an example key, creating the key as it does so, and then retrieves and displays the values. The example demonstrates storing and retrieving the default (nameless) name/value pair, and the use of defaultValue when a name/value pair does not exist.
Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.