Adaxes SDKShow AllHide All

Writing ADSI Scripts

Adaxes ADSI Provider lets you use ADSI interfaces to connect and communicate with Adaxes Service. You can use the ADSI Provider in custom client applications, standalone scripts, and scripts executed by Business Rules, Scheduled Tasks and Custom Commands.

The Adaxes ADSI objects are COM Automation objects that can be accessed and manipulated by any language that supports COM, such as VBScript, PowerShell, C++, and .NET languages like VB.NET and C#.

Referencing ADSI Provider Assembly

Adaxes ADSI Provider is implemented as a .NET assembly targeted for Microsoft .NET Framework version 4.5.2. The assembly is called Softerra.Adaxes.Adsi.dll and is installed into the GAC when you install Adaxes ADSI Provider.

Referencing the assembly in PowerShell scripts

To use the ADSI Provider in a PowerShell script, you need to load the Softerra.Adaxes.Adsi assembly into the PowerShell session:

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

If your PowerShell script is executed by a Business Rule, Scheduled Task, or Custom Command, the assembly is loaded automatically.

Adding a reference to the assembly in a .NET project

  1. Ensure that the target framework for the project is .NET Framework 4.5.2.

  2. Add a reference to the Softerra.Adaxes.Adsi assembly to the project (the assembly is installed into the GAC).

    Adaxes ADSI Provider

Connecting to Adaxes Service

To start using the ADSI Provider, you need to establish a connection with an Adaxes service. You can either establish a connection with the specific Adaxes service running on a specific computer, or, if you have multiple Adaxes services sharing configuration, you can let the provider select the service to connect to. In the latter case, the ADSI provider will connect to the nearest available Adaxes service.

Connecting to a Specific Service

To connect to the Adaxes service running on a given computer, you need to create an instance of the AdmNamespace class and call the GetServiceDirectly method of it, passing the DNS name or IP address of the computer as the parameter of the method. The AdmNamespace class supports the IAdmNamespace interface. A connection is represented by the IAdmService interface.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
    }
}

Connecting to the nearest available service

All Adaxes services sharing common configuration are grouped into logical units called configuration sets. Adaxes ADSI Provider allows you to connect to the nearest available Adaxes service that belong to a configuration set. To connect to the nearest Adaxes service from a configuration set, you need to create an instance of the AdmNamespace class and call the GetNearestService method of it. The first parameter of the method specifies the name of the AD domain where to search for Adaxes services. The 2nd and 3rd parameters of the method are the username and password that will be used to access the domain. If you want to use the credentials of the currently logged on user, set those parameters to NULL. A connection is represented by the IAdmService interface.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$username = $NULL
$password = $NULL
$admService = $admNS.GetNearestService("mydomain.com", $username, $password)
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        String username = null;
        String password = null;
        IAdmService admService = adsNS.GetNearestService("mydomain.com", username, password);
    }
}

If there are multiple configuration sets in your domain, you need to specify which one to use by setting the ID of the desired configuration set to the DefaultConfigurationSet property of the AdmNamespace instance.

$admNS.DefaultConfigurationSet = "{c91c481f-64e3-455c-a674-8b857e444fec}"

For information on how to get the ID of a configuration set, see Get the Configuration Set ID.

Binding to ADSI Objects

To perform any operation in the directory, you need to bind to a directory object first. For example, to read and write properties of an object, first you need to bind to the object; to create a new object, you need to bind to the OU where you want to create the object; to search the directory, you need to bind to the directory object, under which you want to perform a search. 'Directory object' here means both Active Directory objects and Adaxes configuration objects, like Business Rules, Security Roles, Scheduled Tasks, and Business Units.

After you've bound to an object, you can use the appropriate ADSI interfaces to perform operations on the object. The interfaces you can use depend on the type of the directory object. All object types support the IADs and IAdmTop interfaces. User objects support the IADsUser interface, group objects support the IADsGroup interface. Container objects, such as Organizational Units, support the IADsContainer interface that allows you to enumerate and manage their child objects. For more information, see Interfaces Supported by Directory Objects.

To bind to a directory object, you need to call the OpenObject method of the IAdmService interface. To specify to which object you want to bind, you need to provide the ADS path of the object as the first parameter of the method.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADsUser user = (IADsUser)admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",
          null, null, 0);
    }
}

