OracleMembershipProvider Class

The OracleMembershipProvider class enables ASP.NET developers to store Web site user account information in an Oracle database.

Class Inheritance

System.Object

  System.Configuration.Provider.ProviderBase

    System.Web.Security.MembershipProvider

      Oracle.Web.Security.OracleMembershipProvider

Declaration

// C#
public class OracleMembershipProvider: MembershipProvider

Thread Safety

All public static methods are thread-safe, although instance members are not guaranteed to be thread-safe.

Remarks

This class allows ASP.NET applications to store and manage user information in an Oracle database. Note that the term user in this chapter refers to an application or user, not a database user. Thus, the user information that this provider manages is application or user information, not database user information.

Example

The following code example shows a web.config file for an ASP.NET application configured to use OracleMembershipProvider as the default provider. This configuration uses the connection string and default attribute values specified in the machine.config file.

<?xml version="1.0"?>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <system.web>
    <membership defaultProvider="OracleMembershipProvider"/>
  </system.web>
</configuration>

The following is a web.config example for an ASP.NET application that uses an OracleMembershipProvider with customized settings and an application-specific connection string:

<?xml version="1.0"?>
<configuration xmlns=
  "http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <connectionStrings>
    <add name="my_membership_app_con_string" connectionString=
      "User Id=scott;Password=tiger;Data Source=Oracle"/>
  </connectionStrings>
  <system.web>
    <!-- Enable and customize OracleMembershipProvider settings -->
    <membership defaultProvider="MyOracleMembershipProvider">
      <providers>
        <add name="MyOracleMembershipProvider"
             type="Oracle.Web.Security.OracleMembershipProvider, 
             Oracle.Web, Version=2.112.2.0, Culture=neutral, 
             PublicKeyToken=89b483f429c47342"
             connectionStringName="my_membership_app_con_string"
             applicationName="my_membership_app"
             enablePasswordRetrieval="false"
             enablePasswordReset="true"
             requiresQuestionAndAnswer="true"
             requiresUniqueEmail="true"
             passwordFormat="Hashed"
             maxInvalidPasswordAttempts="4"
             minRequiredPasswordLength="9"
             passwordAttemptWindow="8"/>
      </providers>
    </membership>
  </system.web>
</configuration>

Note that the applicationName attribute should be set to a unique value for each ASP.NET application.

Requirements

Namespace: Oracle.Web.Security

Assembly: Oracle.Web.dll

Oracle Providers for ASP.NET Version: Oracle Providers for ASP.NET 2.0 and Oracle Providers for ASP.NET 4

---

OracleMembershipProvider Members

OracleMembershipProvider members are listed in the following tables.

OracleMembershipProvider Constructors

The OracleMembershipProvider constructor is listed in Table 2-1.

OracleMembershipProvider Static Methods

OracleMembershipProvider static methods are listed in Table 2-2.

OracleMembershipProvider Public Properties

OracleMembershipProvider public properties are listed in Table 2-3.

OracleMembershipProvider Public Methods

OracleMembershipProvider public methods are listed in Table 2-4.

OracleMembershipProvider Public Events

OracleMembershipProvider public event is listed in Table 2-5.

---

OracleMembershipProvider Constructors

This constructor instantiates a new instance of the OracleMembershipProvider class.

Overload List:

• OracleMembershipProvider()

  This constructor creates an instance of the OracleMembershipProvider class.

OracleMembershipProvider()

This constructor instantiates a new instance of the OracleMembershipProvider class.

Declaration

// C#
public OracleMembershipProvider();

Remarks

ASP.NET calls the OracleMembershipProvider constructor to create an instance of the OracleMembershipProvider class, as specified in the configuration for the application. Initialization values for the OracleMembershipProvider object are passed through the Initialize method.

This constructor is not intended to be used directly by the application.

---

OracleMembershipProvider Static Methods

OracleMembershipProvider static methods are listed in Table 2-6.

---

OracleMembershipProvider Public Properties

OracleMembershipProvider public properties are listed in Table 2-7.

ApplicationName

This property gets or sets the name of the application that is used to group user information.

Declaration

// C#
public override string ApplicationName{get; set;}

Property Value

The name of the application. If the applicationName attribute is not specified in the application configuration file, or if the value is an empty string, then this property is set to the application virtual path.

Exceptions

ArgumentException - The application name supplied is an empty string or a null reference.

ProviderException - The application name supplied exceeds 256 characters.

Remarks

The string value of the ApplicationName property is used for organizing user information. Multiple ASP.NET applications can use the same database and create duplicate user names because user information is stored uniquely for each application name. This property can be set programmatically, or it can be set declaratively in the Web application configuration file using the applicationName attribute. The attribute name in the configuration file is case-sensitive.

The ApplicationName property is not thread-safe. It is recommended that the programming code not allow users to set the ApplicationName property in Web applications.

CommandTimeout

This property gets the number of seconds that the command is allowed to execute before it is terminated with an exception.

Declaration

// C#
public int CommandTimeout {get;}
 

Property Value

An int.

Remarks

To customize a provider, ASP.NET developers can set an integer value for this property through the web.config file using the commandTimeout attribute.

The default value is 30 seconds. The attribute name in the configuration file is case-sensitive.

EnablePasswordReset

This property indicates whether or not the membership provider is configured to allow users to reset their passwords.

Declaration

// C#
public override bool EnablePasswordReset{get;}

Property Value

Returns true, if the membership provider supports password reset; otherwise, it returns false. The default is true.

Remarks

To customize the membership provider, ASP.NET developers can specify a Boolean value for this property through the web.config file using the enablePasswordReset attribute. The value indicates whether or not users can use the ResetPassword method to overwrite their current password with a new, randomly generated password. The attribute name in the configuration file is case-sensitive.

EnablePasswordRetrieval

This property indicates whether or not the membership provider is configured to allow users to retrieve their passwords.

Declaration

// C#
public override bool EnablePasswordRetrieval{get;}

Property Value

Returns true, if the membership provider is configured to support password retrieval; otherwise, returns false. The default is false.

Remarks

To customize a membership provider, ASP.NET developers can set a Boolean value for this property through the web.config file using the enablePasswordRetrieval attribute. The value indicates whether or not users can use the GetPassword method to retrieve their current password from the database. The attribute name in the configuration file is case-sensitive.

If the custom membership provider supports hashed passwords, then the GetPassword method returns an exception if the EnablePasswordRetrieval property is set to true and the password format is set to Hashed. In other words, hashed passwords cannot be retrieved.

MaxInvalidPasswordAttempts

This property gets the number of invalid password or password-answer attempts allowed before the user is locked out.

Declaration

// C#
public override int MaxInvalidPasswordAttempts{get;}

Property Value

The number of invalid password or password-answer attempts allowed before the user is locked out. The default number of attempts is 5.

Remarks

To customize a membership provider, ASP.NET developers can set an integer value for this property through the web.config file using the maxInvalidPasswordAttempts attribute. The attribute name in the configuration file is case-sensitive.

The MaxInvalidPasswordAttempts property works in conjunction with the PasswordAttemptWindow property. If the number of invalid passwords or password question entries is greater than or equal to the MaxInvalidPasswordAttempts property value within the PasswordAttemptWindow property value (in minutes), then the user is locked out until the user is unlocked by the UnlockUser method. If a valid password or password answer is supplied before the MaxInvalidPasswordAttempts value is reached, then the counter that tracks the number of invalid attempts is reset to zero.

Invalid passwords and password-answer attempts accumulate independently. For example, if the MaxInvalidPasswordAttempts property is set to 10, and 6 invalid password attempts are made followed by 3 invalid password-answer attempts, 4 more invalid password attempts or 7 more invalid password-answer attempts must be made within the PasswordAttemptWindow for the user to be locked out.

If the RequiresQuestionAndAnswer property is set to false, invalid password-answer attempts are not tracked.

Invalid password and password-answer attempts are tracked in the ValidateUser, ChangePassword, ChangePasswordQuestionAndAnswer, GetPassword, and ResetPassword methods.

MinRequiredNonAlphanumericCharacters

This property gets the minimum number of special characters that must be present in a valid password.

Declaration

// C#
public override int MinRequiredNonAlphanumericCharacters(get;}

Property Value

The minimum number of special characters that must be present in a valid password. The default value is 1.

Remarks

To customize a membership provider, ASP.NET developers can set an integer value for this property through the web.config file using the minRequiredNonalphanumericCharacters attribute. The attribute name in the configuration file is case-sensitive.

The MinRequiredNonAlphanumericCharacters property returns the minimum number of special, nonalphabetic characters that must be entered to create a valid password for the OracleMembershipProvider object.

MinRequiredPasswordLength

This property gets the minimum length required for a password.

Declaration

// C#
public override int MinRequiredPasswordLength{get;}

Property Value

The minimum length required for a password. The default value is 7.

Remarks

To customize a membership provider, ASP.NET developers can set an integer value for this property through the web.config file using the minRequiredPasswordLength attribute. The attribute name in the configuration file is case-sensitive.

The minRequiredPasswordLength property gets the minimum number of characters that must be entered to create a valid password for the OracleMembershipProvider object.

PasswordAttemptWindow

This property gets the number of minutes in which a maximum number of invalid password or password-answer attempts are allowed before the user is locked out.

Declaration

// C#
public override int PasswordAttemptWindow{get;}

