You can convert text to bytes and bytes back to text in OCL and EAL by using the .NET static Encoding class; use this when an import, export, file, or external system specifies a character encoding.
Convert between strings and bytes
An encoding defines how characters are represented as numeric byte values. Choose the same encoding at both ends of the exchange. For example, text encoded as UTF-8 must be decoded as UTF-8.
| Task | OCL expression pattern | Result |
|---|---|---|
| Encode text as bytes | Encoding.<EncodingName>.GetBytes(<StringExpression>)
|
A byte array (Blob) |
| Decode bytes as text | Encoding.<EncodingName>.GetString(<ByteArrayExpression>)
|
A string |
Encode a string
Use GetBytes when the receiving system expects byte data in a known encoding.
Encoding.UTF8.GetBytes(Customer.allinstances->first.Name)
This expression converts the first customer's name to a byte array using UTF-8. See GetBytes for the operation syntax and use cases.
Decode a byte array
Use GetString when you have byte data and know how the source encoded the text.
Encoding.ASCII.GetString(bytearray)
This expression interprets bytearray as ASCII and returns a string. If the byte array contains text from an external system, use that system's declared encoding rather than selecting one based only on the visible result.
Choose the encoding deliberately
The encoding changes how characters become bytes. ASCII is appropriate only when the data is limited to its character set. UTF-8 represents Unicode text, including accented characters and emoji, and is used when the external contract requires UTF-8.
| Encoding member | Use it when | Related documentation |
|---|---|---|
Encoding.UTF8
|
The external system requires UTF-8 text, including Unicode characters such as é or 😊.
|
UTF8 |
Encoding.UTF7
|
The external system explicitly requires UTF-7. | UTF7 |
Encoding.UTF32
|
The external system explicitly requires UTF-32. | UTF32 |
Encoding.BigEndianUnicode
|
The external system requires big-endian UTF-16 (UTF-16BE). | BigEndianUnicode |
Encoding.Default
|
You intentionally need the default encoding of the running .NET implementation. | Default |
Do not treat Default as a named interchange encoding
Encoding.Default uses the default encoding for the running .NET implementation. It is not a declaration that data is ISO-8859-1. For example:
Encoding.Default.GetBytes(Customer.allinstances->first.Name)
Use this only when the integration requires the runtime's default encoding. When another party specifies an encoding, use the matching encoding member or conversion required by that integration.
Base64 is not a character encoding
Base64 represents binary data as text. It does not replace selecting the correct character encoding. If you must convert text using a specified code page and send or store the result as Base64, use StringToEncodedBase64. For example, the related operation accepts code page 28591 for ISO-8859-1 Latin 1.
For legacy systems that require Windows-1252 (ANSI) Base64, use StringToAnsiBase64. The related documentation notes that non-Unicode data can cause problems when stored in a string; use Base64 where the integration requires a text-safe representation of encoded bytes.
See also
Character encoding in OCL
You can encode String values as bytes and decode byte arrays in OCL when an integration, file, or external system requires a known character encoding.
Encode and decode text
Character encoding defines how text characters are represented as bytes. In OCL, use the .NET Encoding static class to convert between a String and a byte array:
GetBytes(string)converts text to bytes.GetString(bytearray)converts bytes to text.
For example, encode a customer name as UTF-8 bytes before sending it to an external system:
Encoding.UTF8.GetBytes(Customer.allinstances->first.Name)
Decode a byte array that is known to be ASCII:
Encoding.ASCII.GetString(bytearray)
Use the same encoding for both operations. For example, bytes created with Encoding.UTF8.GetBytes(...) must be decoded with Encoding.UTF8.GetString(...).
Available encodings
The Encoding static class provides the encoding names documented in the following OCL operator pages.
| Encoding | Use | Example |
|---|---|---|
| UTF8 | A variable-length Unicode encoding for text that includes accents, emoji, and non-English letters. | Encoding.UTF8.GetBytes('á😊')
|
| ASCII | An encoding for ASCII text. | Encoding.ASCII.GetString(bytearray)
|
| Unicode | Unicode text representation. | Encoding.Unicode.GetBytes('Café')
|
| BigEndianUnicode | UTF-16 big-endian Unicode encoding, where the most significant byte comes first. | Encoding.BigEndianUnicode.GetBytes('Café')
|
| UTF32 | A fixed-length Unicode encoding that stores each Unicode code point in 32 bits. | Encoding.UTF32.GetBytes('😊')
|
| UTF7 | A variable-length, 7-bit-safe Unicode encoding. | Encoding.UTF7.GetBytes('Café')
|
| Default | The default encoding for the running .NET implementation. | Encoding.Default.GetBytes(Customer.allinstances->first.Name)
|
Choose an encoding for an integration
- Identify the encoding required by the receiving system. For example, an API or file format may require UTF-8, while a legacy system may require Windows-1252 or ISO-8859-1.
- Encode the String with that encoding by calling
GetBytes. - Decode returned bytes with the encoding specified by the sender.
- Test with text that contains the characters your users enter. For UTF-8, include accented characters such as
á,é, andó, and an emoji such as😊.
Do not rely on Encoding.Default when the external format defines a specific encoding. Default follows the running .NET implementation's default encoding, so use an explicit encoding when the integration contract specifies one.
Legacy and Base64 conversions
When a legacy system requires ISO-8859-1 Latin 1 text represented as Base64, use StringToEncodedBase64 with code page 28591:
'Example'.StringToEncodedBase64(28591)
When a legacy system requires Windows-1252 (ANSI) Base64, use StringToAnsiBase64:
'Hello World'.StringToAnsiBase64()
A non-Unicode string can cause storage problems in the String type. Use Base64 encoding when you need to preserve such data as text.