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.
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.
| 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.
Important |
|---|
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
Available since 2.0

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.