This documentation is archived and is not being maintained.

RegistryKey.OpenSubKey Method (String, RegistryKeyPermissionCheck)

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

Namespace: Microsoft.Win32
Assembly: mscorlib (in mscorlib.dll)

[ComVisibleAttribute(false)] 
public RegistryKey OpenSubKey (
	string name,
	RegistryKeyPermissionCheck permissionCheck
)
/** @attribute ComVisibleAttribute(false) */ 
public RegistryKey OpenSubKey (
	String name, 
	RegistryKeyPermissionCheck permissionCheck
)
ComVisibleAttribute(false) 
public function OpenSubKey (
	name : String, 
	permissionCheck : RegistryKeyPermissionCheck
) : RegistryKey
Not applicable.

Parameters

name

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

permissionCheck

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

Return Value

A RegistryKey object representing the subkey requested, or a null reference (Nothing in Visual Basic) if the operation failed.

Exception typeCondition

ArgumentNullException

name is a null reference (Nothing in Visual Basic)

ArgumentException

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

-or-

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.

Rather than throwing an exception, this method returns a null reference (Nothing in Visual Basic) 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.

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.

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.
 */

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0
Show: