RegistryKey::CreateSubKey Method (String^)
Creates a new subkey or opens an existing subkey for write access.
Assembly: mscorlib (in mscorlib.dll)
Parameters
- subkey
-
Type:
System::String^
The name or path of the subkey to create or open. This string is not case-sensitive.
Return Value
Type: Microsoft.Win32::RegistryKey^The newly created subkey, or null if the operation failed. If a zero-length string is specified for subkey, the current RegistryKey object is returned.
| Exception | Condition |
|---|---|
| ArgumentNullException | subkey is null. |
| SecurityException | The user does not have the permissions required to create or open the registry key. |
| ObjectDisposedException | The RegistryKey on which this method is being invoked is closed (closed keys cannot be accessed). |
| UnauthorizedAccessException | The 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. |
In order to perform this action, the user must have permission 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. |
The following code example shows how to create a subkey under HKEY_CURRENT_USER, manipulate its contents, and then delete the subkey.
using namespace System; using namespace System::Security::Permissions; using namespace Microsoft::Win32; int main() { // Create a subkey named Test9999 under HKEY_CURRENT_USER. RegistryKey ^ test9999 = Registry::CurrentUser->CreateSubKey( "Test9999" ); // Create two subkeys under HKEY_CURRENT_USER\Test9999. test9999->CreateSubKey( "TestName" )->Close(); RegistryKey ^ testSettings = test9999->CreateSubKey( "TestSettings" ); // Create data for the TestSettings subkey. testSettings->SetValue( "Language", "French" ); testSettings->SetValue( "Level", "Intermediate" ); testSettings->SetValue( "ID", 123 ); testSettings->Close(); // Print the information from the Test9999 subkey. Console::WriteLine( "There are {0} subkeys under Test9999.", test9999->SubKeyCount.ToString() ); array<String^>^subKeyNames = test9999->GetSubKeyNames(); for ( int i = 0; i < subKeyNames->Length; i++ ) { RegistryKey ^ tempKey = test9999->OpenSubKey( subKeyNames[ i ] ); Console::WriteLine( "\nThere are {0} values for {1}.", tempKey->ValueCount.ToString(), tempKey->Name ); array<String^>^valueNames = tempKey->GetValueNames(); for ( int j = 0; j < valueNames->Length; j++ ) { Console::WriteLine( "{0,-8}: {1}", valueNames[ j ], tempKey->GetValue( valueNames[ j ] )->ToString() ); } } // Delete the ID value. testSettings = test9999->OpenSubKey( "TestSettings", true ); testSettings->DeleteValue( "id" ); // Verify the deletion. Console::WriteLine( dynamic_cast<String^>(testSettings->GetValue( "id", "ID not found." )) ); testSettings->Close(); // Delete or close the new subkey. Console::Write( "\nDelete newly created registry key? (Y/N) " ); if ( Char::ToUpper( Convert::ToChar( Console::Read() ) ) == 'Y' ) { Registry::CurrentUser->DeleteSubKeyTree( "Test9999" ); Console::WriteLine( "\nRegistry key {0} deleted.", test9999->Name ); } else { Console::WriteLine( "\nRegistry key {0} closed.", test9999->ToString() ); test9999->Close(); } }
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
for the ability to access the specified registry key if it is a remote key. Associated enumeration: SecurityPermissionFlag::UnmanagedCode
Available since 1.1