If your script is executed by a Business Rule, Scheduled Task, or Custom Command, you can use the BindToObject method of the predefined variable $Context:

$adObject = $Context.BindToObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com")

The ADS path requires the following format:

Adaxes://[Server[:Port]]/ObjectIdentifier

  • Adaxes (required): Specifies the namespace name of the ADSI provider. The namespace name for the Adaxes ADSI Provider is Adaxes. The namespace name of the provider is case sensitive.

  • Server (optional): Specifies the domain controller name, IP address, or the domain name where the provider will search for the directory object referred by the ADS path.

  • Port (optional): Specifies the port to be used for the connection. If no port number is specified, the ADSI provider will use the default port number. The default port number is 389 if not using an SSL connection or 636 if using an SSL connection.

  • ObjectIdentifier (required): Specifies the identifier of a directory object. The identifier can be a distinguished name (DN), GUID or SID (see examples below).

To work with ADS paths, you can use the AdsPath and DN helper classes.

Binding to an object by DN

To bind to a directory object using the object's distinguished name, the ObjectIdentifier part of the ADS path must contain the DN of the object. For example:

Adaxes://CN=John Smith,CN=Users,DC=mycompany,DC=com

or

Adaxes://mydomain.com/CN=John Smith,CN=Users,DC=mycompany,DC=com

For details on how to get the DN of a directory object, see Get the DN of an Active Directory Object.

The following example shows how to bind to a specific user account by DN and then disable the account.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=mycompany,DC=com",`
    $NULL, $NULL, 0)
$user.AccountDisabled = $True
$user.SetInfo()
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADsUser user = (IADsUser)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=mycompany,DC=com", null, null, 0);
        user.AccountDisabled = true;
        user.SetInfo();
    }
}

Binding to an object by GUID

Each directory object has a globally unique identifier (GUID) that is stored in the objectGUID property of the object. As opposed to the distinguished name that changes when an object is renamed or moved, the object GUID never changes. So, if you want an ADS path to be valid after an object is renamed or moved, you need to use the object's GUID in the path.

To bind to a directory object using the object's GUID, the ObjectIdentifier part of the ADS path must contain the GUID of the object. For example:

Adaxes://<GUID=90495758-7E98-47B6-AA98-5B49129EF1DB>

If your Adaxes service manages multiple AD domains, it is recommended that the ADS path contains the name of the domain where the object is located. This will make the binding operation faster.

Adaxes://mydomain.com/<GUID=90495758-7E98-47B6-AA98-5B49129EF1DB>

The following example binds to a specific directory object by its DN, gets the GUID of the object, and then binds to the object using the GUID.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$object = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)
$guid = [Guid]$object.Get("objectGUID")
$guidPath = "Adaxes://<GUID=$guid>"
$object = $admService.OpenObject($guidPath, $NULL, $NULL, 0)
using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADs obj = (IADs)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", null, null, 0);
        byte[] guidBytes = (byte[])obj.Get("objectGUID");
        Guid guid = new Guid(guidBytes);
        string guidPath = string.Format("Adaxes://<GUID={0}>", guid);
        obj = (IADs)admService.OpenObject(guidPath, null, null, 0);
    }
}

Binding to an object by SID

Each Active Directory security principal (user, security group, computer) has a security identifier (SID) that is stored in the objectSID property of the object. The SID is unique within the domain and does not change even if the object is renamed or moved to another container (within the same domain).

Adaxes ADSI provider allows you to bind to a directory object using the object's SID. To bind to an object using its SID, the ObjectIdentifier part of the ADS path must contain the SID of the object in the SDDL form. For example:

Adaxes://<SID=S-1-5-21-573937-2149998-410785>

If your Adaxes service manages multiple AD domains, it is recommended that the ADS path contains the name of the domain where the object is located. This will make the binding operation faster.

Adaxes://mydomain.com/<SID=S-1-5-21-573937-2149998-410785>

To convert the value of the objectSID property to the SDDL form, you can use the Sid class.

