Convert.ToBase64String Method (Byte(), Base64FormattingOptions)

 

Converts an array of 8-bit unsigned integers to its equivalent string representation that is encoded with base-64 digits. A parameter specifies whether to insert line breaks in the return value.

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

<ComVisibleAttribute(False)>
Public Shared Function ToBase64String (
	inArray As Byte(),
	options As Base64FormattingOptions
) As String

Parameters

inArray
Type: System.Byte()

An array of 8-bit unsigned integers.

options
Type: System.Base64FormattingOptions

InsertLineBreaks to insert a line break every 76 characters, or None to not insert line breaks.

Return Value

Type: System.String

The string representation in base 64 of the elements in inArray.

Exception Condition
ArgumentNullException

inArray is null.

ArgumentException

options is not a valid Base64FormattingOptions value.

The elements of the inArray parameter are taken as a numeric value and converted to a string representation in base 64.

The base-64 digits in ascending order from zero are the uppercase characters "A" to "Z", the lowercase characters "a" to "z", the numerals "0" to "9", and the symbols "+" and "/". The valueless character "=" is used for trailing padding.

System_CAPS_importantImportant

The ToBase64String method is designed to process a single byte array that contains all the data to be encoded. To encode data from a stream, use the System.Security.Cryptography.ToBase64Transform class.

If the options parameter is set to InsertLineBreaks and the output of the conversion is longer than 76 characters, a line break is inserted every 76 characters. A line break is defined as a carriage return character (U+000D) followed by a line feed character (U+000A). Because line breaks are considered whitespace characters in a base-64 encoding, they are ignored when converting a base-64 encoded string back to a byte array. The line breaks are simply convenient when displaying the encoded string to a control or a device such as a console window. For more information, see RFC 2045, "Multipurpose Internet Mail Extensions", at http://www.rfc-editor.org/.

The following example calls the Convert.ToBase64String(Byte(), Base64FormattingOptions) with a Base64FormattingOptions.InsertLineBreaks argument to insert line breaks in the string that is produced by encoding a 100-element byte array.

Module Example
   Public Sub Main()
       ' Define a byte array.
       Dim bytes(99) As Byte
       Dim originalTotal As Integer = 0
       For ctr As Integer = 0 To bytes.GetUpperBound(0)
          bytes(ctr) = CByte(ctr + 1)
          originalTotal += bytes(ctr)
       Next
       ' Display summary information about the array.
       Console.WriteLine("The original byte array:")
       Console.WriteLine("   Total elements: {0}", bytes.Length)
       Console.WriteLine("   Length of String Representation: {0}",
                         BitConverter.ToString(bytes).Length)
       Console.WriteLine("   Sum of elements: {0:N0}", originalTotal)                  
       Console.WriteLine()

       ' Convert the array to a base 64 sring.
       Dim s As String = Convert.ToBase64String(bytes, 
                                               Base64FormattingOptions.InsertLineBreaks)
       Console.WriteLine("The base 64 string:{1}   {0}{1}", 
                         s, vbCrLf)

       ' Restore the byte array.
       Dim newBytes() As Byte = Convert.FromBase64String(s)
       Dim newTotal As Integer = 0
       For Each newByte In newBytes
          newTotal += newByte
       Next
       ' Display summary information about the restored array.
       Console.WriteLine("   Total elements: {0}", newBytes.Length)
       Console.WriteLine("   Length of String Representation: {0}",
                         BitConverter.ToString(newBytes).Length)
       Console.WriteLine("   Sum of elements: {0:N0}", newTotal)                  
   End Sub
End Module
' The example displays the following output:
'   The original byte array:
'      Total elements: 100
'      Length of String Representation: 299
'      Sum of elements: 5,050
'   
'   The base 64 string:
'      AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5
'   Ojs8PT4/QEFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaW1xdXl9gYWJjZA==
'   
'      Total elements: 100
'      Length of String Representation: 299
'      Sum of elements: 5,050

As the output from the example shows, the Convert.FromBase64String succeeds in restoring the original byte array; the line break characters are ignored during the conversion.

.NET Framework
Available since 2.0
Return to top
Show: