RegistryKey.OpenSubKey Method

Definition

Namespace:

Microsoft.Win32

Assembly:

Microsoft.Win32.Registry.dll

Retrieves the specified subkey.

Overloads

OpenSubKey(String, Boolean)	Retrieves a specified subkey, and specifies whether write access is to be applied to the key.
OpenSubKey(String, RegistryKeyPermissionCheck, RegistryRights)	Retrieves the specified subkey for read or read/write access, requesting the specified access rights.
OpenSubKey(String, RegistryRights)	Retrieves a subkey with the specified name and access rights. Available starting with .NET Framework 4.6.
OpenSubKey(String)	Retrieves a subkey as read-only.
OpenSubKey(String, RegistryKeyPermissionCheck)	Retrieves the specified subkey for read or read/write access.

OpenSubKey(String, Boolean)

Retrieves a specified subkey, and specifies whether write access is to be applied to the key.

C#

public Microsoft.Win32.RegistryKey? OpenSubKey(string name, bool writable);

Parameters

name

String

Name or path of the subkey to open.

writable

Boolean

Set to true if you need write access to the key.

Returns

RegistryKey

The subkey requested, or null if the operation failed.

Exceptions

ArgumentNullException

name is null.

ObjectDisposedException

The RegistryKey is closed (closed keys cannot be accessed).

SecurityException

The user does not have the permissions required to access the registry key in the specified mode.

Examples

The following code example creates a test key and uses the OpenSubKey method to open it, demonstrating both overloads of the method.

C#

using System;
using Microsoft.Win32;
using Microsoft.VisualBasic;

public class Example
{
    public static void Main()
    {
        // Delete and recreate the test key.
        Registry.CurrentUser.DeleteSubKey("RegistryOpenSubKeyExample", false);
        RegistryKey rk = Registry.CurrentUser.CreateSubKey("RegistryOpenSubKeyExample");
        rk.Close();

        // Obtain an instance of RegistryKey for the CurrentUser registry
        // root.
        RegistryKey rkCurrentUser = Registry.CurrentUser;

        // Obtain the test key (read-only) and display it.
        RegistryKey rkTest = rkCurrentUser.OpenSubKey("RegistryOpenSubKeyExample");
        Console.WriteLine("Test key: {0}", rkTest);
        rkTest.Close();
        rkCurrentUser.Close();

        // Obtain the test key in one step, using the CurrentUser registry
        // root.
        rkTest = Registry.CurrentUser.OpenSubKey("RegistryOpenSubKeyExample");
        Console.WriteLine("Test key: {0}", rkTest);
        rkTest.Close();

        // Open the test key in read/write mode.
        rkTest = Registry.CurrentUser.OpenSubKey("RegistryOpenSubKeyExample", true);
        rkTest.SetValue("TestName", "TestValue");
        Console.WriteLine("Test value for TestName: {0}", rkTest.GetValue("TestName"));
        rkTest.Close();
    } //Main
} //Example

Remarks

If the requested key does not exist, this method returns null instead of throwing an exception.

If writable is true, the key will be opened for reading and writing, otherwise, the key will be opened as read-only.

In order to use the OpenSubKey method, you must have an instance of the RegistryKey method. To get an instance of RegistryKey, use one of the static members of the Registry class.

See also

• CreateSubKey(String)
• DeleteSubKey(String)
• DeleteSubKeyTree(String)
• GetSubKeyNames()
• OpenRemoteBaseKey(RegistryHive, String)
• SubKeyCount
• Registry

OpenSubKey(String, RegistryKeyPermissionCheck, RegistryRights)

Retrieves the specified subkey for read or read/write access, requesting the specified access rights.

C#

public Microsoft.Win32.RegistryKey? OpenSubKey(string name, Microsoft.Win32.RegistryKeyPermissionCheck permissionCheck, System.Security.AccessControl.RegistryRights rights);

Parameters

name

String

The name or path of the subkey to create or open.

permissionCheck

RegistryKeyPermissionCheck

One of the enumeration values that specifies whether the key is opened for read or read/write access.

rights

RegistryRights

A bitwise combination of enumeration values that specifies the desired security access.

Returns

RegistryKey

The subkey requested, or null if the operation failed.

Exceptions

ArgumentNullException

name is null