The following example binds to a specific user by its DN, gets the SID of the user, and then binds to the user using the SID.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)
$sidBytes = $user.Get("objectSID")
$sid = New-Object "Softerra.Adaxes.Adsi.Sid" @($sidBytes, 0)
$sidPath = "Adaxes://<SID=$sid>"
$user = $admService.OpenObject($sidPath, $NULL, $NULL, 0)
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADs user = (IADs)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", null, null, 0);
        byte[] sidBytes = (byte[])user.Get("objectSID");
        Sid sid = new Sid(sidBytes, 0);
        string sidPath = string.Format("Adaxes://<SID={0}>", sid);
        user = (IADs)admService.OpenObject(sidPath, null, null, 0);
    }
}

Binding to the RootDSE

RootDSE (Root Directory Service Entry) is the root of the Active Directory data tree. Properties of the RootDSE object can be used to retrieve data such as distinguished names of the domain, schema, and configuration containers of the Active Directory. The following ADS path can be used to bind to the RootDSE:

Adaxes://<servername>/rootDSE

The <servername> is the name of a domain or the DNS name of a domain controller. The <servername> is optional, as shown in the following ADS path:

Adaxes://rootDSE

In this case, the path will refer to the RootDSE of the directory server that is used to store Adaxes configuration data (ADAM or AD/LDS).

The following example shows how to bind to the RootDSE of a domain, and get the DNS name of the domain controller being used by the Adaxes service.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$rootDse = $admService.OpenObject("Adaxes://mydomain.com/rootDSE", $NULL, $NULL, 0)
$dcDnsName = $rootDse.Get("dnsHostName")

Write-Host $dcDnsName
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IADs rootDse = (IADs)admService.OpenObject("Adaxes://mydomain.com/rootDSE", null, null, 0);
        string dcDnsName = (string)rootDse.Get("dnsHostName");

        Console.WriteLine(dcDnsName);
    }
}

Binding to the domain partition

The domain partition (or the default naming context) stores directory objects like users, groups, computers and Organizational Units. The domain partition is replicated to all domain controllers of a domain. When you bind to the domain partition, you bind to the top container of the domain. This means that if, for example, you want to search the whole domain, you need to perform a search under the domain partition object.

The following ADS path can be used to bind to the domain partition of a domain:

Adaxes://<servername>

The <servername> is the name of a domain or the DNS name of a domain controller.

The following example shows how to update the minimum password length in the Defult Domain Password Policy by updating the minPwdLength property of the domain partition object.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$defaultNC = $admService.OpenObject("Adaxes://mydomain.com", $NULL, $NULL, 0)
$defaultNC.Put("minPwdLength", 8)
$defaultNC.SetInfo()
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IADs defaultNC = (IADs)admService.OpenObject("Adaxes://mydomain.com", null, null, 0);
        defaultNC.Put("minPwdLength", 8);
        defaultNC.SetInfo();
    }
}

Binding to an object's parent

In ADSI, every directory object is represented by an object that exposes the IADs interface. To get the ADS path of the parent container of an object, you can use the IADs::Parent property. Then you can use the obtained ADS path to bind to the parent object.

The following example shows how to bind to the parent container of a directory object.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$object = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=mycompany,DC=com",`
    $NULL, $NULL, 0)

$parent = $admService.OpenObject($object.Parent, $NULL, $NULL, 0)
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IADs obj = (IADs)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=mycompany,DC=com", null, null, 0);
        
        IADs parent = (IADs)admService.OpenObject(obj.Parent, null, null, 0);
    }
}

Binding to child objects

In ADSI, every container object exposes the IADsContainer interface. You can use the IADsContainer::GetObject method to bind to a child object. The IADsContainer::GetObject method takes the object class and the relative distinguished name (RDN) of the directory object you want to bind to as parameters.

