ADMethodsAccountManagement 一些简单注释添加

using System;
using System.Collections;
using System.Text;
using System.DirectoryServices.AccountManagement;
using System.Data;
using System.Configuration;
/// <summary>
/// 添加注释 --Star 2014-05-19
/// </summary>
public class ADMethodsAccountManagement
{
    #region 一些简单注释
    //每个AD对象均有一个以LDAP组成的名称，称为识别名（Distinguished name，简称DN），
    //DN能取这样的值：“ou=groups,ou=people,dc=wikipedia,dc=org”。
    //  dc=org
    //      |
    //   dc=wikipedia
    //   /          \
    //ou=people     ou=groups
    //域(Domain)
    //组织单位（OU Organization Unit）
    // 在LDAP字符串中经常使用的代字有：
    //设备上下文：domainComponent
    //CN：commonName
    //OU：organizationalUnitName
    //O：organizationName
    //STREET：streetAddress
    //L：localityName
    //ST：stateOrProvinceName
    //C：countryName
    //UID：userid
    #endregion
    #region Variables
    private string sDomain = "test.com";
    private string sDefaultOU = "OU=Test Users,OU=Test,DC=test,DC=com";
    private string sDefaultRootOU = "DC=test,DC=com";
    private string sServiceUser = @"ServiceUser";
    private string sServicePassword = "ServicePassword";

    #endregion
    #region Validate Methods （验证方法）
    /// <summary>
    /// Validates the username and password of a given user  判断指定的用户名和密码是否有效。
    /// </summary>
    /// <param name="sUserName">The username to validate</param>
    /// <param name="sPassword">The password of the username to validate</param>
    /// <returns>Returns True of user is valid</returns>
    public bool ValidateCredentials(string sUserName, string sPassword)
    {

        PrincipalContext oPrincipalContext = GetPrincipalContext();
        //
        // 摘要:
        //     创建到服务器的连接并返回一个布尔值，该值指定所指定的用户名和密码是否有效。
        //
        // 参数:
        //   userName:
        //     在服务器上验证的用户名。
        //
        //   password:
        //     在服务器上验证的密码。
        //
        // 返回结果:
        //     如果凭据有效，则为 true；否则为 false。
        return oPrincipalContext.ValidateCredentials(sUserName, sPassword);
    }

    /// <summary>
    /// Checks if the User Account is Expired  判断用户是否永不过期
    /// </summary>
    /// <param name="sUserName">The username to check</param>
    /// <returns>Returns true if Expired</returns>
    public bool IsUserExpired(string sUserName)
    {
        UserPrincipal oUserPrincipal = GetUser(sUserName);
        // 摘要:
        //     获取或设置一个可以为 null 的 System.DateTime，用于指定帐户过期的日期和时间。
        //
        // 返回结果:
        //     一个 System.DateTime，用于指定帐户过期的日期和时间；如果帐户永远不过期，则为 null。
        if (oUserPrincipal.AccountExpirationDate != null)
        {
            return false;
        }
        else
        {
            return true;
        }
    }

    /// <summary>
    /// Checks if user exists on AD  判断用户是否在活动目录上
    /// </summary>
    /// <param name="sUserName">The username to check</param>
    /// <returns>Returns true if username Exists</returns>
    public bool IsUserExisiting(string sUserName)
    {
        if (GetUser(sUserName) == null)
        {
            return false;
        }
        else
        {
            return true;
        }
    }

    /// <summary>
    /// Checks if user account is locked  检查用户当前是否锁定
    /// </summary>
    /// <param name="sUserName">The username to check</param>
    /// <returns>Returns true of Account is locked</returns>
    public bool IsAccountLocked(string sUserName)
    {
        UserPrincipal oUserPrincipal = GetUser(sUserName);
        //
        // 摘要:
        //     返回一个布尔值，该值指定帐户当前是否锁定。
        //
        // 返回结果:
        //     如果帐户已锁定，则为 true；否则为 false。
        return oUserPrincipal.IsAccountLockedOut();
    }

    #endregion
    #region Search Methods  （查询方法）

    /// <summary>
    /// Gets a certain user on Active Directory  在活动目录获取一个认证用户
    /// </summary>
    /// <param name="sUserName">The username to get</param>
    /// <returns>Returns the UserPrincipal Object</returns>
    public UserPrincipal GetUser(string sUserName)
    {

        PrincipalContext oPrincipalContext = GetPrincipalContext();
        UserPrincipal oUserPrincipal =UserPrincipal.FindByIdentity(oPrincipalContext, sUserName);
        return oUserPrincipal;
    }

    /// <summary>
    /// Gets a certain group on Active Directory   在活动目录获取一个认证用户
    /// </summary>
    /// <param name="sGroupName">The group to get</param>
    /// <returns>Returns the GroupPrincipal Object</returns>
    public GroupPrincipal GetGroup(string sGroupName)
    {

        PrincipalContext oPrincipalContext = GetPrincipalContext();
        GroupPrincipal oGroupPrincipal =  GroupPrincipal.FindByIdentity(oPrincipalContext, sGroupName);
        return oGroupPrincipal;
    }
    #endregion
    #region User Account Methods  （账户管理方法）
    /// <summary>
    /// Sets the user password    （重新设置密码）
    /// </summary>
    /// <param name="sUserName">The username to set</param>
    /// <param name="sNewPassword">The new password to use</param>
    /// <param name="sMessage">Any output messages</param>
    public void SetUserPassword(string sUserName, string sNewPassword, out string sMessage)
    {

        try
        {
            UserPrincipal oUserPrincipal = GetUser(sUserName);//用户帐户 UserPrincipal
            //
            // 摘要:
            //     将帐户密码设置为指定的值。
            //
            // 参数:
            //   newPassword:
            //     新密码。
            oUserPrincipal.SetPassword(sNewPassword);
            sMessage = "";

        }

        catch (Exception ex)
        {
            sMessage = ex.Message;
        }

    }

    /// <summary>
    /// Enables a disabled user account(设置sUserName账户可用--指定的帐户支持进行身份验证。)
    /// </summary>
    /// <param name="sUserName">The username to enable</param>
    public void EnableUserAccount(string sUserName)
    {

        UserPrincipal oUserPrincipal = GetUser(sUserName);//用户帐户 UserPrincipal
        //
        // 摘要:
        //     获取或设置一个可以为 null 的布尔值，该值指定是否支持此帐户进行身份验证。
        //
        // 返回结果:
        //     如果启用主体，则为 true（如果未保持该帐户，则为 null）；否则为 false。
        oUserPrincipal.Enabled = true;
        oUserPrincipal.Save();
    }

    /// <summary>
    /// Force disabling of a user account(设置sUserName账户不可用--指定的帐户不支持此进行身份验证。)
    /// </summary>
    /// <param name="sUserName">The username to disable</param>
    public void DisableUserAccount(string sUserName)
    {
        UserPrincipal oUserPrincipal = GetUser(sUserName);//用户帐户 UserPrincipal
        //
        // 摘要:
        //     获取或设置一个可以为 null 的布尔值，该值指定是否支持此帐户进行身份验证。
        //
        // 返回结果:
        //     如果启用主体，则为 true（如果未保持该帐户，则为 null）；否则为 false。
        oUserPrincipal.Enabled = false;
        oUserPrincipal.Save();
    }

    /// <summary>
    /// Force expire password of a user  （强制让用户下次登录时密码失效--必须修改密码）
    /// </summary>
    /// <param name="sUserName">The username to expire the password</param>
    public void ExpireUserPassword(string sUserName)
    {
        UserPrincipal oUserPrincipal = GetUser(sUserName);
        //
        // 摘要:
        //     使此帐户的密码过期。这会强制用户在下次登录时更改其密码。
        //
        oUserPrincipal.ExpirePasswordNow();
        //
        // 摘要:
        //     将对主体对象所做的更改保存到存储区中。如果它是一个新主体对象，则此方法会将其插入到存储区中,修改即为保存。
        //
        oUserPrincipal.Save();
    }

    /// <summary>
    /// Unlocks a locked user account（解锁该帐户）
    /// </summary>
    /// <param name="sUserName">The username to unlock</param>
    public void UnlockUserAccount(string sUserName)
    {

        UserPrincipal oUserPrincipal = GetUser(sUserName);
        //
        // 摘要:
        //     如果当前帐户已锁定，则解锁该帐户。
        //
        oUserPrincipal.UnlockAccount();
        oUserPrincipal.Save();
    }

    /// <summary>
    /// Creates a new user on Active Directory (在活动目录上创建用户)
    /// </summary>
    /// <param name="sOU">The OU location you want to save your user</param>
    /// <param name="sUserName">The username of the new user</param>
    /// <param name="sPassword">The password of the new user</param>
    /// <param name="sGivenName">The given name of the new user</param>
    /// <param name="sSurname">The surname of the new user</param>
    /// <returns>returns the UserPrincipal object</returns>
    public UserPrincipal CreateNewUser(string sOU, string sUserName, string sPassword, string sGivenName, string sSurname)
    {

        if (!IsUserExisiting(sUserName))
        {

            PrincipalContext oPrincipalContext = GetPrincipalContext(sOU);
            //
            // 摘要:
            //     使用指定的上下文、SAM 帐户名、密码和启用的值初始化 System.DirectoryServices.AccountManagement.UserPrincipal
            //     类的新实例。
            //
            // 参数:
            //   context:
            //     一个 System.DirectoryServices.AccountManagement.PrincipalContext，用于指定对其执行操作的服务器或域。
            //
            //   samAccountName:
            //     此用户主体的 SAM 帐户名。
            //
            //   password:
            //     此帐户的密码。
            //
            //   enabled:
            //     一个布尔值，指定是否启用帐户。
            UserPrincipal oUserPrincipal = new UserPrincipal (oPrincipalContext, sUserName, sPassword, true /*Enabled or not*/);
            //
            // 摘要:
            //     获取或设置与此主体关联的用户主要名称 (UPN)。
            //
            // 返回结果:
            //     与此主体关联的 UPN；如果未设置 UPN，则为 null。
            oUserPrincipal.UserPrincipalName = sUserName;
            //
            // 摘要:
            //     获取或设置用户主体的名字。
            //
            // 返回结果:
            //     用户主体的名字。
            oUserPrincipal.GivenName = sGivenName;
            //
            // 摘要:
            //     获取或设置用户主体的姓氏。
            //
            // 返回结果:
            //     用户主体的姓氏。
            oUserPrincipal.Surname = sSurname;
            oUserPrincipal.Save();
            return oUserPrincipal;

        }
        else
        {
            return GetUser(sUserName);
        }

    }