Property Value

The number of minutes in which a maximum number of invalid password or password-answer attempts are allowed before the user is locked out. The default value is 10.

Remarks

To customize a membership provider, ASP.NET developers can set an integer value for this property through the web.config file using the passwordAttemptWindow attribute. The attribute name in the configuration file is case-sensitive.

The PasswordAttemptWindow property works in conjunction with the MaxInvalidPasswordAttempts property. If the number of invalid passwords or password question entries is greater than or equal to the MaxInvalidPasswordAttempts property value within the PasswordAttemptWindow property value (in minutes), then the user is locked out until the user is unlocked by the UnlockUser method. If a valid password or password answer is supplied before the MaxInvalidPasswordAttempts value is reached, then the counter that tracks the number of invalid attempts is reset to zero.

Invalid password and password-answer attempts accumulate independently. For example, if the MaxInvalidPasswordAttempts property is set to 10, and 6 invalid password attempts are made followed by 3 invalid password-answer attempts, 4 more invalid password attempts or 7 more invalid password-answer attempts must be made within the PasswordAttemptWindow value for the user to be locked out.

If the RequiresQuestionAndAnswer property is set to false, then invalid password-answer attempts are not tracked.

Invalid password and password-answer attempts are tracked in the ValidateUser, ChangePassword, ChangePasswordQuestionAndAnswer, GetPassword, and ResetPassword methods.

PasswordCompatMode

This property gets the password compatibility mode.

Declaration

// C#
public string PasswordCompatMode {get;}

Property Value

A string.

Remarks

The default value is Framework20. The other acceptable value is Framework40. The string value is case-sensitive.

To customize a provider, ASP.NET developers can set a string value for this property through the web.config file using the case-sensitive passwordCompatMode attribute.

When passwordFormat attribute is set to Hashed, the value of System.Web.Security.Membership.HashAlgorithmType property is used to hash password for a Membership user during the creation and validation of the user.

The value for HashAlgorithmType property can be set in the web.config file through the case-sensitive attribute hashAlgorithmType, as in the following example:

<membership defaultProvider="OracleMembershipProvider" hashAlgorithmType="SHA1"/>

If hashAlgorithmType attribute is not specified in the web.config file, SHA1 will be used. With .NET Framework 2.0, the other valid value for hashAlgorithmType is MD5.

With .NET Framework 4, if a new application that does not have existing Membership users and would like to use one of the other variants of SHA and HMACSHA hash algorithm types, the passwordCompatMode attribute must be set to Framework40 and the hashAlgorithmType attribute must be set to the desired type, such as SHA256, HMACSHA256, HMACSHA384, or HMACSHA512. Nevertheless, SHA1 and MD5 are still supported when passwordCompatMode is set to Framework40.

Example

The following is a web.config example that sets hashAlgorithmType to HMACSHA25 and passwordCompatMode to Framework40.

<!-- Enable and customize OracleMembershipProvider settings -->
<membership defaultProvider="MyOracleMembershipProvider" hashAlgorithmType="HMACSHA256">
             <providers>
    <add name="MyOracleMembershipProvider"
    type="Oracle.Web.Security.OracleMembershipProvider, Oracle.Web,
    Version=4.112.2.0, Culture=neutral, PublicKeyToken=89b483f429c47342"
    ConnectionStringName="my_membership_app_con_string"
    applicationName="my_membership_app"
    enablePasswordRetrieval="false"
    enablePasswordReset="true"
    requiresQuestionAndAnswer="true"
    requiresUniqueEmail="true"
    passwordFormat="Hashed"
    maxInvalidPasswordAttempts="4"
    minRequiredPasswordLength="9"
                passwordCompatMode="Framework40"
    passwordAttemptWindow="8"/>
          </providers>
</membership>

Once one hashAlgorithmType is used to create a Membership user, the same hashAlgorithmType must be used to validate the user. If hashAlgorithmType is changed, the user will not be validated successfully. Thus, the same hashAlgorithmType must be used for a given application during its lifetime.

PasswordFormat

This property gets a value indicating the format for storing passwords in the membership data source.

Declaration

// C#
public override MembershipPasswordFormat PasswordFormat{get;}

Property Value

The format for storing passwords in the data source. The format can be any one of the MembershipPasswordFormat values, such as Clear, Hashed, or Encrypted. The default value is Hashed.

Remarks

To customize a membership provider, ASP.NET developers can specify a MembershipPasswordFormat enumerated value for this property through the web.config file using the passwordFormat attribute. The attribute name in the configuration file is case-sensitive.

The PasswordFormat property indicates that passwords are stored in any one of the following formats: Clear, Encrypted, or Hashed. The format name is case-sensitive. For example, Clear is valid, but clear is invalid.

