.NET Framework Class Library
SecureString..::.AppendChar Method

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

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

Visual Basic (Declaration)
Public Sub AppendChar ( _
    c As Char _
)
Visual Basic (Usage)
Dim instance As SecureString
Dim c As Char

instance.AppendChar(c)
C#
public void AppendChar(
    char c
)
Visual C++
public:
void AppendChar(
    wchar_t c
)
JScript
public function AppendChar(
    c : char
)

Parameters

c
Type: System..::.Char
A character to append to this secure string.
Exceptions

ExceptionCondition
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 65536 characters.

CryptographicException

An error occurred while encrypting or decrypting the value of this secure string.

Remarks

The value of this secure string, if any, is decrypted; c is appended; then the new value of the secure string is encrypted.

Examples

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

Visual Basic
' This example demonstrates the AppendChar, 
' InsertAt, RemoveAt, SetAt, and Clear methods.
Imports System
Imports System.Security

Class Sample
   Public Shared Sub Main()
      Dim msg1 As String = "   SecureString = {0}" & vbCrLf & "   Length = {1}" & vbCrLf
      Dim msg2 As String = "This example demonstrates the effect of the AppendChar, InsertAt," & vbCrLf & _
                           "RemoveAt, SetAt, and Clear methods on the value of a SecureString" & vbCrLf & _
                           "object. This example simulates the value of the object because the" & vbCrLf & _
                           "actual value is encrypted." & vbCrLf
      Dim ss As New SecureString()
' 
'  This sample modifies the contents of a SecureString, ss, in
'  several steps. After each step, the length and simulated value of ss 
'  are displayed. The actual value of ss is encrypted.
'
      Console.WriteLine(msg2)

      Console.WriteLine("1) The initial value of the SecureString object:")
      Console.WriteLine(msg1, """""", ss.Length)

      Console.WriteLine("2) AppendChar: Append 'a' to the value:")
      ss.AppendChar("a"c)
      Console.WriteLine(msg1, """a""", ss.Length)

      Console.WriteLine("3) AppendChar: Append 'X' to the value:")
      ss.AppendChar("X"c)
      Console.WriteLine(msg1, """aX""", ss.Length)

      Console.WriteLine("4) AppendChar: Append 'c' to the value:")
      ss.AppendChar("c"c)
      Console.WriteLine(msg1, """aXc""", ss.Length)

      Console.WriteLine(("5) InsertAt: Insert 'd' at the end of the value (equivalent" & vbCrLf & "     to AppendChar):"))
      ss.InsertAt(ss.Length, "d"c)
      Console.WriteLine(msg1, """aXcd""", ss.Length)

      Console.WriteLine("6) RemoveAt: Remove the last character ('d') from the value:")
      ss.RemoveAt(3)
      Console.WriteLine(msg1, """aXc""", ss.Length)

      Console.WriteLine("7) SetAt: Set the second character ('X') of the value to 'b':")
      ss.SetAt(1, "b"c)
      Console.WriteLine(msg1, """abc""", ss.Length)

      Console.WriteLine("8) Clear: Delete the value of the SecureString object:")
      ss.Clear()
      Console.WriteLine(msg1, """""", ss.Length)
   End Sub 'Main
End Class 'Sample
'
'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
'
C#
// This example demonstrates the AppendChar, 
// InsertAt, RemoveAt, SetAt, and Clear methods.

using System;
using System.Security;

