IADsContainer

The IADsContainer interface enables you to enumerate, create, delete, and manage child objects. Container objects represent hierarchical directory trees, such as in a file system, and can be used to organize the directory hierarchy.

Inheritance: IDispatch and IEnumerable

Methods

  • Method

  • Description

  • CopyHere()

  • Creates a copy of the specified directory object in this container.

  • Create()

  • Creates a directory object of the specified schema class and a given name in the container.

  • Delete()

  • Deletes a specified directory object from this container.

  • GetEnumerator()

  • Retrieves an enumerator object for the container.

  • GetObject()

  • Retrieves an interface for a directory object in the container.

  • MoveHere()

  • Moves a specified object to the container that implements this interface.

Properties

  • Property

  • Description

  • Count

  • Gets the number of child objects in the container.

  • Filter

  • Gets or sets the filter used to select object classes in a given enumeration.

  • Hints

  • Enables you to indicate which properties to load for each enumerated object.

Details

CopyHere()

Creates a copy of the specified directory object in this container.

object CopyHere(string sourcePath, string newName)

Parameters

  • sourcePath - The ADS path of the directory object to copy.
  • newName - Optional name of the new object within the container. If a new name is not specified for the object (set to null), the new object will have the same name as the source object.

Examples

The following code sample copies the John Smith user object to the new user object, Denise Smith, within the same Organization Unit.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the target container
$targetcontainerDN = "CN=Users,DC=domain,DC=com"
$targetContainer = $service.OpenObject("Adaxes://$targetcontainerDN", $null, $null, 0)

# Create a new user object by copying the user account of John Smith
$sourceUserPath = "Adaxes://CN=John Smith,OU=Sales,DC=domain,DC=com"
$newUserRdn = "CN=Denise Smith"
$user = $targetContainer.CopyHere($sourceUserPath, $newUserRdn)

# Update some properties
$user.Put("givenName", "Denise") # First Name
$user.Put("sn", "Smith") # Last Name
$user.Put("userPrincipalName", "dsmith") # Username
$user.Put("unicodePwd", "secret") # Password
$user.Put("pwdLastSet", 0); # Must Change Password at First Logon

# Save the user to the directory
$user.SetInfo()
C#
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the target container
        const string targetContainerPath = "Adaxes://CN=Users,DC=domain,DC=com";
        IADsContainer targetContainer = (IADsContainer)service.OpenObject(
            targetContainerPath, null, null, 0);

        // Create a new user object by copying the user account of John Smith
        const string sourceUserPath = "Adaxes://CN=John Smith,OU=Sales,DC=domain,DC=com";
        const string newUserRdn = "CN=Denise Smith";
        IADs user = (IADs)targetContainer.CopyHere(sourceUserPath, newUserRdn);

        // Update some properties
        user.Put("givenName", "Denise"); // First Name
        user.Put("sn", "Smith"); // Last Name
        user.Put("userPrincipalName", "dsmith"); // Username
        user.Put("unicodePwd", "secret"); // Password
        user.Put("pwdLastSet", 0); // Must Change Password at First Logon

        // Save the user to the directory
        user.SetInfo();
    }
}

Create()

Creates a directory object of the specified schema class and a given name in the container. The object is not made persistent until IADs::SetInfo is called on the new object.

object Create(string className, string relativeName)

Parameters

  • className - Name of the schema class object to be created (e.g. user, group, organizationalUnit, computer).
  • relativeName - Relative distinguished name (RDN) of the object as it is known in the directory.

Examples

The following code sample creates a new user object.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the target container
$targetcontainerDN = "CN=Users,DC=domain,DC=com"
$targetContainer = $service.OpenObject("Adaxes://$targetcontainerDN", $null, $null, 0)

# Create a new user object
$user = $targetContainer.Create("user","CN=John Smith")

# Update some properties
$user.Put("givenName", "John") # First Name
$user.Put("sn", "Smith") # Last Name
$user.Put("userPrincipalName", "jsmith") # Username
$user.Put("unicodePwd", "secret") # Password
$user.Put("pwdLastSet", 0); # Must Change Password at First Logon

# Save the user to the directory
$user.SetInfo()
C#
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the target container
        const string targetContainerPath = "Adaxes://CN=Users,DC=domain,DC=com";
        IADsContainer targetContainer = (IADsContainer)service.OpenObject(
            targetContainerPath, null, null, 0);

        // Create a new user object
        IADs user = (IADs)targetContainer.Create("user", "CN=John Smith");

        // Update some properties
        user.Put("givenName", "John"); // First Name
        user.Put("sn", "Smith"); // Last Name
        user.Put("userPrincipalName", "jsmith"); // Username
        user.Put("unicodePwd", "secret"); // Password
        user.Put("pwdLastSet", 0); // Must Change Password at First Logon

        // Save the user to the directory
        user.SetInfo();
    }
}

Delete()

Deletes a specified directory object from this container.

void Delete(string className, string relativeName)

Parameters

  • className - The schema class object to delete. Also, null is a valid option for this parameter. Providing null for this parameter is the only way to deal with defunct schema classes. If an instance was created before the class became defunct, the only way to delete the instance of the defunct class is to call Delete and provide null for this parameter.
  • relativeName - The relative distinguished name (RDN) of the object to be deleted.

Remarks

The object to be deleted must be a leaf object or a childless subcontainer. To delete a container and its children that are a subtree, use IADsDeleteOps::DeleteObject

The specified object is immediately removed after calling the Delete method and calling IADs::SetInfo on the container object is unnecessary.