PasswordStrengthRegularExpression

This property gets the regular expression used to evaluate a password.

Declaration

// C#
public override string PasswordStrengthRegularExpression{get;}

Property Value

The regular expression that is used to evaluate a password. The default is an empty string.

Remarks

To customize a membership provider, ASP.NET developers can set a string value for this property through the web.config file using the passwordStrengthRegularExpression attribute. The attribute name in the configuration file is case-sensitive.

The PasswordStrengthRegularExpression property gets the regular expression as criteria to evaluate the password. If the password does not meet the criteria, it is not accepted by the membership provider.

Consider the following example:

passwordStrengthRegularExpression="(?=.{7,})(?=(.*\d){1,})(?=(.*\W){1,})"

The code in the preceding example validates passwords against the following criteria:

• Has at least 7 characters.

• Contains at least 1 digit.

• Contains at least 1 special (nonalphanumeric) character.

The minimum password length defined in passwordStrengthRegularExpression must be equal to or greater than the value of the minRequiredPasswordLength attribute.

The minimum number of special (nonalphanumeric) characters defined in the passwordStrengthRegularExpression attribute must be equal to or greater than the value of the minRequiredNonalphanumericCharacters attribute.

The passwordStrengthRegularExpression attribute is not used in automatically generated passwords from the ResetPassword method.

RequiresQuestionAndAnswer

This property gets a value indicating whether or not the membership provider is configured in such a way that it requires the user to answer a password question for password reset and retrieval.

Declaration

// C#
public override bool RequiresQuestionAndAnswer{get;}

Property Value

Returns true, if a password answer is required for password reset and retrieval; otherwise, returns false. The default value is true.

Remarks

To customize a membership provider, ASP.NET developers can set a Boolean value for this property through the web.config file by using the requiresQuestionAndAnswer attribute. The value indicates whether users must supply a password answer in order to retrieve their password using the GetPassword method, or reset their password using the ResetPassword method. The attribute name in the configuration file is case-sensitive.

RequiresUniqueEmail

This property gets a value indicating whether or not the membership provider is configured to require a unique e-mail address for each user name.

Declaration

// C#
public override bool RequiresUniqueEmail{get;}

Property Value

Returns true, if the membership provider requires a unique e-mail address; otherwise, returns false. The default value is false.

Remarks

To customize a membership provider, ASP.NET developers can specify a Boolean value for the RequiresUniqueEmail property through the web.config file using the requiresUniqueEmail attribute. The attribute name in the configuration file is case-sensitive.

---

OracleMembershipProvider Public Methods

OracleMembershipProvider public methods are listed in Table 2-8.

ChangePassword

This method updates the password for a user.

Declaration

// C#
public override bool ChangePassword(string userName, string oldPassword, 
  string newPassword);

Parameters

• userName

  The user to update the password for.

• oldPassword

  The current password for the specified user.

• newPassword

  The new password for the specified user.

Return Value

Returns true if the password was updated successfully; otherwise, returns false.

Exceptions

ArgumentNullException - The userName, oldPassword, or newPassword parameter is null.

System.Web.Security.MembershipPasswordException - userName was not found in the membership database.

System.Configuration.Provider.ProviderException - An error occurred when setting the new password in the database.

Exception - An unhandled exception has occurred.

ArgumentException - One of the following conditions exists:

• The userName parameter is an empty string, contains a comma, or is longer than 256 characters.

• The oldPassword parameter is an empty string or is longer than 128 characters.

• The newPassword parameter is an empty string, is longer than 128 characters (including the encoded version), is less than the value of the MinRequiredPasswordLength property, has a number of nonalphanumeric characters less than the value of MinRequiredNonAlphanumericCharacters property, or does not match the regular expression defined in the PasswordStrengthRegularExpression property.

• The change-password operation was canceled by a subscriber to the ValidatingPassword event, and the FailureInformation property was a null reference.

Remarks

The ChangePassword method returns true if the supplied user name and password are valid and the password was updated successfully; otherwise, it returns false.

ChangePasswordQuestionAndAnswer

This method updates the password question and answer for a user.

Declaration

// C#
public override bool ChangePasswordQuestionAndAnswer(string userName, string
   password, string newPasswordQuestion, string newPasswordAnswer);

Parameters

• userName

  The user that the password question and answer change for.

• password

  The password for the specified user.

• newPasswordQuestion

  The new password question for the specified user.

• newPasswordAnswer

  The new password answer for the specified user.

Return Value

Returns true, if the password question and answer were updated successfully; false, if otherwise.

Exceptions

ArgumentException - One of the following conditions exists:

• The userName parameter is an empty string, contains a comma, or is longer than 256 characters.

• The password parameter is an empty string or is longer than 128 characters.