class Sample 
{
    public static void Main() 
    {
    string msg1 = "   SecureString = {0}\n   Length = {1}\n";
    string msg2 = "This example demonstrates the effect of the AppendChar, InsertAt,\n" +
                  "RemoveAt, SetAt, and Clear methods on the value of a SecureString\n" +
                  "object. This example simulates the value of the object because the\n" +
                  "actual value is encrypted.\n";
    SecureString ss = new SecureString();
/* 
  This sample modifies the contents of a SecureString, ss, in
  several steps. After each step, the length and simulated value of ss 
  are displayed. The actual value of ss is encrypted.
*/
    Console.WriteLine(msg2);

    Console.WriteLine("1) The initial value of the SecureString object:");
    Console.WriteLine(msg1, "\"\"", ss.Length);

    Console.WriteLine("2) AppendChar: Append 'a' to the value:");
    ss.AppendChar('a');
    Console.WriteLine(msg1, "\"a\"", ss.Length);

    Console.WriteLine("3) AppendChar: Append 'X' to the value:");
    ss.AppendChar('X');
    Console.WriteLine(msg1, "\"aX\"", ss.Length);

    Console.WriteLine("4) AppendChar: Append 'c' to the value:");
    ss.AppendChar('c');
    Console.WriteLine(msg1, "\"aXc\"", ss.Length);

    Console.WriteLine("5) InsertAt: Insert 'd' at the end of the value (equivalent\n" +
                      "     to AppendChar):");
    ss.InsertAt(ss.Length, 'd');
    Console.WriteLine(msg1, "\"aXcd\"", ss.Length);

    Console.WriteLine("6) RemoveAt: Remove the last character ('d') from the value:");
    ss.RemoveAt(3);
    Console.WriteLine(msg1, "\"aXc\"", ss.Length);

    Console.WriteLine("7) SetAt: Set the second character ('X') of the value to 'b':");
    ss.SetAt(1, 'b');
    Console.WriteLine(msg1, "\"abc\"", ss.Length);

    Console.WriteLine("8) Clear: Delete the value of the SecureString object:");
    ss.Clear();
    Console.WriteLine(msg1, "\"\"", ss.Length);
    }
}
/*
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
*/
Visual C++
// This example demonstrates the AppendChar,
// InsertAt, RemoveAt, SetAt, and Clear methods.

using namespace System;
using namespace System::Security;

int main()
{
    String^ msg1 = L"   SecureString = {0}\n   Length = {1}\n";
    String^ msg2 = L"This example demonstrates the effect of the AppendChar, InsertAt,\n"
    L"RemoveAt, SetAt, and Clear methods on the value of a SecureString\n"
    L"object. This example simulates the value of the object because the\n"
    L"actual value is encrypted.\n";
    SecureString ^ ss = gcnew SecureString;

    // This sample modifies the contents of a SecureString, ss, in
    // several steps. After each step, the length and simulated value of ss
    // are displayed. The actual value of ss is encrypted.
    Console::WriteLine( msg2 );
    Console::WriteLine( L"1) The initial value of the SecureString object:" );
    Console::WriteLine( msg1, L"\"\"", ss->Length );
    Console::WriteLine( L"2) AppendChar: Append 'a' to the value:" );

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

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

    ss->AppendChar( 'c' );
    Console::WriteLine( msg1, L"\"aXc\"", ss->Length );
    Console::WriteLine( L"5) InsertAt: Insert 'd' at the end of the value (equivalent\n"
                        L"     to AppendChar):" );

    ss->InsertAt( ss->Length, 'd' );
    Console::WriteLine( msg1, L"\"aXcd\"", ss->Length );
    Console::WriteLine( L"6) RemoveAt: Remove the last character ('d') from the value:" );

    ss->RemoveAt( 3 );
    Console::WriteLine( msg1, L"\"aXc\"", ss->Length );
    Console::WriteLine( L"7) SetAt: Set the second character ('X') of the value to 'b':" );

    ss->SetAt( 1, 'b' );
    Console::WriteLine( msg1, L"\"abc\"", ss->Length );
    Console::WriteLine( L"8) Clear: Delete the value of the SecureString object:" );

    ss->Clear();
    Console::WriteLine( msg1, L"\"\"", ss->Length );

    return 0;
}