ArgumentException

permissionCheck contains an invalid value.

ObjectDisposedException

The RegistryKey is closed (closed keys cannot be accessed).

SecurityException

rights includes invalid registry rights values.

-or-

The user does not have the requested permissions.

Remarks

Rather than throwing an exception, this method returns null if the requested key does not exist.

If permissionCheck is RegistryKeyPermissionCheck.ReadWriteSubTree, the key is opened for reading and writing; if permissionCheck is RegistryKeyPermissionCheck.ReadSubTree or RegistryKeyPermissionCheck.Default, the key is opened for reading unless the parent key was opened with RegistryKeyPermissionCheck.ReadWriteSubTree.

The access specified for permissionCheck takes precedence over the access specified for rights. For example, if you specify RegistryKeyPermissionCheck.ReadSubTree for permissionCheck and RegistryRights.WriteKey for rights, an attempt to write to the subkey throws an exception.

In order to use the OpenSubKey method, you must have an instance of the RegistryKey class. To get an instance of RegistryKey, use one of the static members of the Registry class.

See also

• CreateSubKey(String)
• DeleteSubKey(String)
• DeleteSubKeyTree(String)
• GetSubKeyNames()
• OpenRemoteBaseKey(RegistryHive, String)
• SubKeyCount
• Registry

OpenSubKey(String, RegistryRights)

Retrieves a subkey with the specified name and access rights. Available starting with .NET Framework 4.6.

C#

public Microsoft.Win32.RegistryKey? OpenSubKey(string name, System.Security.AccessControl.RegistryRights rights);

Parameters

name

String

The name or path of the subkey to create or open.

rights

RegistryRights

The rights for the registry key.

Returns

RegistryKey

The subkey requested, or null if the operation failed.

Exceptions

ArgumentNullException

name is null.

ObjectDisposedException

The RegistryKey is closed (closed keys cannot be accessed).

SecurityException

The user does not have the permissions required to access the registry key in the specified mode.

Remarks

You must open a key before it can be manipulated with other methods and properties. To modify a key, you must open it with an overload of the OpenSubKey method that allows you to specify write access.

OpenSubKey(String)

Retrieves a subkey as read-only.

C#

public Microsoft.Win32.RegistryKey? OpenSubKey(string name);

Parameters

name

String

The name or path of the subkey to open as read-only.

Returns

RegistryKey

The subkey requested, or null if the operation failed.

Exceptions

ArgumentNullException

name is null

ObjectDisposedException

The RegistryKey is closed (closed keys cannot be accessed).

SecurityException

The user does not have the permissions required to read the registry key.

Examples

The following code example creates a test key and uses the OpenSubKey method to open it, demonstrating both overloads of the method.

C#

using System;
using Microsoft.Win32;
using Microsoft.VisualBasic;

public class Example
{
    public static void Main()
    {
        // Delete and recreate the test key.
        Registry.CurrentUser.DeleteSubKey("RegistryOpenSubKeyExample", false);
        RegistryKey rk = Registry.CurrentUser.CreateSubKey("RegistryOpenSubKeyExample");
        rk.Close();

        // Obtain an instance of RegistryKey for the CurrentUser registry
        // root.
        RegistryKey rkCurrentUser = Registry.CurrentUser;

        // Obtain the test key (read-only) and display it.
        RegistryKey rkTest = rkCurrentUser.OpenSubKey("RegistryOpenSubKeyExample");
        Console.WriteLine("Test key: {0}", rkTest);
        rkTest.Close();
        rkCurrentUser.Close();

        // Obtain the test key in one step, using the CurrentUser registry
        // root.
        rkTest = Registry.CurrentUser.OpenSubKey("RegistryOpenSubKeyExample");
        Console.WriteLine("Test key: {0}", rkTest);
        rkTest.Close();

        // Open the test key in read/write mode.
        rkTest = Registry.CurrentUser.OpenSubKey("RegistryOpenSubKeyExample", true);
        rkTest.SetValue("TestName", "TestValue");
        Console.WriteLine("Test value for TestName: {0}", rkTest.GetValue("TestName"));
        rkTest.Close();
    } //Main
} //Example

Remarks