• The newPasswordQuestion parameter is an empty string or is longer than 256 characters.

• The newPasswordAnswer parameter is an empty string or is longer than 128 characters (including the encoded version).

Remarks

If the user name and password supplied are valid and the password question and answer were updated successfully, then this method returns true. Otherwise, it returns false.

CreateUser

This method adds a new user to the database.

Declaration

// C#
public override MembershipUser CreateUser(string userName, string password,
   string emailAddress, string passwordQuestion, string passwordAnswer, bool
   isApproved, Object providerUserKey, out MembershipCreateStatus status);

Parameters

• userName

  The user name for the new user.

• password

  The password for the new user.

• emailAddress

  The email address for the new user.

• passwordQuestion

  The password question for the new user.

• passwordAnswer

  The password answer for the new user.

• isApproved

  A Boolean value that indicates whether or not the new user is approved to be validated.

• providerUserKey

  The unique identifier from the database for the new user.

• status

  A MembershipCreateStatus enumeration value indicating whether or not the user was created successfully.

Return Value

A MembershipUser object populated with the information for the newly created user.

Remarks

This method returns a MembershipUser object populated with the information for the newly created user. The status parameter returns a MembershipCreateStatus value that indicates whether or not the user was successfully created. If the CreateUser method failed, a MembershipCreateStatus member indicates the cause of the failure.

MembershipCreateStatus Enumeration

The MembershipCreateStatus enumeration values are listed in Table 2-9.

DeleteUser

This method removes a user from the database.

Declaration

// C#
public override bool DeleteUser(string userName, bool deleteAllRelatedData);

Parameters

• userName

  The name of the user to delete.

• deleteAllRelatedData

  A Boolean value that indicates whether or not all the data related to the user is to be removed from the database.

Return Value

Returns true, if the user was successfully deleted; false, if otherwise or if the user does not exist in the database.

Exceptions

ArgumentException - The userName parameter is an empty string, contains a comma, or is longer than 256 characters.

ArgumentNullException - The userName parameter is a null reference.

Remarks

Leading and trailing spaces are trimmed from the userName parameter value. If deleteAllRelatedData is true, then all data related to the user in the database such as, data for roles, profiles, and personalization, are also deleted, even if the user does not exist in the Oracle membership database.

FindUsersByEmail

This method returns a collection of users whose e-mail addresses match the specified e-mail address.

Declaration

// C#
public override MembershipUserCollection FindUsersByEmail(string emailToMatch,
   int pageIndex, int pageSize, out int totalRecords);

Parameters

• emailToMatch

  The email address to search for.

• pageIndex

  The index of the page of results to return. The PageIndex is zero-based.

• pageSize

  The size of the page of results to return.

• totalRecords

  The total number of matched users.

Return Value

Returns a MembershipUserCollection object that contains MembershipUser objects.

Exceptions

ArgumentException - One of the following conditions exists:

• The emailToMatch parameter is an empty string or is longer than 256 characters.

• The pageIndex parameter is less than 0.

• The pageSize parameter is less than 1 or the page upper bound is larger than Int32.MaxValue.

ArgumentNullException - The emailToMatch, pageIndex, pageSize, or totalRecords parameter is null.

Remarks

Leading and trailing spaces are trimmed from the emailToMatch parameter value. The results returned by the FindUsersByEmail method are constrained by the pageIndex and pageSize parameters. The pageSize parameter identifies the maximum number of MembershipUser objects to return in the MembershipUserCollection object. The pageIndex parameter identifies which page of results to return. Zero identifies the first page, as the value is zero-based. The totalRecords parameter is an out parameter for the total number of users that matched the emailToMatch value.

The OracleMembershipProvider class supports extensive searching by accepting the percent character (%) as a wildcard.

FindUsersByName

This method returns a collection of users that match the specified user name.

Declaration

// C#
public override MembershipUserCollection FindUsersByEmail(string userNameToMatch,
  int pageIndex, int pageSize, out int totalRecords);

Parameters

• userNameToMatch

  The user name to search for.

• pageIndex

  The zero-based index of the returned results page.

• pageSize

  The size of the returned results page.

• totalRecords

  The total number of matched users.

Return Value

Returns a MembershipUserCollection object that contains MembershipUser objects.

Exceptions

ArgumentException - One of the following conditions exists:

• The userNameToMatch parameter is an empty string, contains a comma, or is longer than 256 characters.

• The pageIndex parameter is less than 0.

• The pageSize parameter is less than 1 or the page upper bound is larger than Int32.MaxValue.

ArgumentNullException - The userNameToMatch, pageIndex, pageSize, or totalRecords parameter is null.

Remarks

Leading and trailing spaces are trimmed from the userNameToMatch parameter value.