/*
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 code example demonstrates how the AppendChar and RemoveAt methods can be used to collect the characters in a password.

Visual Basic
' This example demonstrates using the AppendChar and RemoveAt 
' methods to collect a password.

Imports System
Imports System.Security

Class Sample
   Public Shared Sub Main()
      Dim cki As ConsoleKeyInfo
      Dim m1 As String = "(This example simulates entering a password. " & _
                         "Do not enter an actual password.)" & vbCrLf
      Dim m2 As String = "Enter your password (up to 15 letters, numbers, and underscores)" & vbCrLf & "Press BACKSPACE to delete the last character entered. " & vbCrLf & _
                         "Press ESCAPE to quit:"
      Dim password As New SecureString()
      Dim top, left As Integer
      '
      ' The Console.TreatControlCAsInput property prevents this example from
      ' ending if you press CTL+C, however all other operating system keys and 
      ' shortcuts, such as ALT+TAB or the Windows Logo key, are still in effect. 
      ' Each input character is assumed to occupy one screen column.
      '
      Console.TreatControlCAsInput = True

      Console.Clear()
      Console.WriteLine(m1)
      Console.WriteLine(m2)

      top = Console.CursorTop
      left = Console.CursorLeft

      ' Read user input from the console. Store up to 15 letter, digit, or underscore
      ' characters in a SecureString object, or delete a character if the user enters 
      ' a backspace. Display an asterisk (*) on the console to represent each character 
      ' that is stored.

      While True
         cki = Console.ReadKey(True)
         If cki.Key = ConsoleKey.Escape Then
            Exit While
         End If
         If cki.Key = ConsoleKey.Backspace Then
            If password.Length > 0 Then
               Console.SetCursorPosition(left + password.Length - 1, top)
               Console.Write(" "c)
               Console.SetCursorPosition(left + password.Length - 1, top)
               password.RemoveAt(password.Length - 1)
            End If
         Else
            If password.Length < 15 AndAlso([Char].IsLetterOrDigit(cki.KeyChar) _
            OrElse cki.KeyChar = "_"c) Then
               password.AppendChar(cki.KeyChar)
               Console.SetCursorPosition(left + password.Length - 1, top)
               Console.Write("*"c)
            End If
         End If
      End While

      ' Make the password read-only to prevent it from being modified after it has 
      ' been collected. 

      password.MakeReadOnly()
   End Sub 'Main
End Class 'Sample
'
'This example produces results similar to the following text:
'
'(This example simulates entering a password. Do not enter an actual password.)
'
'Enter your password (up to 15 letters, numbers, and underscores)
'Press BACKSPACE to delete the last character entered.
'Press ESCAPE to quit:
'***************
'
C#
// This example demonstrates using the AppendChar and RemoveAt 
// methods to collect a password.

using System;
using System.Security;

class Sample 
{
    public static void Main() 
    {
    ConsoleKeyInfo cki;
    String m1 = "(This example simulates entering a password. " +
                "Do not enter an actual password.)\n";
    String m2 = "Enter your password (up to 15 letters, numbers, and underscores)\n" +
                "Press BACKSPACE to delete the last character entered. \nPress ESCAPE to quit:";
    SecureString password = new SecureString();
    int top, left;

// The Console.TreatControlCAsInput property prevents this example from
// ending if you press CTL+C, however all other operating system keys and 
// shortcuts, such as ALT+TAB or the Windows Logo key, are still in effect. 
// Each input character is assumed to occupy one screen column.

    Console.TreatControlCAsInput = true;

    Console.Clear();
    Console.WriteLine(m1);
    Console.WriteLine(m2);

    top  = Console.CursorTop;
    left = Console.CursorLeft;

// Read user input from the console. Store up to 15 letter, digit, or underscore
// characters in a SecureString object, or delete a character if the user enters 
// a backspace. Display an asterisk (*) on the console to represent each character 
// that is stored.

    while (true)
        {
        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('*');
                }
            }
        }

// Make the password read-only to prevent it from being modified after it has 
// been collected. 

    password.MakeReadOnly();
    }
}
/*
This example produces results similar to the following text:

(This example simulates entering a password. Do not enter an actual password.)

Enter your password (up to 15 letters, numbers, and underscores)
Press BACKSPACE to delete the last character entered.
Press ESCAPE to quit:
***************

*/
Visual C++
// This example demonstrates using the AppendChar and RemoveAt
// methods to collect a password.
using namespace System;
using namespace System::Security;
int main()
{
   bool go = true;
   ConsoleKeyInfo cki;
   String^ m1 = L"(This example simulates entering a password. "
   L"Do not enter an actual password.)\n";
   String^ m2 = L"Enter your password (up to 15 letters, numbers, and underscores)\n"
   L"Press BACKSPACE to delete the last character entered. \nPress ESCAPE to quit:";
   SecureString ^ password = gcnew SecureString;
   int top;
   int left;

   //
   // The Console.TreatControlCAsInput property prevents this example from
   // ending if you press CTL+C, however all other operating system keys and
   // shortcuts, such as ALT+TAB or the Windows Logo key, are still in effect.
   // Each input character is assumed to occupy one screen column.
   //
   Console::TreatControlCAsInput = true;
   Console::Clear();
   Console::WriteLine( m1 );
   Console::WriteLine( m2 );
   top = Console::CursorTop;
   left = Console::CursorLeft;
   while ( go )
   {
      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( '*' );
         }
      }
   }

   return 0;
}

/*
This example produces results similar to the following text:

(This example simulates entering a password. Do not enter an actual password.)

Enter your password (up to 15 letters, numbers, and underscores)
Press BACKSPACE to delete the last character entered.
Press ESCAPE to quit:
***************

*/
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
See Also

Reference

Tags :


Page view tracker