RegistryKey.CreateSubKey Method (String, RegistryKeyPermissionCheck, RegistrySecurity) (Microsoft.Win32)

.NET Framework Class Library

RegistryKey..::.CreateSubKey Method (String, RegistryKeyPermissionCheck, RegistrySecurity)

Creates a new subkey or opens an existing subkey for write access, using the specified permission check option and registry security. The string subkey is not case-sensitive.

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

Syntax

Visual Basic (Declaration)

<ComVisibleAttribute(False)> _
Public Function CreateSubKey ( _
    subkey As String, _
    permissionCheck As RegistryKeyPermissionCheck, _
    registrySecurity As RegistrySecurity _
) As RegistryKey

Visual Basic (Usage)

Dim instance As RegistryKey
Dim subkey As String
Dim permissionCheck As RegistryKeyPermissionCheck
Dim registrySecurity As RegistrySecurity
Dim returnValue As RegistryKey

returnValue = instance.CreateSubKey(subkey, _
    permissionCheck, registrySecurity)

[ComVisibleAttribute(false)]
public RegistryKey CreateSubKey(
    string subkey,
    RegistryKeyPermissionCheck permissionCheck,
    RegistrySecurity registrySecurity
)

Visual C++

[ComVisibleAttribute(false)]
public:
RegistryKey^ CreateSubKey(
    String^ subkey, 
    RegistryKeyPermissionCheck permissionCheck, 
    RegistrySecurity^ registrySecurity
)

JScript

public function CreateSubKey(
    subkey : String, 
    permissionCheck : RegistryKeyPermissionCheck, 
    registrySecurity : RegistrySecurity
) : RegistryKey

Parameters

subkey: Type: System..::.String
The name or path of the subkey to create or open.

permissionCheck: Type: Microsoft.Win32..::.RegistryKeyPermissionCheck
One of the RegistryKeyPermissionCheck values that specifies whether the key is opened for read or read/write access.

registrySecurity: Type: System.Security.AccessControl..::.RegistrySecurity
A RegistrySecurity object that specifies the access control security for the new key.

Return Value

Type: Microsoft.Win32..::.RegistryKey
A RegistryKey object that represents the newly created subkey, or nullNothingnullptra null reference (Nothing in Visual Basic) if the operation failed. If a zero-length string is specified for subkey, the current RegistryKey object is returned.

Exceptions

Exception	Condition
ArgumentNullException	subkey is nullNothingnullptra null reference (Nothing in Visual Basic).
SecurityException	The user does not have the permissions required to create or open the registry key.
ArgumentException	subkey is longer than the maximum length allowed (255 characters). -or- permissionCheck contains an invalid value.
ObjectDisposedException	The RegistryKey on which this method is being invoked is closed (closed keys cannot be accessed).
UnauthorizedAccessException	The current RegistryKey cannot be written to; for example, it was not opened as a writable key, or the user does not have the necessary access rights.
IOException	The nesting level exceeds 510. -or- A system error occurred, such as deletion of the key, or an attempt to create a key in the LocalMachine root.

Remarks

The CreateSubKey method creates a registry key that has the access control specified by the registrySecurity parameter. The RegistryKey object that is returned represents the registry key, but that object is not restricted by the access control specified in the registrySecurity parameter.

If permissionCheck is RegistryKeyPermissionCheck..::.ReadWriteSubTree, the key is opened for read/write access. If permissionCheck is RegistryKeyPermissionCheck..::.ReadSubTree, the key is opened for read access.

For backward compatibility, the key is opened for reading and writing if permissionCheck is RegistryKeyPermissionCheck..::.Default and the parent key also has RegistryKeyPermissionCheck..::.Default. If the parent key has any other setting, read/write status is controlled by the parent key's setting.

In order to perform this action, the user must have permissions at this level and below in the registry hierarchy.

Caution:
Do not expose RegistryKey objects in such a way that a malicious program could create thousands of meaningless subkeys or key/value pairs. For example, do not allow callers to enter arbitrary keys or values.

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.

.NET Framework Security

RegistryPermission
for the ability to modify the specified registry key if it exists, or for the ability to create the registry key if it does not already exist. Associated enumerations: RegistryPermissionAccess..::.Write, RegistryPermissionAccess..::.Create
SecurityPermission
for the ability to access the specified registry key if it is a remote key. Associated enumeration: SecurityPermissionFlag..::.UnmanagedCode

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0

Reference

RegistryKey Class

RegistryKey Members

CreateSubKey Overload

Microsoft.Win32 Namespace

DeleteSubKey

OpenSubKey