The results returned by the FindUsersByName method are constrained by the pageIndex and pageSize parameters. The pageSize parameter identifies the maximum number of MembershipUser objects to return in the MembershipUserCollection object. The pageIndex parameter identifies which page of results to return. Zero identifies the first page, as the value is zero-based. The totalRecords parameter is an out parameter for the total number of users that matched the userNameToMatch value.

The OracleMembershipProvider class supports extensive search by accepting the percent character (%) as a wildcard.

GeneratePassword

This method generates a random password that is at least 14 characters in length.

Declaration

// C#
public virtual string GeneratePassword( );

Return Value

A random string for a password that is at least 14 characters in length.

Remarks

The OracleMembershipProvider object calls the GeneratePassword method to get a randomly generated password that is at least 14 characters but less than 128 characters in length.

The generated password contains only alphanumeric characters and the following punctuation marks: !@#$%^&*()_-+=[{]};:<>|./?. No hidden or non-printable control characters are included in the generated password.

If the value specified for MinRequiredPasswordLength property is greater than 14, then the length of the password returned by the GeneratePassword property is the value of the MinRequiredPasswordLength property. Otherwise, the length is 14 characters.

The random password generated by the GeneratePassword method is not guaranteed to pass the regular expression in the PasswordStrengthRegularExpression property. However, the random password meets the criteria established by the MinRequiredPasswordLength and MinRequiredNonAlphanumericCharacters properties.

GetAllUsers

This method returns a collection of all the users in the database.

Declaration

// C#
public override MembershipUserCollection GetAllUsers(int pageIndex, int pageSize,
   out int totalRecords);

Parameters

• pageIndex

  The zero-based index of the page of results to return.

• pageSize

  The size of the page of results to return.

• totalRecords

  The total number of users.

Return Value

A MembershipUserCollection object that contains MembershipUser objects.

Exceptions

ArgumentException - The pageIndex parameter is less than 0, or the pageSize parameter is less than 1 or the page upper bound is larger than Int32.MaxValue.

ArgumentNullException - The pageIndex, pageSize, or totalRecords parameter is null.

Remarks

The results returned by the GetAllUsers method are constrained by the pageIndex and pageSize parameters. The pageSize parameter identifies the maximum number of MembershipUser objects to return in the MembershipUserCollection object. The pageIndex parameter identifies which page of results to return. Zero identifies the first page, as the value is zero-based. The totalRecords parameter is an out parameter for the total number of users for the configured applicationName.

GetNumberOfUsersOnline

This method returns the number of users that are currently accessing the application.

Declaration

// C#
public override int GeNumberOfUsersOnline();

Return Value

An integer value indicating the total number of users currently accessing the application.

Remarks

The GetNumberOfUsersOnline method returns the number of users of the current application whose last activity date and time is greater than the current date and time less the value (in minutes) of the Membership.UserIsOnlineTimeWindow property.

The count includes only users that are associated with the configured applicationName.

GetPassword

This method returns the password for the specified user name from the database.

Declaration

// C#
public override string GetPassword(string userName, string passwordAnswer);

Parameters

• userName

  The user to retrieve the password for.

• passwordAnswer

  The password answer for the user.

Return Value

A password string for the specified user name.

Exceptions

ArgumentNullException - The userName parameter is null or the passwordAnswer parameter is null when the RequiresQuestionAndAnswer property is true.

System.Web.Security.MembershipPasswordException - The passwordAnswer parameter is invalid or the user identified by userName is being locked.

System.Configuration.Provider.ProviderException - The userName parameter is not found in the membership database, or an error occurred when retrieving the password from the membership database.

NotSupportedException - EnablePasswordRetrieval property is set to false.

ArgumentException - One of the following conditions exists:

• The userName parameter is an empty string, contains a comma, or is longer than 256 characters.

• The passwordAnswer parameter is an empty string and the RequiresQuestionAndAnswer property is true, or the passwordAnswer parameter is longer than 128 characters (including the encoded version).

Remarks

Leading and trailing spaces are trimmed from the userName and passwordAnswer parameter values.

The GetPassword method requires that the EnablePasswordRetrieval property be set to true. However, if the PasswordFormat property is set to Hashed, then a ProviderException is thrown when the provider is initialized. In other words, the GetPassword method cannot retrieve Hashed passwords. By default, the EnablePasswordRetrieval property is set to false.

If the RequiresQuestionAndAnswer property is set to true and an incorrect password answer is supplied to the GetPassword method, then the internal counter that tracks invalid password-answer attempts is incremented by one. This can result in the user being locked out and unable to log on until the lock status is cleared by a call to the UnlockUser method. If the correct password answer is supplied and the user is not currently locked out, then the internal counter that tracks invalid password-answer attempts is reset to zero.