Examples

The following code sample deletes a user.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the target container
$targetcontainerDN = "CN=Users,DC=domain,DC=com"
$targetContainer = $service.OpenObject("Adaxes://$targetcontainerDN", $null, $null, 0)

# Delete user
$targetContainer.Delete("user","CN=John Smith")
C#
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the target container
        const string targetContainerPath = "Adaxes://CN=Users,DC=domain,DC=com";
        IADsContainer targetContainer = (IADsContainer)service.OpenObject(
            targetContainerPath, null, null, 0);

        // Delete the user
        targetContainer.Delete("user", "CN=John Smith");
    }
}

GetEnumerator()

Retrieves an enumerator object for the container. The enumerator object implements the IEnumerator interface that can be used to enumerate the children of the container in foreach loops.

IEnumerator GetEnumerator()

Examples

The following code sample shows how to enumerate child objects in a container.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the target container
$containerDN = "CN=Users,DC=domain,DC=com"
$container = $service.OpenObject("Adaxes://$containerDN", $null, $null, 0)

# Enumerate child objects in a container
$container.Filter = @("user","group")

foreach($child in $container)
{
    Write-Host $child.Name
}
C#
using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the target container
        const string containerPath = "Adaxes://CN=Users,DC=domain,DC=com";
        IADsContainer container = (IADsContainer)service.OpenObject(
        containerPath, null, null, 0);

        // Enumerate child objects in a container
        container.Filter = new object[] {"user","group"};

        foreach (IADs child in container)
        {
            Console.WriteLine(child.Name);
        }
    }
}

GetObject()

Retrieves an interface for a directory object in the container.

object GetObject(string className, string relativeName)

Parameters

  • className - Specifies the name of the object class as of the object to retrieve. If this parameter is null the method returns the first item found in the container.
  • relativeName - Specifies the relative distinguished name (RDN) of the object to retrieve. The relativeName parameter can also contain more than one level of name, such as "CN=John Smith,OU=Sales".

Examples

The following code sample retrieves a user object from a container object.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the target container
$containerDN = "CN=Users,DC=domain,DC=com"
$container = $service.OpenObject("Adaxes://$containerDN", $null, $null, 0)

# Retrieve a user object from a container object
$user = $container.GetObject("user","CN=John Smith")

Write-Host $user.Name
C#
using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the target container
        const string containerPath = "Adaxes://CN=Users,DC=domain,DC=com";
        IADsContainer container = (IADsContainer)service.OpenObject(
            containerPath, null, null, 0);

        // Retrieve a user object from a container object
        IADs user = (IADs) container.GetObject("user", "CN=John Smith");

        Console.WriteLine(user.Name);
    }
}

MoveHere()

Moves a specified object to the container that implements this interface. The method can be also used to rename an object.

object MoveHere(string sourceName, string newName)

Parameters

  • sourceName - A string that specifies the ADS path of the object to be moved.
  • newName - A string that specifies the relative distinguished name (RDN) of the object within the target container. This can be null, in which case the object is moved. If it is not null, the object is renamed accordingly in the process.

Remarks

In Active Directory, you can move an object within the same domain or from different domains in the same directory forest. For the cross domain move, the following restrictions apply:

  • The destination domain must be in the native mode.
  • The object to be moved must be a leaf object or an empty container.
  • NT LAN Manager (NTLM) cannot perform authentication, use Kerberos authentication or delegation. Be aware that if Kerberos authentication is not used, the password transmits in plain text over the network. To avoid this, use delegation with secure authentication.
  • You cannot move security principals (for example, user, group, computer, and so on) belonging to a global group. When a security principal is moved, a new SID is created for the object at the destination. However, its old SID from the source, stored in the sIDHistory attribute, is preserved, as well as the password of the object.

Examples

The following code sample moves a user object using the MoveHere method.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the target organizational unit
$targetOUDN = "OU=TargetOU,DC=domain,DC=com"
$targetOU = $service.OpenObject("Adaxes://$targetOUDN",`
    $null, $null, 0)

# Move the account of John Smith from SourceOU to TargetOU
$userPath = "Adaxes://CN=John Smith,OU=SourceOU,DC=domain,DC=com"
$movedUser = $targetOU.MoveHere($userPath, $null)
C#
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the target organizational unit
        const string targetOUPath = "Adaxes://CN=TargetOU,DC=domain,DC=com";
        IADsContainer targetOU = (IADsContainer)service.OpenObject(
            targetOUPath, null, null, 0);

        // Move the account of John Smith from SourceOU to TargetOU
        const string userPath = "Adaxes://CN=John Smith,OU=SourceOU,DC=company,DC=com";
        IADsUser movedUser = (IADsUser)targetOU.MoveHere(userPath, null);
    }
}

Count

Gets the number of child objects in the container. When the Filter property is set, this property gets only the number of filtered items.

  • Type:
  • int
  • Access:
  • Read-Only

Filter

Gets or sets the filter used to select object classes in a given enumeration. This is an object[] array, each element of which is the name of a schema class. If the property is not set, all objects of all classes are retrieved by the enumerator.

  • Type:
  • Object
  • Access:
  • Read/Write

Hints

Gets or sets the properties to load for each enumerated object. Such data may be used to optimize network access. This is a string[] array, each element of which identifies the name of a property found in the schema definition.

  • Type:
  • Object
  • Access:
  • Read/Write

Requirements

Minimum required version: 2009.1

See also

© Softerra 2022. All rights reserved.
Send feedback