The following example shows how to bind to a child object of a container object.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$parent = $admService.OpenObject("Adaxes://CN=Users,DC=mycompany,DC=com",`
    $NULL, $NULL, 0)

$child = $parent.GetObject("user", "CN=John Smith")
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IADsContainer parent = (IADsContainer)admService.OpenObject(
            "Adaxes://CN=Users,DC=mycompany,DC=com", null, null, 0);

        IADs child = (IADs)parent.GetObject("user", "CN=John Smith");
    }
}

You can also use the AdsPath helper class to build the ADS path of a child object.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$parentPath = "Adaxes://CN=Users,DC=mycompany,DC=com"
$adsPath = New-Object "Softerra.Adaxes.Adsi.AdsPath" $parentPath

$childPath = $adsPath.CreateChildPath("CN=John Smith")
$child = $admService.OpenObject($childPath.ToString(), $NULL, $NULL, 0)
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        const string parentPath = "Adaxes://CN=Users,DC=mycompany,DC=com";
        AdsPath adsPath = new AdsPath(parentPath);
        
        AdsPath childPath = adsPath.CreateChildPath("CN=John Smith");
        IADs child = (IADs)admService.OpenObject(childPath.ToString(), null, null, 0);
    }
}

This approach works only if the ADS path of the parent object contains the object DN.

Binding to Adaxes-specific objects

Using Adaxes ADSI Provider, you can also manage Adaxes configuration objects, such as Security Roles, Business Rules, Scheduled Tasks, and Business Units. Adaxes-specific objects are stored in the Adaxes Configuration Server (ADAM or AD/LDS) that is installed on the computer where the Adaxes Service is running. You can manage Adaxes configuration objects in the same way you manage Active Directory objects.

Each type of an Adaxes configuration object is stored in a separate container. That is, there is a separate container for Business Rules, Security Roles, Property Patterns, etc.

To get the ADS path of a container that stores Adaxes configuration objects, you need to call the GetConfigurationContainerPath method of the IAdmServiceBackend interface and provide the alias of the desired container as the first parameter of the method. The IAdmServiceBackend interface can be obtained via the Backend property of the AdmNamespace instance.

The following example shows how to get the ADS path of the container where Business Rules are stored.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$businessRulesPath = $admService.Backend.GetConfigurationContainerPath(`
    "BusinessRules")
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        string businessRulesPath = admService.Backend.GetConfigurationContainerPath(
            "BusinessRules");
    }
}

Aliases for containers that store Adaxes configuration objects:

ContainerAlias
Security Roles AccessControlRoles
Business Rules BusinessRules
Property Patterns PropertyPatterns
Custom Commands CustomCommands
Scheduled Tasks ScheduledTasks
Approval Requests ApprovalRequests
Business Units BusinessUnits
Managed Active Directory Domains ManagedDomains
Policies for Password Self-Service PasswordSelfServicePolicies
Office 365 Tenants CloudServicesO365
Common settings for a set of Adaxes services that share configuration ConfigurationSetSettings
Web Interface Configurations WebUIConfigurationContainer
SMS Settings SMSSettings
Root Container for Reports ReportsRoot
Reports \ Overview ReportOverviews
Reports \ All reports Reports
Reports \ Schedule ReportSchedule
Report Categories ReportCategories
Service Settings ServiceSettings

Example 1: Bind to the Scheduled Tasks container:

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$scheduledTasksPath = $admService.Backend.GetConfigurationContainerPath(`
    "ScheduledTasks")
$scheduledTasksContainer = $admService.OpenObject($scheduledTasksPath,`
     $NULL, $NULL, 0)
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        string scheduledTasksPath = admService.Backend.GetConfigurationContainerPath(
            "ScheduledTasks");
        IADsContainer scheduledTasksContainer =
            (IADsContainer)admService.OpenObject(scheduledTasksPath, null, null, 0);
    }
}

Example 2: Bind to the Scheduled Task called My Task.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$scheduledTasksPath = $admService.Backend.GetConfigurationContainerPath(`
    "ScheduledTasks")
$containerAdsPath = New-Object "Softerra.Adaxes.Adsi.AdsPath"`
    $scheduledTasksPath
$taskAdsPath = $containerAdsPath.CreateChildPath("CN=My Task")
$task = $admService.OpenObject($taskAdsPath.ToString(), $NULL, $NULL, 0)
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
using Softerra.Adaxes.Interop.Adsi.ScheduledTasks;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        String scheduledTasksPath = admService.Backend.GetConfigurationContainerPath(
            "ScheduledTasks");
        AdsPath containerAdsPath = new AdsPath(scheduledTasksPath);
        AdsPath taskAdsPath = containerAdsPath.CreateChildPath("CN=My Task");
        IAdmScheduledTask task =
            (IAdmScheduledTask)admService.OpenObject(taskAdsPath.ToString(), null, null, 0);
    }
}

For information on how to manage Adaxes configuration objects, see the section entitled Managing Adaxes Configuration.

Reading Object Properties

Directory object data is stored in its properties. For example, the first name of a user is stored in the givenName property of the user object. Some object properties are required while others are optional.