You must open a key before it can be manipulated with other methods and properties. To modify a key, you must open it with an overload of the OpenSubKey method that allows you to specify write access, such as the OpenSubKey(String, RegistryKeyPermissionCheck) overload or the OpenSubKey(String, Boolean) overload.

If the specified subkey cannot be found, then null is returned.

In order to use the OpenSubKey method, you must have an instance of RegistryKey. To get an instance of RegistryKey, use the one of the static members of the Registry class.

See also

• CreateSubKey(String)
• DeleteSubKey(String)
• DeleteSubKeyTree(String)
• GetSubKeyNames()
• OpenRemoteBaseKey(RegistryHive, String)
• SubKeyCount
• Registry

OpenSubKey(String, RegistryKeyPermissionCheck)

Retrieves the specified subkey for read or read/write access.

C#

public Microsoft.Win32.RegistryKey? OpenSubKey(string name, Microsoft.Win32.RegistryKeyPermissionCheck permissionCheck);

Parameters

name

String

The name or path of the subkey to create or open.

permissionCheck

RegistryKeyPermissionCheck

One of the enumeration values that specifies whether the key is opened for read or read/write access.

Returns

RegistryKey

The subkey requested, or null if the operation failed.

Exceptions

ArgumentNullException

name is null

ArgumentException

permissionCheck contains an invalid value.

ObjectDisposedException

The RegistryKey is closed (closed keys cannot be accessed).

SecurityException

The user does not have the permissions required to read the registry key.

Examples

The following code example creates a subkey containing 100 key/value pairs and closes it. The example opens the subkey with Default, records the time it takes to read all the values, and closes the subkey. The example opens the subkey with ReadSubTree and records the time it takes to read all the values. Finally, the example computes and displays the percentage improvement.

C#

using System;
using Microsoft.Win32;
using System.Diagnostics;

public class Example
{
    public static void Main()
    {
        const int LIMIT = 100;
        RegistryKey cu = Registry.CurrentUser;
        const string testKey = "RegistryKeyPermissionCheckExample";

        Console.WriteLine("Generating {0} key/value pairs.", LIMIT);
        RegistryKey rk = cu.CreateSubKey(testKey);
        for (int i = 0; i < LIMIT; i++)
        {
            rk.SetValue("Key" + i, i);
        }

        rk.Close();

        Stopwatch s = new Stopwatch();

        // On the default setting, security is checked every time
        // a key/value pair is read.
        rk = cu.OpenSubKey(testKey, RegistryKeyPermissionCheck.Default);

        s.Start();
        for (int i = 0; i < LIMIT; i++)
        {
            rk.GetValue("Key" + i, i);
        }
        s.Stop();
        rk.Close();
        long delta1 = s.ElapsedTicks;

        s.Reset();

        // When the key is opened with ReadSubTree, security is
        // not checked when the values are read.
        rk = cu.OpenSubKey(testKey, RegistryKeyPermissionCheck.ReadSubTree);

        s.Start();
        for (int i = 0; i < LIMIT; i++)
        {
            rk.GetValue("Key" + i, i);
        }
        s.Stop();
        rk.Close();
        long delta2 = s.ElapsedTicks;

        double faster = (double) (delta1 - delta2) / (double) delta1;
        Console.WriteLine("ReadSubTree is {0}% faster for {1} values.",
            (faster * 100).ToString("0.0"), LIMIT);

        cu.DeleteSubKey(testKey);
    }
}

/* This code example produces output similar to the following:

Generating 100 key/value pairs.
ReadSubTree is 23.4% faster for 100 values.
 */

Remarks

Rather than throwing an exception, this method returns null if the requested key does not exist.

If permissionCheck is RegistryKeyPermissionCheck.ReadWriteSubTree, the key is opened for reading and writing; if permissionCheck is RegistryKeyPermissionCheck.ReadSubTree or RegistryKeyPermissionCheck.Default, the key is opened for reading unless the parent key was opened with RegistryKeyPermissionCheck.ReadWriteSubTree.

In order to use the OpenSubKey method, you must have an instance of the RegistryKey class. To get an instance of RegistryKey, use one of the static members of the Registry class.

See also

• CreateSubKey(String)
• DeleteSubKey(String)
• DeleteSubKeyTree(String)
• GetSubKeyNames()
• OpenRemoteBaseKey(RegistryHive, String)
• SubKeyCount
• Registry