GetUser

This method returns user information from the database based on the unique identifier for the user.

Overload List:

• GetUser(Object, bool)

  This method returns user information from the database based on the supplied unique identifier.

• GetUser(string, bool)

  This method returns user information from the database based on the supplied the user name.

GetUser(Object, bool)

This method returns user information from the database based on the supplied unique identifier.

Declaration

// C#
public override MembershipUser GetUser(Object providerUserKey, 
   bool userIsOnline);

Parameters

• providerUserKey

  The unique identifier of the user for whom information is being retrieved.

• userIsOnline

  A Boolean value that indicates whether or not the method updates the last-activity date/time stamp for the user. If the value is set to true, it is updated; otherwise, the method returns user information without updating the last-activity date/time stamp.

Return Value

A MembershipUser object populated with the specified user's information from the database.

Exceptions

ArgumentException - The providerUserKey parameter is not of type GUID.

ArgumentNullException - The providerUserKey parameter is null.

Remarks

The GetUser method provides an option to update the last-activity date/time stamp for the user.

The GetUser method returns a MembershipUser object populated with information about the specified user. If the user name is not found in the database, then the GetUser method returns a null reference.

GetUser(string, bool)

This method returns user information from the database based on the supplied user name.

Declaration

// C#
public override MembershipUser GetUser(string userName, bool userIsOnline);

Parameters

• userName

  The name of the user to get information for.

• userIsOnline

  A Boolean value that indicates whether or not the method updates the last-activity date/time stamp for the user. If the value is set to true, it is updated; otherwise, the method returns user information without updating the last-activity date/time stamp.

Return Value

A MembershipUser object populated with the specified user's information from the database.

Exceptions

ArgumentException - The userName parameter is an empty string, contains a comma, or is longer than 256 characters.

ArgumentNullException - The userName parameter is null.

Remarks

The GetUser method provides an option to update the last-activity date/time stamp for the user.

The GetUser method returns a MembershipUser object populated with information about the specified user. If the user name is not found in the database, then the GetUser method returns a null reference.

GetUserNameByEmail

This method returns the user name associated with the specified e-mail address.

Declaration

// C#
public override string GetUserNameByEmail(string emailAddress);

Parameters

• emailAddress

  The email address to search for.

Return Value

The user name associated with the specified e-mail address. If no match is found, then it returns a null reference.

Exceptions

ArgumentException - E-mail address exceeds 256 characters.

System.Configuration.Provider.ProviderException - More than one user with the same e-mail address exists in the database and the RequiresUniqueEmail property is true.

Remarks

If the value of the RequiresUniqueEmail property is true, then a unique e-mail address must be associated with each user name.

Initialize

This method initializes the OracleMembership provider with the property values specified in the ASP.NET application configuration file (web.config).

Declaration

// C#
public override void Initialize(string name, NameValueCollection config);

Parameters

• name

  The name of the OracleMembership provider instance to initialize.

• config

  A collection of name/value pairs representing the provider-specific attributes specified in the configuration for this provider.

Exceptions

ArgumentNullException - The config parameter is a null value.

InvalidOperationException - An attempt is made to call the Initialize method on a provider after the provider has already been initialized.

HttpException - The current trust level is less than Low.

System.Configuration.Provider.ProviderException - One of the following is true in the application configuration file:

• The enablePasswordRetrieval, enablePasswordReset, requiresQuestionAndAnswer, or requiresUniqueEmail attribute is set to a value other than a Boolean value.

• The maxInvalidPasswordAttempts or passwordAttemptWindow attribute is set to a value that is not a positive integer.

• The minRequiredPasswordLength attribute is set to a value that is not a positive integer, or the value is greater than 128.

• The minRequiredNonalphanumericCharacters attribute is set to a negative integer, or the value is greater than 128.

• The value for the passwordStrengthRegularExpression attribute is not a valid regular expression.

• The value for the applicationName attribute is greater than 256 characters.

• The value for passwordFormat attribute is an invalid MembershipPasswordFormat enumeration value.

• The passwordFormat attribute is set to Hashed, and the enablePasswordRetrieval attribute is set to true.

• The passwordFormat attribute is set to Encrypted, and the machineKey configuration element specifies AutoGenerate for the decryptionKey attribute.

• The connectionStringName attribute is empty or does not exist in the application configuration file.

• The value of the connection string for the connectionStringName attribute value is empty, or the specified connectionStringName does not exist in the application configuration file.

• The value for the commandTimeout attribute is set to a negative integer.

• The application configuration file for this OracleMembershipProvider instance contains an unrecognized attribute.

Remarks

The Initialize method is not intended to be called directly by the application.

ResetPassword

This method resets a user's password and returns a new automatically generated password.

