ManagementAgent.EscapeDNComponent Method (String[])

  • Article

Creates a ReferenceValue object that contains an escaped distinguished name component from an array of strings. The strings should not contain escaped characters.

Namespace: Microsoft.MetadirectoryServices
Assembly: Microsoft.MetadirectoryServicesEx (in Microsoft.MetadirectoryServicesEx.dll)

Usage

'Usage
Dim instance As ManagementAgent
Dim parts As String()
Dim returnValue As ReferenceValue

returnValue = instance.EscapeDNComponent(parts)

Syntax

'Declaration
Public MustOverride Function EscapeDNComponent ( _
    ParamArray parts As String() _
) As ReferenceValue

public abstract ReferenceValue EscapeDNComponent (
    params string[] parts
)

public:
virtual ReferenceValue^ EscapeDNComponent (
    ... array<String^>^ parts
) abstract

public abstract ReferenceValue EscapeDNComponent (
    String[] parts
)

public abstract function EscapeDNComponent (
    ... parts : String[]
) : 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 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 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 by using this method. However, you can 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

Reference

ManagementAgent Class
ManagementAgent Members
Microsoft.MetadirectoryServices Namespace
ReferenceValue
ManagementAgent Class