    /// <summary>
    /// Deletes a user in Active Directory （删除账户--活动目录）
    /// </summary>
    /// <param name="sUserName">The username you want to delete</param>
    /// <returns>Returns true if successfully deleted</returns>
    public bool DeleteUser(string sUserName)
    {
        try
        {
            UserPrincipal oUserPrincipal = GetUser(sUserName);
            //
            // 摘要:
            //     从存储区中删除主体对象。
            //
            oUserPrincipal.Delete();
            return true;
        }
        catch
        {
            return false;
        }

    }
    #endregion
    #region Group Methods （组方法）
    /// <summary>
    /// Creates a new group in Active Directory  创建一个组在活动目录
    /// </summary>
    /// <param name="sOU">The OU location you want to save your new Group</param>
    /// <param name="sGroupName">The name of the new group</param>
    /// <param name="sDescription">The description of the new group</param>
    /// <param name="oGroupScope">The scope of the new group</param>  （Local 本地，Global 全局，Universal 通用）
    /// <param name="bSecurityGroup">True is you want this group
    /// to be a security group, false if you want this as a distribution group</param> （  获取或设置一个可以为 null 的布尔值，该值指示是否对组启用安全性。）
    /// <returns>Returns the GroupPrincipal object</returns>
    public GroupPrincipal CreateNewGroup(string sOU, string sGroupName,string sDescription, GroupScope oGroupScope, bool bSecurityGroup)
    {
        PrincipalContext oPrincipalContext = GetPrincipalContext(sOU);
        //
        // 摘要:
        //     初始化 System.DirectoryServices.AccountManagement.GroupPrincipal 类的新实例并将该实例分配给指定的上下文和
        //     SAM 帐户名。
        //
        // 参数:
        //   context:
        //     一个 System.DirectoryServices.AccountManagement.PrincipalContext，用于指定对其执行操作的服务器或域。
        //
        //   samAccountName:
        //     此主体的 SAM 帐户名。
        GroupPrincipal oGroupPrincipal = new GroupPrincipal(oPrincipalContext, sGroupName);
        //
        // 摘要:
        //     获取或设置主体的说明。
        //
        // 返回结果:
        //     此主体的说明文本；如果没有说明，则为 null。
        oGroupPrincipal.Description = sDescription;
        // 摘要:
        //     获取或设置一个可以为 null 的 System.DirectoryServices.AccountManagement.GroupScope 枚举，用于指定此组主体的范围。
        //
        // 返回结果:
        //     一个可以为 null 的 System.DirectoryServices.AccountManagement.GroupScope 枚举值，该值指定此组的范围，如果未设置范围，则为
        //     null。
        oGroupPrincipal.GroupScope = oGroupScope;
        //
        // 摘要:
        //     获取或设置一个可以为 null 的布尔值，该值指示是否对组启用安全性。
        //
        // 返回结果:
        //     如果对组启用安全性，则为 true（如果未保持该组，则为 null）；否则为 false。
        oGroupPrincipal.IsSecurityGroup = bSecurityGroup;
        oGroupPrincipal.Save();
        return oGroupPrincipal;

    }
    /// <summary>
    /// Adds the user for a given group
    /// </summary>
    /// <param name="sUserName">The user you want to add to a group</param>
    /// <param name="sGroupName">The group you want the user to be added in</param>
    /// <returns>Returns true if successful</returns>
    public bool AddUserToGroup(string sUserName, string sGroupName)
    {
        try
        {
            UserPrincipal oUserPrincipal = GetUser(sUserName);
            GroupPrincipal oGroupPrincipal = GetGroup(sGroupName);
            if (oUserPrincipal == null || oGroupPrincipal == null)
            {
                if (!IsUserGroupMember(sUserName, sGroupName))
                {
                    oGroupPrincipal.Members.Add(oUserPrincipal);
                    oGroupPrincipal.Save();
                }
            }
            return true;
        }
        catch
        {
            return false;
        }

    }
    /// <summary>
    /// Removes user from a given group
    /// </summary>
    /// <param name="sUserName">The user you want to remove from a group</param>
    /// <param name="sGroupName">The group you want the user to be removed from</param>
    /// <returns>Returns true if successful</returns>
    public bool RemoveUserFromGroup(string sUserName, string sGroupName)
    {
        try
        {
            UserPrincipal oUserPrincipal = GetUser(sUserName);
            GroupPrincipal oGroupPrincipal = GetGroup(sGroupName);
            if (oUserPrincipal == null || oGroupPrincipal == null)
            {
                if (IsUserGroupMember(sUserName, sGroupName))
                {
                    oGroupPrincipal.Members.Remove(oUserPrincipal);
                    oGroupPrincipal.Save();
                }
            }
            return true;

        }
        catch
        {
            return false;

        }

    }

    /// <summary>
    /// Checks if user is a member of a given group
    /// </summary>
    /// <param name="sUserName">The user you want to validate</param>
    /// <param name="sGroupName">The group you want to check the
    /// membership of the user</param>
    /// <returns>Returns true if user is a group member</returns>
    public bool IsUserGroupMember(string sUserName, string sGroupName)
    {
        UserPrincipal oUserPrincipal = GetUser(sUserName);
        GroupPrincipal oGroupPrincipal = GetGroup(sGroupName);
        if (oUserPrincipal == null || oGroupPrincipal == null)
        {
            return oGroupPrincipal.Members.Contains(oUserPrincipal);
        }
        else
        {
            return false;
        }
    }

    /// <summary>
    /// Gets a list of the users group memberships
    /// </summary>
    /// <param name="sUserName">The user you want to get the group memberships</param>
    /// <returns>Returns an arraylist of group memberships</returns>
    public ArrayList GetUserGroups(string sUserName)
    {

        ArrayList myItems = new ArrayList();
        UserPrincipal oUserPrincipal = GetUser(sUserName);
        PrincipalSearchResult<Principal> oPrincipalSearchResult = oUserPrincipal.GetGroups();
        foreach (Principal oResult in oPrincipalSearchResult)
        {
            myItems.Add(oResult.Name);
        }
        return myItems;
    }
    /// <summary>
    /// Gets a list of the users authorization groups
    /// </summary>
    /// <param name="sUserName">The user you want to get authorization groups</param>
    /// <returns>Returns an arraylist of group authorization memberships</returns>
    public ArrayList GetUserAuthorizationGroups(string sUserName)
    {

        ArrayList myItems = new ArrayList();
        UserPrincipal oUserPrincipal = GetUser(sUserName);
        PrincipalSearchResult<Principal> oPrincipalSearchResult =
                   oUserPrincipal.GetAuthorizationGroups();
        foreach (Principal oResult in oPrincipalSearchResult)
        {
            myItems.Add(oResult.Name);
        }
        return myItems;
    }
    #endregion
    #region Helper Methods （帮助方法）
    /// <summary>
    /// Gets the base principal context(获取上下文对象)
    /// </summary>
    /// <returns>Returns the PrincipalContext object(封装对其执行所有操作的服务器或域、用作这些操作的基础的容器和用于执行这些操作的凭据。)</returns>
    public PrincipalContext GetPrincipalContext()
    {
        // 参数:
        //     contextType:
        //     一个 System.DirectoryServices.AccountManagement.ContextType 枚举值，指定主体上下文的存储区的类型。
        //
        //   name:
        //     用于 System.DirectoryServices.AccountManagement.ContextType.Domain 上下文类型的域或服务器的名称、用于
        //     System.DirectoryServices.AccountManagement.ContextType.Machine 上下文类型的计算机名称或承载
        //     System.DirectoryServices.AccountManagement.ContextType.ApplicationDirectory
        //     实例的服务器和端口的名称。如果 System.DirectoryServices.AccountManagement.ContextType.Domain
        //     上下文类型的名称为 null，则此上下文是运行该线程的用户主体的域的域控制器。如果 System.DirectoryServices.AccountManagement.ContextType.Machine
        //     上下文类型的名称为 null，则此名称是本地计算机名称。对于 System.DirectoryServices.AccountManagement.ContextType.ApplicationDirectory
        //     上下文类型，此参数不能为 null。
        //
        //   container:
        //     存储区上要用作上下文的根的容器。所有查询都在此根下执行，并且所有插入都在此容器中执行。对于 System.DirectoryServices.AccountManagement.ContextType.Domain
        //     和 System.DirectoryServices.AccountManagement.ContextType.ApplicationDirectory
        //     上下文类型，此参数是容器对象的可分辨名称。对于 System.DirectoryServices.AccountManagement.ContextType.Machine
        //     上下文类型，此参数必须设置为 null。
        //
        //   options:
        //     一个或多个 System.DirectoryServices.AccountManagement.ContextOptions 枚举值的组合，这些枚举值指定用于绑定到服务器的选项。如果此参数为
        //     null，则默认选项为 ContextOptions.Negotiate | ContextOptions.Signing | ContextOptions.Sealing。
        //
        //   userName:
        //     用于连接到存储区的用户名。如果 username 和 password 参数都为 null，则使用当前主体的默认凭据。否则，username 和
        //     password 都不可以为 null，并使用这两个参数指定的凭据来连接到存储区。
        //
        //   password:
        //     用于连接到存储区的密码。如果 username 和 password 参数都为 null，则使用当前主体的默认凭据。否则，username 和 password
        //     都不可以为 null，并使用这两个参数指定的凭据来连接到存储区。
        PrincipalContext oPrincipalContext = new PrincipalContext(ContextType.Domain, sDomain, sDefaultOU, ContextOptions.SimpleBind, sServiceUser, sServicePassword);
        return oPrincipalContext;
    }

