Creates a ReferenceValue object that contains an escaped distinguished name component from an array of Value objects.
Namespace: Microsoft.MetadirectoryServices
Assembly: Microsoft.MetadirectoryServicesEx (in microsoft.metadirectoryservicesex.dll)

Usage

Visual Basic 
Dim instance As ManagementAgent
Dim parts As Value()
Dim returnValue As ReferenceValue

returnValue = instance.EscapeDNComponent(parts)

Syntax

Visual Basic 
Public MustOverride Function EscapeDNComponent ( _
		ParamArray parts As Value() _
) As ReferenceValue
C# 
public abstract ReferenceValue EscapeDNComponent (
		params Value[] parts
)
C++ 
public:
virtual ReferenceValue^ EscapeDNComponent (
		... array<Value^>^ parts
) abstract
J# 
public abstract ReferenceValue EscapeDNComponent (
		Value[] parts
)
JScript 
public abstract function EscapeDNComponent (
		... parts : Value[]
) : ReferenceValue

Parameters

parts

Contains an array of Value objects that are used to build the distinguished name component.

Return Value

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

Exceptions

Exception type Condition
System.ArgumentException

The management agent requires a distinguished name that has a single component, and the parts parameter contains zero components or more than one component.
System.OutOfMemoryException

A memory allocation failure occurred.

Remarks

You can use this method to handle multi-part relative distinguished names (RDNs).

Because different management agents require different distinguished name formats, this method processes the input strings based on the type of management agent. The types are Lightweight Directory Access Protocol (LDAP) distinguished name, such as Active Directory Domain Services (AD DS), Sun ONE Directory Server 5.1 (formerly iPlanet Directory Server), Microsoft 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 prohibited characters (including invalid XML characters) in the name portion of a given part 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, 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, 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 that is defined in the LDAP specifications. EscapeDNComponent 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, 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 a prohibited XML character such as '0x10'), that part is encoded as '#410010004300'.

    Note:
    You cannot specify a binary part with this method. However, you can 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.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Target Platforms

Change History

See Also