ConnectorCollection.StartNewConnector Method

Article
02/16/2009

The StartNewConnector(String, String[]) method initiates the process of creating a connector of the specified object type from an array of object classes. If you have a ValueCollection object from the connector space entry, use the ConnectorCollection. StartNewConnector(String, ValueCollection) method.

Syntax

public CSEntry StartNewConnector(
  String objectType,
  String[] objectClass
);

Public Function StartNewConnector( _
  ByVal objectType As String, _
  ByVal objectClass() As String _
) As CSEntry

Parameters

objectType
Contains the name of the object type for the new connector. You must set this parameter to an object type that you have selected for the management agent. To see which object types you selected for a management agent, open Select Object Types in the properties for the management agent.
objectClass
Contains an array of names that are used to populate the LDAP objectClass attribute on the new object. These names constitute the hierarchy of the object in your Active Directory.

Return Value

Returns a CSEntry object (without a distinguished name) that represents the new connector.

Exceptions

Exception type	Condition
ArgumentNullException	The objectType or objectClass is null.
InvalidOperationException	The connector collection is read-only.
NoSuchClassException	Any element of the input object class is not in the schema.
NoSuchObjectTypeException	The object type reference is not in the schema.

Remarks

After calling this method, set the required attribute values and then call the CSEntry.CommitNewConnector method to add the connector to the ConnectorCollection object. If you do not call the CSEntry.CommitNewConnector method after calling this method, the object is rolled back to the original attribute values without generating any error messages.

Because different management agents require different (relative) distinguished name formats, this method handles distinguished names based upon the type of management agent. The types are database management agents; XML without LDAP-style distinguished names; and the management agents that are neither database nor XML.

Management agent type	Distinguished name handling notes
Database	The DN property is writable between the calls to StartNewConnector(String) and CommitNewConnector, and the process may set it. If the DN property is set, then the DN is considered a temporary DN. If the DN property is not set, then a DN is constructed from the anchor attributes. All attributes that contribute to the anchor must have been added to the CSEntry before the call to CommitNewConnector. If any of those attributes were not set, then an AttributeNotPresentException is thrown. The values of the anchor attributes are combined to create the DN for the object. For details, see EscapeDNComponent. After CommitNewConnector is called, the DN property is read-only.
XML	The DN property on the new connector is marked as read-only and thus cannot be set by your process. The DN is constructed from the anchor attributes, and that behavior is exactly the same as the database case. The DN property remains read-only after the call to CommitNewConnector.
All other types	The DN property on the new connector is writable and must be set before the call to CommitNewConnector. If the DN property has not been set, then CommitNewConnector throws an InvalidOperationException. The DN property can be modified after the call to CommitNewConnector, in which case it is treated as a rename on the object.

Database

The DN property is writable between the calls to StartNewConnector(String) and CommitNewConnector, and the process may set it.
If the DN property is set, then the DN is considered a temporary DN.
If the DN property is not set, then a DN is constructed from the anchor attributes. All attributes that contribute to the anchor must have been added to the CSEntry before the call to CommitNewConnector. If any of those attributes were not set, then an AttributeNotPresentException is thrown. The values of the anchor attributes are combined to create the DN for the object. For details, see EscapeDNComponent.
After CommitNewConnector is called, the DN property is read-only.

XML

The DN property on the new connector is marked as read-only and thus cannot be set by your process.
The DN is constructed from the anchor attributes, and that behavior is exactly the same as the database case.
The DN property remains read-only after the call to CommitNewConnector.

All other types

The DN property on the new connector is writable and must be set before the call to CommitNewConnector. If the DN property has not been set, then CommitNewConnector throws an InvalidOperationException.
The DN property can be modified after the call to CommitNewConnector, in which case it is treated as a rename on the object.

Requirements

Product	ILM 2007 FP1
Namespace	Microsoft.MetadirectoryServices
Assembly	Microsoft.MetadirectoryServices
.NET Framework	.NET Framework 2.0