To read properties of a directory object, you can use the IADs interface that is supported by all ADSI objects. To read a property, you need to call the Get or GetEx method of the IADs interface and pass the LDAP name of the property you want to read as the parameter of the method.

The following example shows how to get the user logon name (pre-Windows 2000) of a user account. The user logon name is stored in the sAMAccountName property.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)
$username = $user.Get("sAMAccountName")
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADs user = (IADs)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", null, null, 0);
        string username = (string)user.Get("sAMAccountName");
    }
}

Apart from the IADs interface, you can also use other ADSI interfaces to read properties of directory objects. The interfaces you can use depend on the type of the directory object. For more information, see Interfaces Supported by Directory Objects.

The following example shows how to get the Terminal Services profile path of a user by reading the TerminalServicesProfilePath property of the IADsTSUserEx interface.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject(`
    "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", $NULL, $NULL, 0)
$tsProfilePath = $user.TerminalServicesProfilePath
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADsTSUserEx tsUser = (IADsTSUserEx)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", null, null, 0);
        string tsProfilePath = tsUser.TerminalServicesProfilePath;
    }
}

Modifying Object Properties

To modify properties of a directory object you can use the Put and PutEx methods of the IADs interface. Both methods only make changes to property values contained in the property cache of the object. In order to commit changes to the directory, you must call IADs::SetInfo.

The following example shows how to modify the description and account expiration date of a user object.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)

$user.Put("description", "My description")
$expirationDate = (Get-Date).AddDays(30) # current date + 30 days
$user.Put("accountExpires", $expirationDate)
$user.SetInfo()
using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADs user = (IADs)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", null, null, 0);
        
        user.Put("description", "My description");
        DateTime expirationDate = DateTime.Now.AddDays(30); // current date + 30 days
        user.Put("accountExpires", expirationDate);
        user.SetInfo();
    }
}

See also: Modifying User Accounts, Enabling and Disabling User Accounts, Unlocking User Accounts, Renaming User Accounts, Modifying Groups, Modifying Organizational Units.

Creating Objects

To create a new directory object, first you need to bind to the Organizational Unit or container where you want to create the object. All containers and Organizational Units expose the IADsContainer interface. To create a new object, you need to call the IADsContainer::Create method and pass in the object class and relative distinguished name (RDN) of the object being created. The Create method returns an instance of an ADSI object that represents the new directory object. Then you need to set object properties by calling IADs::Put and IADs::PutEx methods of the returned ADSI object. To save the object to the directory, call IADs::SetInfo.

The following example shows how to create a new user in Active Directory.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

# Bind to the parent container
$parent = $admService.OpenObject("Adaxes://CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)

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

# Set object properties
$user.Put("givenName", "John") # First Name
$user.Put("sn", "Smith") # Last Name
$user.Put("sAMAccountName", "jsmith") # User Logon Name (pre-Windows 2000)
$user.Put("unicodePwd", "secret") # Password
$user.Put("pwdLastSet", 0) # Must Change Password at First Logon
$user.AccountDisabled = $False

# Save the user to the directory
$user.SetInfo()
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        // Bind to the parent container
        IADsContainer parent = (IADsContainer)admService.OpenObject(
            "Adaxes://CN=Users,DC=company,DC=com", null, null, 0);
            
        // Create a new user object
        IADs user = (IADs)parent.Create("user", "CN=John Smith");

        // Set object properties
        user.Put("givenName", "John"); // First Name
        user.Put("sn", "Smith"); // Last Name
        user.Put("sAMAccountName", "jsmith"); // User Logon Name (pre-Windows 2000)
        user.Put("unicodePwd", "secret"); // Password
        user.Put("pwdLastSet", 0); // Must Change Password at First Logon
        ((IADsUser)user).AccountDisabled = false;

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

See also: Creating Groups, Creating Computer Accounts, Creating Organizational Units.

Deleting Objects

To delete a directory object, you need to bind to the object and call the DeleteObject method of the IADsDeleteOps interface. The IADsDeleteOps interface is supported by all directory objects.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)

$user.DeleteObject("ADM_DELETEOBJECTFLAGS_AUTO")
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.Utils;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADsDeleteOps user = (IADsDeleteOps)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", null, null, 0);
        
        user.DeleteObject(
            ADM_DELETEOBJECTFLAGS_ENUM.ADM_DELETEOBJECTFLAGS_AUTO);
    }
}

Copying Objects

To copy a directory object, first you need to bind to the target Organizational Unit or container where you want the copied object to be placed. All containers and Organizational Units support the IADsContainer interface. To copy a directory object, you need to call the CopyHere method of the IADsContainer interface. The first parameter of the method is the ADS path of the object to be copied. The second parameter is the relative distinguished name (RDN) of the new directory object.

The following example shows how to create a new user by copying an existing user account.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

# Bind to the target container
$targetContainer = $admService.OpenObject("Adaxes://CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)

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

# Update some properties
$user.Put("givenName", "Ann") # First Name
$user.Put("sn", "Jones") # Last Name
$user.Put("sAMAccountName", "ajones") # User Logon Name (pre-Windows 2000)
$user.Put("unicodePwd", "secret") # Password
$user.Put("pwdLastSet", 0); # Must Change Password at First Logon

# Save the user to the directory
$user.SetInfo()
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        // Bind to the target container
        IADsContainer targetContainer = (IADsContainer)admService.OpenObject(
            "Adaxes://CN=Users,DC=company,DC=com", 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=company,DC=com";
        const string newUserRdn = "CN=Ann Jones";
        IADs user = (IADs)targetContainer.CopyHere(sourceUserPath, newUserRdn);

        // Update some properties
        user.Put("givenName", "Ann"); // First Name
        user.Put("sn", "Jones"); // Last Name
        user.Put("sAMAccountName", "ajones"); // User Logon Name (pre-Windows 2000)
        user.Put("unicodePwd", "secret"); // Password
        user.Put("pwdLastSet", 0); // Must Change Password at First Logon

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

See also: Copying Groups

Moving Objects

To move a directory object from one location in the directory tree to another, first you need to bind to the container or Organizational Unit where you want to move the object. All containers and Organizational Units support the IADsContainer interface. To move a directory object, you need to call the MoveHere method of the IADsContainer interface. The first parameter of the method is the ADS path of the object to be moved.

The following example shows how to move a user from one Organizational Unit to another.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

# Bind to the target Organizational Unit
$targetOU = $admService.OpenObject("Adaxes://CN=TargetOU,DC=company,DC=com",`
    $NULL, $NULL, 0)

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

        // Bind to the target Organizational Unit
        IADsContainer targetOU = (IADsContainer)admService.OpenObject(
            "Adaxes://CN=TargetOU,DC=company,DC=com", 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);
    }
}

Renaming Objects

To rename a directory object, you need to modify the name property of the object:

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$user = $admService.OpenObject("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com",`
    $NULL, $NULL, 0)

$user.Put("name", "SMITH, John")
$user.SetInfo()
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");
        
        IADs user = (IADs)admService.OpenObject(
            "Adaxes://CN=John Smith,CN=Users,DC=company,DC=com", null, null, 0);
        
        user.Put("name", "SMITH, John");
        user.SetInfo();
    }
}

Enumerating Child Objects

To obtain a list of directory objects located in a container (or Organizational Unit), first you need to bind to the container. All containers and Organizational Units support the IEnumVARIANT interface that can be used to enumerate child objects. If you want to enumerate only child objects of specific types, you can use the IADsContainer::Filter property.

The following example shows how to enumerate all users and groups in an Organizational Unit.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$container = $admService.OpenObject(
    "Adaxes://OU=Sales,DC=company,DC=com", $NULL, $NULL, 0)

$container.Filter = @("user", "group")

foreach ($child in $container)
{
    Write-Host $child.ADsPath
}
using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IADsContainer container = (IADsContainer)admService.OpenObject(
            "Adaxes://OU=Sales,DC=company,DC=com", null, null, 0);

        container.Filter = new Object[] {"user", "group"};

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

See also: Enumerating Computer Accounts, Enumerating Child Objects.

Searching for Objects

Using Adaxes ADSI Provider, you can search for Active Directory objects and Adaxes-specific objects, such as Security Roles, Business Rules, and Scheduled Tasks. To perform a query in the directory, first you need to bind to the directory object under which you want to search. All directory objects support the IAdmDirectorySearcher interface. Using the IAdmDirectorySearcher::SearchFilter property, you can provide the LDAP search filter that defines the search criteria. The IAdmDirectorySearcher::SearchScope property specifies the scope of the search.

To start searching, you need to call the IAdmDirectorySearcher::ExecuteSearch method that returns the IAdmSearchResultIterator interface. To fetch all search results, call IAdmSearchResultIterator::FetchAll. Each search result is represented by the IAdmSearchResult interface.

The following example shows how to search for all users from the Sales department in the Organizational Unit called People.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$searcher = $admService.OpenObject(
    "Adaxes://OU=People,DC=company,DC=com", $NULL, $NULL, 0)

$searcher.SearchFilter = "(&(objectCategory=person)(objectClass=user)(department=Sales))"
$searcher.SearchScope = "ADS_SCOPE_SUBTREE"
try
{
    $results = $searcher.ExecuteSearch()
    foreach ($result in $results.FetchAll())
    {
        Write-Host $result.ADsPath
    }
}
finally
{
    $results.Dispose()
}
using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IAdmDirectorySearcher searcher = (IAdmDirectorySearcher)admService.OpenObject(
            "Adaxes://OU=People,DC=company,DC=com", null, null, 0);

        searcher.SearchFilter = "(&(objectCategory=person)(objectClass=user)(department=Sales)";
        searcher.SearchScope = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;

        using (IAdmSearchResultIterator results = searcher.ExecuteSearch())
        {
            foreach (IAdmSearchResult result in results.FetchAll())
            {
                Console.WriteLine(result.AdsPath);
            }
        }
    }
}

See also: Searching User Accounts, Searching Groups, Searching Computers, Searching Organizational Units.

Adding and Removing Group Members

To add or remove members from a group, first you need to bind to the group. Each group object supports the IADsGroup interface. To add an object to a group, call the IADsGroup::Add method; to remove an object from a group, call IADsGroup::Remove. Both methods take the ADS path of the directory object to be added or removed from the group.

The following example adds John Smith and removes Ann Wilson from a group.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$group = $admService.OpenObject(
    "Adaxes://CN=My Group,DC=company,DC=com", $NULL, $NULL, 0)

$group.Add("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com")
$group.Remove("Adaxes://CN=Ann Wilson,CN=Users,DC=company,DC=com")
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IADsGroup group = (IADsGroup)admService.OpenObject(
            "Adaxes://CN=My Group,DC=company,DC=com", null, null, 0);
            
        group.Add("Adaxes://CN=John Smith,CN=Users,DC=company,DC=com");
        group.Remove("Adaxes://CN=Ann Wilson,CN=Users,DC=company,DC=com");
    }
}

See also: Getting Group Members, Finding Groups in Which a User is a Member.

Getting Operation Execution Log

When performing operations on directory objects, Adaxes may execute additional actions. For example, you may have a Business Rule that automatically creates an Exchange mailbox and home folder for newly created users.

The information about additional actions is recorded in the Execution Log of an operation. To get the Execution Log of the last operation performed on a directory object, you can use the IAdmLastOperationOps interface. The IAdmLastOperationOps interface is supported by all directory objects. The GetLastOperationInfo method of the interface returns the IAdmOperationInfo interface. To get the operation Execution Log, you can use the IAdmOperationInfo::ExecutionLog property. The Execution Log is represented by the IAdmExecutionLogEntryCollection interface. Execution Log records are represented by the IAdmExecutionLogEntry interface.

The following example outputs the Execution Log of a user creation operation.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$parent = $admService.OpenObject("Adaxes://CN=Users,DC=company,DC=com",
    $NULL, $NULL, 0)
$user = $parent.Create("user", "CN=John Smith")
$user.Put("sAMAccountName", "jsmith")
$user.SetInfo()

$operationInfo = $user.GetLastOperationInfo()
$executionLog = $operationInfo.ExecutionLog

Write-Host $executionLog.ToString()
using System;
using Interop;
using Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        IADsContainer parent = (IADsContainer)admService.OpenObject(
            "Adaxes://CN=Users,DC=company,DC=com", null, null, 0);
            
        IADs user = (IADs)parent.Create("user", "CN=John Smith");
        user.Put("sAMAccountName", "jsmith");
        user.SetInfo();

        IAdmOperationInfo operationInfo =
            ((IAdmLastOperationOps)user).GetLastOperationInfo();
        IAdmExecutionLogEntryCollection executionLog = operationInfo.ExecutionLog;

      Console.Write(executionLog.ToString());
    }
}

See Also