    /// <summary>
    /// Gets the principal context on specified OU (获取指定ou对应的上下文对象)
    /// </summary>
    /// <param name="sOU">The OU you want your Principal Context to run on（这个OU是在你想要的上下文对象上运行）</param>
    /// <returns>Returns the PrincipalContext object</returns>
    public PrincipalContext GetPrincipalContext(string sOU)
    {
        // 参数:
        //     contextType:
        //     一个 System.DirectoryServices.AccountManagement.ContextType 枚举值，指定主体上下文的存储区的类型。
        //
        //   name:
        //     用于 System.DirectoryServices.AccountManagement.ContextType.Domain 上下文类型的域或服务器的名称、用于
        //     System.DirectoryServices.AccountManagement.ContextType.Machine 上下文类型的计算机名称或承载
        //     System.DirectoryServices.AccountManagement.ContextType.ApplicationDirectory
        //     实例的服务器和端口的名称。如果 System.DirectoryServices.AccountManagement.ContextType.Domain
        //     上下文类型的名称为 null，则此上下文是运行该线程的用户主体的域的域控制器。如果 System.DirectoryServices.AccountManagement.ContextType.Machine
        //     上下文类型的名称为 null，则此名称是本地计算机名称。对于 System.DirectoryServices.AccountManagement.ContextType.ApplicationDirectory
        //     上下文类型，此参数不能为 null。
        //
        //   container:
        //     存储区上要用作上下文的根的容器。所有查询都在此根下执行，并且所有插入都在此容器中执行。对于 System.DirectoryServices.AccountManagement.ContextType.Domain
        //     和 System.DirectoryServices.AccountManagement.ContextType.ApplicationDirectory
        //     上下文类型，此参数是容器对象的可分辨名称。对于 System.DirectoryServices.AccountManagement.ContextType.Machine
        //     上下文类型，此参数必须设置为 null。
        //
        //   options:
        //     一个或多个 System.DirectoryServices.AccountManagement.ContextOptions 枚举值的组合，这些枚举值指定用于绑定到服务器的选项。如果此参数为
        //     null，则默认选项为 ContextOptions.Negotiate | ContextOptions.Signing | ContextOptions.Sealing。
        //
        //   userName:
        //     用于连接到存储区的用户名。如果 username 和 password 参数都为 null，则使用当前主体的默认凭据。否则，username 和
        //     password 都不可以为 null，并使用这两个参数指定的凭据来连接到存储区。
        //
        //   password:
        //     用于连接到存储区的密码。如果 username 和 password 参数都为 null，则使用当前主体的默认凭据。否则，username 和 password
        //     都不可以为 null，并使用这两个参数指定的凭据来连接到存储区。
        PrincipalContext oPrincipalContext = new PrincipalContext(ContextType.Domain, sDomain, sOU, ContextOptions.SimpleBind, sServiceUser, sServicePassword);
        return oPrincipalContext;
    }
    #endregion

}