SecureString::AppendChar Method (Char)

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Appends a character to the end of the current secure string.

Namespace:   System.Security
Assembly:  mscorlib (in mscorlib.dll)

public:
[HandleProcessCorruptedStateExceptionsAttribute]
void AppendChar(
	wchar_t c
)

Parameters

c
Type: System::Char

A character to append to this secure string.

Exception Condition
ObjectDisposedException

This secure string has already been disposed.

InvalidOperationException

This secure string is read-only.

ArgumentOutOfRangeException

Performing this operation would make the length of this secure string greater than 65,536 characters.

CryptographicException

An error occurred while protecting or unprotecting the value of this secure string.

If the implementation uses a protection mechanism, such as encryption, the value of this secure string, if any, is unprotected; c is appended; then the new value of the secure string is re-protected.

The following example demonstrates how the AppendChar, InsertAt, RemoveAt, SetAt, and Clear methods affect the value of a SecureString object.

using namespace System;
using namespace System::Security;

void main()
{
    String^ msg = L"   The current length of the SecureString object: {0}\n";
    SecureString ^ ss = gcnew SecureString;

    Console::WriteLine(L"1) Instantiate the SecureString object:");
    Console::WriteLine(msg, ss->Length );

    Console::WriteLine(L"2) Append 'a' to the value:");
    ss->AppendChar('a');
    Console::WriteLine(msg, ss->Length );

    Console::WriteLine(L"3) Append 'X' to the value:");
    ss->AppendChar('X');
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"4) Append 'c' to the value:");
    ss->AppendChar('c');
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"5) Insert 'd' at the end of the value:");
    ss->InsertAt(ss->Length, 'd');
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"6) Remove the last character ('d') from the value:");
    ss->RemoveAt(3);
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"7) Set the second character ('X') of the value to 'b':" );
    ss->SetAt(1, 'b');
    Console::WriteLine(msg, ss->Length );

    Console::WriteLine(L"8) Delete the value of the SecureString object:");
    ss->Clear();
    Console::WriteLine(msg, ss->Length);

    delete ss;
}

/*
This code example produces the following results:

This example demonstrates the effect of the AppendChar, InsertAt,
RemoveAt, SetAt, and Clear methods on the value of a SecureString
object. This example simulates the value of the object because the
actual value is encrypted.

1) The initial value of the SecureString object:
   SecureString = ""
   Length = 0

2) AppendChar: Append 'a' to the value:
   SecureString = "a"
   Length = 1

3) AppendChar: Append 'X' to the value:
   SecureString = "aX"
   Length = 2

4) AppendChar: Append 'c' to the value:
   SecureString = "aXc"
   Length = 3

5) InsertAt: Insert 'd' at the end of the value (equivalent
     to AppendChar):
   SecureString = "aXcd"
   Length = 4

6) RemoveAt: Remove the last character ('d') from the value:
   SecureString = "aXc"
   Length = 3

7) SetAt: Set the second character ('X') of the value to 'b':
   SecureString = "abc"
   Length = 3

8) Clear: Delete the value of the SecureString object:
   SecureString = ""
   Length = 0
*/

The following example demonstrates how the AppendChar and RemoveAt methods can be used to collect the characters in a password.

using namespace System;
using namespace System::Security;

void main()
{
   bool go = true;
   ConsoleKeyInfo cki;
   String^ m = L"\nEnter your password (up to 15 letters, numbers, and underscores)\n"
               L"Press BACKSPACE to delete the last character entered. " +
               L"\nPress Enter when done, or ESCAPE to quit:";
   SecureString ^ password = gcnew SecureString;
   int top;
   int left;

   // The Console.TreatControlCAsInput property prevents CTRL+C from
   // ending this example.
   Console::TreatControlCAsInput = true;

   Console::Clear();
   Console::WriteLine(m);

   top = Console::CursorTop;
   left = Console::CursorLeft;

   do {
      cki = Console::ReadKey(true);
      if (cki.Key == ConsoleKey::Escape)
         break;

      if (cki.Key == ConsoleKey::Backspace){
         if (password->Length > 0) {
            Console::SetCursorPosition(left + password->Length - 1, top);
            Console::Write(' ');
            Console::SetCursorPosition(left + password->Length - 1, top);
            password->RemoveAt(password->Length - 1);
         }
      }
      else {
         if ((password->Length < 15) &&
             (Char::IsLetterOrDigit( cki.KeyChar ) ||
              cki.KeyChar == '_') ) {
            password->AppendChar( cki.KeyChar );
            Console::SetCursorPosition( left + password->Length - 1, top );
            Console::Write("*");
         }
      }
   } while (cki.Key != ConsoleKey::Enter & password->Length < 15);

   // Make the password read-only to prevent modification.
   password->MakeReadOnly();
   // Dispose of the SecureString instance.
   delete password;

}
// The example displays output like the following:
//    Enter your password (up to 15 letters, numbers, and underscores)
//    Press BACKSPACE to delete the last character entered.
//    Press Enter when done, or ESCAPE to quit:
//    ************

.NET Framework
Available since 2.0
Return to top
Show: