Active Directory Service Interface

activeds.dll 中封裝了幾個 ADSI 中最核心的介面：

• IADs：作為所有 Active Directory 物件最頂層的介面，擁有最基礎的功能，
• IADsContainer：作為所有可收納 Active Directory 物件的收納器 (Container) 最頂層的介面，具有收納器的基礎功能。
• IADsOpenDSObject：連接 Active Directory 之用（它只有 OpenDSObject() 一個方法），同時它會快取住用來連接的安全資訊內容。
• IADsNamespace：由目錄服務提供者 (directory service provider) 提供，用來識別目錄結構的命名空間之用。

activeds.dll 亦提供了幾個依物件不同而實作的介面，像是：

• IADsComputer：提供目錄服務中的電腦 (computer) 物件。
• IADsDomain：提供目錄服務中的網域 (domain) 物件。
• IADsUser：提供目錄服務中的使用者 (user) 物件。
• IADsGroup：提供目錄服務中的使用者群組 (group) 物件。
• IADsOU：提供目錄服務中的組織單元 (organization unit) 物件。
• IADsCollection：提供目錄服務物件集合。

在使用 ADSI 之時，有時會需要一些工具型功能，像是 DOMAIN\user 和 User Principal Name 間的轉換，或是取得系統資訊等，ADSI 也提供了這類的介面：

• IADsNameTranslate：在目錄服務中在不同的名稱間轉換。
• IADsWinNTSystemInfo：在目錄服務中取得 Windows NT Directory Service 系統資訊。
• IADsADSystemInfo：在目錄服務中取得 LDAP Directory Service 系統資訊。
• IADsPathname：剖析 X.500 名稱與路徑。

這些介面多是使用 C/C++ 程式語言來存取，若是使用 VB 或是 Scripting Language 時，則可以使用另外的方法來存取。

' Get user object from Active Directory.
Dim mach As IADsContainer
Dim usr as IADsUser

On Error GoTo Cleanup
Set mach = GetObject("WinNT://MyMachine,Computer")
Set usr = mach.Create("user","jeffsmith")
usr.SetInfo

Cleanup:
    If(Err.Number<>0) Then
        MsgBox("An error has occurred. " & Err.Number)
    End If
    Set mach = Nothing
    Set usr = Nothing

// binding Active Directory using C++ and native interface.
IADs *pObject;
HRESULT hr;

// Initialize COM.
CoInitialize(NULL);

hr = ADsGetObject(L"LDAP://CN=jeffsmith,DC=fabrikam,DC=com", 
        IID_IADs,
        (void**) &pObject);
if(SUCCEEDED(hr))
{
    // Use the object.

    // Release the object.
    pObject->Release()
}

// Uninitialize COM.
CoUninitialize();

ADSI 除了介面以外，也將部份功能使用函式方式顯露，以簡化呼叫原生介面需要處理的工作，較重要且經常被使用的有：

• ADsOpenDSObject()，封裝取得 IADs 或 IADsContainer 等物件的工作。
• ADsGetObject()，封裝利用已開啟的 Active Directory Session 取得物件的工作。
• ADsGetLastError()，取得在 ADSI 作業中，最後一個引發的錯誤。
• AllocADsMem(), FreeADsMem(), AllocADsStr(), FreeADsStr()，配置與釋放 ADSI 使用的資源。
• ADsBuildEnumerator(), ADsEnumerateNext(), ADsFreeEnumerator()：處理 ADSI 物件的列舉工作。

下列的例子，是使用 ADsOpenDSObject() 取得 IADs 物件的範例程式碼：

IADs *pObject;
LPWSTR szUsername = NULL;
LPWSTR szPassword = NULL
HRESULT hr;

// Insert code to securely retrieve the username and password.

hr = ADsOpenObject(L"LDAP://CN=Jeff,DC=Fabrikam,DC=com",
                   "jeffsmith",
                   "etercespot",
                   ADS_SECURE_AUTHENTICATION, 
                   IID_IADs,
                   (void**) &pObject);

在 .NET Framework 中，另外提供了一個 .NET 專用的 ADSI 介面程式庫 System.DirectoryService.dll，程式開發人員可以加入此程式庫的參考來取得 ADSI 的功能，在這個原生類別庫中，封裝了兩個類別，作為存取 Active Directory 的入口之用。

• DirectoryEntry：此類別封裝了 IADs 以及 IADsContainer 等原生介面，用來存取 Active Directory 的物件資料，以及 Schema 封裝的資訊等等。
• DirectorySearcher：此類別封裝了 IDirectorySearch 介面，作為搜尋 Active Directory 的主要工具，並使用 SearchResult 物件封裝搜尋結果，讓 .NET 開發人員可以簡化處理搜尋結果的工作。

截至 .NET Framework 3.5 為止，ADSI 在 Managed Class Library 中有四個命名空間：

• System.DirectoryServices：原生的 ADSI Managed 介面，封裝 DirectoryEntry 和 DirectorySearcher 與工具類別。
• System.DirectoryServices.AccountManagement：封裝對 IADsUser, IADsComputer, IADsGroup 等介面，簡化處理物件的工具。
• System.DirectoryServices.ActiveDirectory：封裝對 Active Directory 結構物件的工具。
• System.DirectoryServices.Protocol：封裝對 LDAP 協定與目錄服務通訊的工具與基礎類別。

下列為使用 C# 存取 DirectoryEntry 的範例程式碼：

DirectoryEntry ent = new DirectoryEntry();
DirectoryEntry ou = ent.Children.Find("OU=Consulting");

// Use the Add method to add a user to an organizational unit.
DirectoryEntry usr = ou.Children.Add("CN=New User","user");
// Set the samAccountName, then commit changes to the directory.
usr.Properties["samAccountName"].Value = "newuser"; 
usr.CommitChanges();