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 class in this container.

  • Delete()

  • Deletes the 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 this container.

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 object you want to copy.
  • newName – a name of the new object. 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 logon

# Save the user to the directory.
$user.SetInfo()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.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 logon

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

Create()

Creates a directory object of the specified class. The object is not made persistent until IADs::SetInfo is called on the new object.

object Create(string className, string relativeName)

Parameters

  • className – the class name of the object you want to create (e.g. user, group, organizationalUnit, computer).
  • relativeName – the 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 logon

# Save the user to the directory.
$user.SetInfo()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.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 logon

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

Delete()

Deletes the specified directory object from this container.

void Delete(string className, string relativeName)

Parameters

  • className – the class name of the object you want to delete. Also, null is a valid option for this parameter. If an object was created before its 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, so 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.Adsi;
using Softerra.Adaxes.Interop.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.Adsi;
using Softerra.Adaxes.Interop.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 – the class name of the object you want to retrieve. If this parameter is null the method returns the first item found in the container.
  • relativeName – the relative distinguished name (RDN) of the object to retrieve. This parameter can also contain more than one name level, for instance, "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.Adsi;
using Softerra.Adaxes.Interop.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 the specified object to this container. This method can also be used to rename an object.

object MoveHere(string sourceName, string newName)

Parameters

  • sourceName – the ADS path of the object you want to move.
  • newName – the relative distinguished name (RDN) of the object within the target container. If it's null, the object is just moved. If it's not null, the object is also renamed.

Remarks

In Active Directory, you can move an object within the same domain or from a different domain 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 move 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, as well as the password of the object is preserved.

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.Adsi;
using Softerra.Adaxes.Interop.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 that determines which object classes are included in the enumeration. The value is an object[], where each element is the name of a schema class. If no filter is specified, the enumerator retrieves all objects of all classes.

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

Hints

Gets or sets an array of property names to load for each enumerated object. Specifying these properties can help reduce network traffic by retrieving only the data you need. Each element of the array is a string corresponding to a property name defined in the schema.

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

Requirements

Minimum required version: 2009.1

See also

© Softerra 2022. All rights reserved.
Send feedback