Microsoft Identity Integration Server 2003 Developer Reference

ManagementAgent.EscapeDNComponent (String[])

The EscapeDNComponent(String[]) method creates a ReferenceValue object that contains an escaped distinguished name component from an array of strings. The strings should not contain escaped characters.

[C#]
public ReferenceValue EscapeDNComponent(
  String[] parts
);

[Visual Basic .NET]
Public Function EscapeDNComponent( _
  ByVal parts As String[] _
) As ReferenceValue

Parameters

parts: Contains an array of strings that will be used to build the distinguished name component. The strings should not contain escaped characters.

Return Values

Returns a ReferenceValue object that represents the escaped distinguished name component.

Exceptions

Exception type	Condition
ArgumentException	The management agent requires a distinguished name with a single component and the parts parameter contains zero components or more than one component.
OutOfMemoryException	A memory allocation failure occurred.

Remarks

You can use this method to handle multi-part RDNs.

Because different management agents require different distinguished name formats, this method processes the input strings based upon the type of management agent. The types are LDAP distinguished name, such as Active Directory, Sun ONE Directory Server 5.1 (formerly iPlanet Directory Server), Exchange, and XMLMA with LDAP distinguished names; hierarchical non-LDAP, such as Windows NT and Lotus Notes; and extrinsic, such as database and XML without LDAP distinguished names.

Management agent type	Processing
LDAP Distinguished Name	Any invalid XML characters in the value portion of a given part are hexadecimal-encoded. Any illegal characters (including invalid XML characters) in the name portion of a given part will generate an error. The following characters are escaped: Comma (',') Equal sign ('=') Plus sign ('+') Less-than sign ('<') Greater-than sign ('>') Number sign ('#') Semicolon (';') Backslash ('\') Quotation mark ('"') If the last character in the string is a space, then that space is escaped. Any extraneous leading or trailing spaces around a part name are removed. For the XML management agent, if there are multiple parts, then the parts are alphabetized. If multiple parts are specified, the composite distinguished name string is the concatenation of the individual strings separated by plus signs. An error is generated if the input string is not a well-formed, LDAP-style distinguished name string. Note The validation of distinguished names is less strict than the syntax defined in the LDAP specifications. EscapeDNComponent(String[]) allows a part name to contain any combination of one or more of the characters 'a'-'z', 'A'-'Z', '0'-‘9’, '-', and '.'.
Hierarchical non-LDAP	These management agents do not support multi-part components. If multiple strings are passed to EscapeDNComponent, an ArgumentException is thrown. If any of the characters in the input string are invalid XML characters, an ArgumentException is thrown. All commas and backslashes in the input string are escaped. If the last character in the string is a space, then that space is escaped.
Extrinsic	If any part is binary or contains an invalid XML character, that part is stored as a hexadecimal-encoded version of the raw data with a '#' character prefixed to the front of the string. For example, if a part was 'AxC' (where x represents an illegal XML character such as '0x10'), that part is encoded as '#410010004300'. Note It is not possible to specify a binary part with this method. However, it is possible to have a binary part in CommitNewConnector if the distinguished name is constructed from anchor attributes and one of the anchor attributes is a binary type. Otherwise, all instances of the following characters are escaped: Backslash ('\') Comma (',') Plus sign ('+') Number sign ('#') If the last character in a given part string is a space, that space is escaped. If multiple parts are specified, the composite distinguished name string is the concatenation of all the individual strings separated by plus signs.

Management agent type

Processing

LDAP Distinguished Name

Any invalid XML characters in the value portion of a given part are hexadecimal-encoded.
Any illegal characters (including invalid XML characters) in the name portion of a given part will generate an error.
The following characters are escaped:
- Comma (',')
- Equal sign ('=')
- Plus sign ('+')
- Less-than sign ('<')
- Greater-than sign ('>')
- Number sign ('#')
- Semicolon (';')
- Backslash ('\')
- Quotation mark ('"')
If the last character in the string is a space, then that space is escaped.
Any extraneous leading or trailing spaces around a part name are removed.
For the XML management agent, if there are multiple parts, then the parts are alphabetized.
If multiple parts are specified, the composite distinguished name string is the concatenation of the individual strings separated by plus signs.
An error is generated if the input string is not a well-formed, LDAP-style distinguished name string.

Note The validation of distinguished names is less strict than the syntax defined in the LDAP specifications. EscapeDNComponent(String[]) allows a part name to contain any combination of one or more of the characters 'a'-'z', 'A'-'Z', '0'-‘9’, '-', and '.'.

Hierarchical non-LDAP

These management agents do not support multi-part components. If multiple strings are passed to EscapeDNComponent, an ArgumentException is thrown.
If any of the characters in the input string are invalid XML characters, an ArgumentException is thrown.
All commas and backslashes in the input string are escaped.
If the last character in the string is a space, then that space is escaped.

Extrinsic

If any part is binary or contains an invalid XML character, that part is stored as a hexadecimal-encoded version of the raw data with a '#' character prefixed to the front of the string. For example, if a part was 'AxC' (where x represents an illegal XML character such as '0x10'), that part is encoded as '#410010004300'.
Note It is not possible to specify a binary part with this method. However, it is possible to have a binary part in CommitNewConnector if the distinguished name is constructed from anchor attributes and one of the anchor attributes is a binary type.
Otherwise, all instances of the following characters are escaped:
- Backslash ('\')
- Comma (',')
- Plus sign ('+')
- Number sign ('#')
If the last character in a given part string is a space, that space is escaped.
If multiple parts are specified, the composite distinguished name string is the concatenation of all the individual strings separated by plus signs.

Requirements

Product: Microsoft Identity Integration Server 2003
Namespace: Defined in Microsoft.MetadirectoryServices.
Assembly: Requires Microsoft.MetadirectoryServices (in Microsoft.MetadirectoryServices.dll).
.NET Framework: Requires .NET Framework 1.1.