Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Registry.SetValue Method (String, String, Object)

Sets the specified name/value pair on the specified registry key. If the specified key does not exist, it is created.

Namespace:  Microsoft.Win32
Assembly:  mscorlib (in mscorlib.dll)
'Declaration
Public Shared Sub SetValue ( _
	keyName As String, _
	valueName As String, _
	value As Object _
)

Parameters

keyName
Type: System.String
The full registry path of the key, beginning with a valid registry root, such as "HKEY_CURRENT_USER".
valueName
Type: System.String
The name of the name/value pair.
value
Type: System.Object
The value to be stored.
ExceptionCondition
ArgumentNullException

value is Nothing.

ArgumentException

keyName does not begin with a valid registry root.

-or-

keyName is longer than the maximum length allowed (255 characters).

UnauthorizedAccessException

The RegistryKey is read-only, and thus cannot be written to; for example, it is a root-level node.

SecurityException

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 to 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.

NoteNote

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 Nothing 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.

NoteNote

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.

This overload of SetValue stores 64-bit integers as strings (RegistryValueKind.String). To store 64-bit numbers as RegistryValueKind.QWord values, use the SetValue(String, String, Object, RegistryValueKind) method overload.

This overload of SetValue stores all string values as RegistryValueKind.String objects, even if they contain expandable references to environment variables. To save string values as expandable strings (RegistryValueKind.ExpandString), use the SetValue(String, String, Object, RegistryValueKind) method overload.

This overload is equivalent to calling the SetValue(String, String, Object, RegistryValueKind) method overload with RegistryValueKind.Unknown.

NoteNote

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.


Imports System
Imports Microsoft.Win32

Public Class Example
    Public Shared Sub Main()
        ' The name of the key must include a valid root.
        Const userRoot As String = "HKEY_CURRENT_USER"
        Const subkey As String = "RegistrySetValueExample"
        Const keyName As String = userRoot & "\" & subkey

        ' Integer values can be stored without specifying the
        ' registry data type, but Long values will be stored
        ' as strings unless you specify the type. Note that
        ' the integer is stored in the default name/value
        ' pair.
        Registry.SetValue(keyName, "", 5280)
        Registry.SetValue(keyName, "TestLong", 12345678901234, _
            RegistryValueKind.QWord)

        ' Strings with expandable environment variables are
        ' stored as ordinary strings unless you specify the
        ' data type.
        Registry.SetValue(keyName, "TestExpand", "My path: %path%")
        Registry.SetValue(keyName, "TestExpand2", "My path: %path%", _
            RegistryValueKind.ExpandString)

        ' Arrays of strings are stored automatically as 
        ' MultiString. Similarly, arrays of Byte are stored
        ' automatically as Binary.
        Dim strings() As String = {"One", "Two", "Three"}
        Registry.SetValue(keyName, "TestArray", strings)

        ' Your default value is returned if the name/value pair
        ' does not exist.
        Dim noSuch As String = _
            Registry.GetValue(keyName, "NoSuchName", _
            "Return this default if NoSuchName does not exist.")
        Console.WriteLine(vbCrLf & "NoSuchName: {0}", noSuch)

        ' Retrieve the Integer and Long values, specifying 
        ' numeric default values in case the name/value pairs
        ' do not exist. The Integer value is retrieved from the
        ' default (nameless) name/value pair for the key.
        Dim tInteger As Integer = _
            Registry.GetValue(keyName, "", -1)
        Console.WriteLine("(Default): {0}", tInteger)
        Dim tLong As Long = Registry.GetValue(keyName, _
             "TestLong", Long.MinValue)
        Console.WriteLine("TestLong: {0}", tLong)

        ' When retrieving a MultiString value, you can specify
        ' an array for the default return value. The value is
        ' declared inline, but could also be declared as:
        ' Dim default() As String = {"Default value."}
        '
        Dim tArray() As String = _
            Registry.GetValue(keyName, "TestArray", _
            New String() {"Default if TestArray does not exist."})
        For i As Integer = 0 To tArray.Length - 1
            Console.WriteLine("TestArray({0}): {1}", i, tArray(i))
        Next

        ' A string with embedded environment variables is not
        ' expanded if it was stored as an ordinary string.
        Dim tExpand As String = Registry.GetValue(keyName, _
             "TestExpand", "Default if TestExpand does not exist.")
        Console.WriteLine("TestExpand: {0}", tExpand)

        ' A string stored as ExpandString is expanded.
        Dim tExpand2 As String = Registry.GetValue(keyName, _
             "TestExpand2", "Default if TestExpand2 does not exist.")
        Console.WriteLine("TestExpand2: {0}...", _
            tExpand2.Substring(0, 40))

        Console.WriteLine(vbCrLf & _
            "Use the registry editor to examine the key.")
        Console.WriteLine("Press the Enter key to delete the key.")
        Console.ReadLine()
        Registry.CurrentUser.DeleteSubKey(subkey)
    End Sub
End Class
'
' This code example produces output similar to the following:
'
'NoSuchName: Return this default if NoSuchName does not exist.
'(Default): 5280
'TestLong: 12345678901234
'TestArray(0): One
'TestArray(1): Two
'TestArray(2): Three
'TestExpand: My path: %path%
'TestExpand2: My path: D:\Program Files\Microsoft.NET\...
'
'Use the registry editor to examine the key.
'Press the Enter key to delete the key.


.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

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.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.