Declaration

// C#
public override string ResetPassword(string userName, string passwordAnswer);

Parameters

• userName

  The user to reset the password for.

• passwordAnswer

  The password answer for the specified user.

Return Value

The new password for the specified user.

Exceptions

ArgumentNullException - The userName parameter is a null reference, or the passwordAnswer parameter is null when the RequiresQuestionAndAnswer property is true.

System.Web.Security.MembershipPasswordException - The passwordAnswer parameter is invalid or the user identified by the userName parameter is locked out.

ArgumentException - One of the following conditions exists:

• The userName parameter is an empty string, contains a comma, or is longer than 256 characters.

• The passwordAnswer parameter is an empty string and RequiresQuestionAndAnswer property is true, or the passwordAnswer parameter is longer than 128 characters (including the encoded version).

System.Configuration.Provider.ProviderException - One of the following conditions exists:

• userName was not found in the membership database.

• The reset-password operation was canceled by a subscriber to the ValidatingPassword event and the FailureInformation property was a null reference.

• An error occurred when resetting the password in the membership database.

NotSupportedException - The EnablePasswordReset property is set to false.

Exception - An unhandled exception occurred.

Remarks

Leading and trailing spaces are trimmed from the userName and passwordAnswer parameter values.

The ResetPassword method is most commonly used when the PasswordFormat property is set to Hashed. If a user forgets a password that is in hashed format, the password cannot be retrieved. However, the provider can reset the password to a new, automatically generated password if the user supplies the correct password answer. The ResetPassword method requires that the EnablePasswordReset property is set to true. If an incorrect password answer is supplied to the ResetPassword method, then the internal counter that tracks invalid password attempts is incremented by one. This can result in the user being locked out and unable to log on until the lock status is cleared by a call to the UnlockUser method. If the correct password answer is supplied and the user is not currently locked out, then the internal counter that tracks invalid password-answer attempts is reset to zero.

The random password generated by the ResetPassword method is not guaranteed to pass the regular expression in the PasswordStrengthRegularExpression property. However, the random password will meet the criteria established by the MinRequiredPasswordLength and MinRequiredNonAlphanumericCharacters properties.

UnlockUser

This method unlocks a user so that the user can be validated.

Declaration

// C#
public override bool UnLockUser(string userName);

Parameters

• userName

  The name of the user to be unlocked.

Return Value

Returns true, if the user was successfully unlocked; false, if otherwise.

Exceptions

ArgumentException - The userName parameter is an empty string, contains a comma, or is longer than 256 characters.

ArgumentNullException - The userName parameter is null.

Remarks

Leading and trailing spaces are trimmed from the userName parameter value.

UpdateUser

This method updates information about a user in the database.

Declaration

// C#
public override void UpdateUser(MembershipUser membershipUser);

Parameters

• membershipUser

  A MembershipUser object populated with user information.

Exceptions

ArgumentException - One of the following conditions exists:

• The userName property of membershipUser is an empty string, contains a comma, or is longer than 256 characters.

• The email property of membership User is an empty string and the Requires Unique Em ail property is set to true, or the mail property is longer than 256 characters.

Argument Null Exception - The membership User parameter is null, or the surname or mail property of the membership User parameter is null.

System.Configuration.Provider.ProviderException - One of the following conditions exists:

• The surname property of the membership User parameter is not found in the membership database.

• The mail property of the membership User parameter is equal to an existing e-mail address in the membership database, and the Requires Unique Em ail property is set to true.

• An error occurred when updating the user in the membership database.

Remarks

The specified user's Mail, Comment, IsApproved, Last Login Date, and LastActivityDate property values can be modified, and then updated by the UpdateUser method. However, the password for a user cannot. To update the password for a user, use the ChangePassword method of the MembershipUser class.

ValidateUser

This method validates the user.

Declaration

// C#
public override bool ValidateUser(string userName, string password);

Parameters

• userName

  The name of the user to be validated.

• password

  The password for the specified user.

Return Value

Returns true if the specified user name and password are valid; returns false if they are not valid or the user does not exist in the database.

Remarks

Leading and trailing spaces are trimmed from the userName and password parameter values.

When a user is successfully validated, the last activity date and last sign-in date values are updated to the current date and time in the database.

The ValidateUser method returns false on any user who was created with the isApproved parameter set to false.

If an incorrect password is supplied to the ValidateUser method, then the internal counter that tracks invalid password attempts is incremented by one. This can result in the user being locked out and unable to log on until the lock status is cleared by a call to the UnlockUser method. If the correct password is supplied and the user is not currently locked out, then the internal counters that track invalid password and password-answer attempts are reset to zero.

---

OracleMembershipProvider Public Events

OracleMembershipProvider public event is listed in Table 2-10.