Oracle® Providers for ASP.NET Developer's Guide 11g Release 2 (11.2.0.3) for Microsoft Windows E18737-02 |
|
|
PDF · Mobi · ePub |
The OracleMembershipProvider
class enables ASP.NET developers to store Web site user account information in an Oracle database.
System.Object
System.Configuration.Provider.ProviderBase
System.Web.Security.MembershipProvider
Oracle.Web.Security.OracleMembershipProvider
// C# public class OracleMembershipProvider: MembershipProvider
All public static methods are thread-safe, although instance members are not guaranteed to be thread-safe.
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.
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.
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
See Also:
OracleMembershipProvider
members are listed in the following tables.
OracleMembershipProvider Constructors
The OracleMembershipProvider
constructor is listed in Table 2-1.
Table 2-1 OracleMembershipProvider Constructor
Constructor | Description |
---|---|
Instantiates a new instance of the |
OracleMembershipProvider Static Methods
OracleMembershipProvider
static methods are listed in Table 2-2.
Table 2-2 OracleMembershipProvider Static Methods
Static Methods | Description |
---|---|
|
Inherited from |
|
Inherited from |
OracleMembershipProvider Public Properties
OracleMembershipProvider
public properties are listed in Table 2-3.
Table 2-3 OracleMembershipProvider Public Properties
Public Properties | Description |
---|---|
Gets or sets the name of the application that is used to group user information |
|
Gets the number of seconds that the command is allowed to execute before it is terminated with an exception |
|
|
Inherited from |
Indicates whether or not the membership provider is configured to allow users to reset their passwords |
|
Indicates whether or not the membership provider is configured to allow users to retrieve their passwords |
|
Gets the number of invalid password or password-answer attempts allowed before the user is locked out |
|
Gets the minimum number of special characters that must be present in a valid password |
|
Gets the minimum length required for a password |
|
|
Inherited from |
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 |
|
Gets the password compatibility mode. |
|
Gets a value indicating the format for storing passwords in the membership data source |
|
Gets the regular expression used to evaluate a password |
|
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 |
|
Gets a value indicating whether or not the membership provider is configured to require a unique e-mail address for each user name |
OracleMembershipProvider Public Methods
OracleMembershipProvider
public methods are listed in Table 2-4.
Table 2-4 OracleMembershipProvider Public Methods
Public Methods | Description |
---|---|
Updates the password for a user |
|
Updates the password question and answer for a user |
|
Adds a new user to the database |
|
Removes a user from the database |
|
|
Inherited from |
Returns a collection of users whose e-mail addresses match the specified e-mail address |
|
Returns a collection of users that match the specified user name |
|
Generates a random password that is at least 14 characters in length |
|
Returns a collection of all the users in the database |
|
|
Inherited from |
Returns the number of users that are currently accessing the application |
|
Returns the password for the specified user name from the database |
|
|
Inherited from |
Returns user information from the database based on the unique identifier for the user (Overloaded) |
|
Returns the user name associated with the specified e-mail address |
|
Initializes the |
|
Resets a user's password and returns a new automatically generated password |
|
|
Inherited from |
Unlocks a user so that the user can be validated |
|
Updates information about a user in the database |
|
Validates the user |
OracleMembershipProvider Public Events
OracleMembershipProvider
public event is listed in Table 2-5.
Table 2-5 OracleMembershipProvider Public Event
Public Event | Description |
---|---|
|
Inherited from |
See Also:
This constructor instantiates a new instance of the OracleMembershipProvider
class.
This constructor creates an instance of the OracleMembershipProvider
class.
See Also:
This constructor instantiates a new instance of the OracleMembershipProvider
class.
// C# public OracleMembershipProvider();
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.
See Also:
OracleMembershipProvider
static methods are listed in Table 2-6.
Table 2-6 OracleMembershipProvider Static Methods
Static Methods | Description |
---|---|
|
Inherited from |
|
Inherited from |
See Also:
OracleMembershipProvider
public properties are listed in Table 2-7.
Table 2-7 OracleMembershipProvider Public Properties
Public Properties | Description |
---|---|
Gets or sets the name of the application that is used to group user information |
|
Gets the number of seconds that the command is allowed to execute before it is terminated with an exception |
|
|
Inherited from |
Indicates whether or not the membership provider is configured to allow users to reset their passwords |
|
Indicates whether or not the membership provider is configured to allow users to retrieve their passwords |
|
Gets the number of invalid password or password-answer attempts allowed before the user is locked out |
|
Gets the minimum number of special characters that must be present in a valid password |
|
Gets the minimum length required for a password |
|
|
Inherited from |
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 |
|
Gets the password compatibility mode. |
|
Gets a value indicating the format for storing passwords in the membership data source |
|
Gets the regular expression used to evaluate a password |
|
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 |
|
Gets a value indicating whether or not the membership provider is configured to require a unique e-mail address for each user name |
See Also:
This property gets or sets the name of the application that is used to group user information.
// C# public override string ApplicationName{get; set;}
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.
ArgumentException
- The application name supplied is an empty string or a null reference.
ProviderException
- The application name supplied exceeds 256 characters.
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.
See Also:
This property gets the number of seconds that the command is allowed to execute before it is terminated with an exception.
// C# public int CommandTimeout {get;}
An int
.
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.
See Also:
This property indicates whether or not the membership provider is configured to allow users to reset their passwords.
// C# public override bool EnablePasswordReset{get;}
Returns true
, if the membership provider supports password reset; otherwise, it returns false
. The default is true
.
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.
See Also:
This property indicates whether or not the membership provider is configured to allow users to retrieve their passwords.
// C# public override bool EnablePasswordRetrieval{get;}
Returns true
, if the membership provider is configured to support password retrieval; otherwise, returns false
. The default is false
.
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.
See Also:
This property gets the number of invalid password or password-answer attempts allowed before the user is locked out.
// C# public override int MaxInvalidPasswordAttempts{get;}
The number of invalid password or password-answer attempts allowed before the user is locked out. The default number of attempts is 5.
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.
See Also:
This property gets the minimum number of special characters that must be present in a valid password.
// C# public override int MinRequiredNonAlphanumericCharacters(get;}
The minimum number of special characters that must be present in a valid password. The default value is 1.
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.
See Also:
This property gets the minimum length required for a password.
// C# public override int MinRequiredPasswordLength{get;}
The minimum length required for a password. The default value is 7.
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.
See Also:
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.
// C# public override int PasswordAttemptWindow{get;}
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.
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.
See Also:
This property gets the password compatibility mode.
// C# public string PasswordCompatMode {get;}
A string
.
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
.
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.
See Also:
This property gets a value indicating the format for storing passwords in the membership data source.
// C# public override MembershipPasswordFormat PasswordFormat{get;}
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
.
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.
See Also:
This property gets the regular expression used to evaluate a password.
// C# public override string PasswordStrengthRegularExpression{get;}
The regular expression that is used to evaluate a password. The default is an empty string.
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.
See Also:
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.
// C# public override bool RequiresQuestionAndAnswer{get;}
Returns true
, if a password answer is required for password reset and retrieval; otherwise, returns false
. The default value is true
.
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.
See Also:
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.
// C# public override bool RequiresUniqueEmail{get;}
Returns true
, if the membership provider requires a unique e-mail address; otherwise, returns false
. The default value is false
.
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.
See Also:
OracleMembershipProvider
public methods are listed in Table 2-8.
Table 2-8 OracleMembershipProvider Public Methods
Public Methods | Description |
---|---|
Updates the password for a user |
|
Updates the password question and answer for a user |
|
Adds a new user to the database |
|
Removes a user from the database |
|
|
Inherited from |
Returns a collection of users whose e-mail addresses match the specified e-mail address |
|
Returns a collection of users that match the specified user name |
|
Generates a random password that is at least 14 characters in length |
|
Returns a collection of all the users in the database |
|
|
Inherited from |
Returns the number of users that are currently accessing the application |
|
Returns the password for the specified user name from the database |
|
|
Inherited from |
Returns user information from the database based on the unique identifier for the user (Overloaded) |
|
Returns the user name associated with the specified e-mail address |
|
Initializes the |
|
Resets a user's password and returns a new automatically generated password |
|
|
Inherited from |
Unlocks a user so that the user can be validated |
|
Updates information about a user in the database |
|
Validates the user |
See Also:
This method updates the password for a user.
// C# public override bool ChangePassword(string userName, string oldPassword, string newPassword);
userName
The user to update the password for.
oldPassword
The current password for the specified user.
newPassword
The new password for the specified user.
Returns true
if the password was updated successfully; otherwise, returns false
.
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.
The ChangePassword
method returns true
if the supplied user name and password are valid and the password was updated successfully; otherwise, it returns false
.
See Also:
This method updates the password question and answer for a user.
// C# public override bool ChangePasswordQuestionAndAnswer(string userName, string password, string newPasswordQuestion, string newPasswordAnswer);
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.
Returns true
, if the password question and answer were updated successfully; false
, if otherwise.
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).
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
.
See Also:
This method adds a new user to the database.
// C# public override MembershipUser CreateUser(string userName, string password, string emailAddress, string passwordQuestion, string passwordAnswer, bool isApproved, Object providerUserKey, out MembershipCreateStatus status);
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.
A MembershipUser
object populated with the information for the newly created user.
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.
Table 2-9 MembershipCreateStatus Enumeration Values
Member Name | Description |
---|---|
|
The e-mail address for the application already exists in the database. |
|
The provider user key for the application already exists in the database. |
|
The user name for the application already exists in the database. |
|
The password answer is not formatted correctly. |
|
The e-mail address is not formatted correctly. |
|
The password is not formatted correctly. |
|
The provider user key is of an invalid type or format. |
|
The password question is not formatted correctly. |
|
The user name was not found in the database. |
|
The provider returned an error that is not described by other |
|
The user was successfully created. |
|
The user was not created, for a reason defined by the provider. |
See Also:
This method removes a user from the database.
// C# public override bool DeleteUser(string userName, bool deleteAllRelatedData);
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.
Returns true
, if the user was successfully deleted; false
, if otherwise or if the user does not exist in the database.
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.
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.
See Also:
This method returns a collection of users whose e-mail addresses match the specified e-mail address.
// C# public override MembershipUserCollection FindUsersByEmail(string emailToMatch, int pageIndex, int pageSize, out int totalRecords);
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.
Returns a MembershipUserCollection
object that contains MembershipUser
objects.
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.
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.
See Also:
This method returns a collection of users that match the specified user name.
// C# public override MembershipUserCollection FindUsersByEmail(string userNameToMatch, int pageIndex, int pageSize, out int totalRecords);
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.
Returns a MembershipUserCollection
object that contains MembershipUser
objects.
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
.
Note:
The page lower bound is (pageIndex
* pageSize
) and the page upper bound is (pageIndex
*pageSize
) + (pageSize
- 1).ArgumentNullException
- The userNameToMatch
, pageIndex
, pageSize
, or totalRecords
parameter is null.
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.
See Also:
This method generates a random password that is at least 14 characters in length.
// C# public virtual string GeneratePassword( );
A random string for a password that is at least 14 characters in length.
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.
See Also:
This method returns a collection of all the users in the database.
// C# public override MembershipUserCollection GetAllUsers(int pageIndex, int pageSize, out int totalRecords);
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.
A MembershipUserCollection
object that contains MembershipUser
objects.
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
.
Note:
The page lower bound is (pageIndex
* pageSize
) and the page upper bound is (pageIndex
*pageSize
) + (pageSize
- 1).ArgumentNullException
- The pageIndex
, pageSize
, or totalRecords
parameter is null.
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
.
See Also:
This method returns the number of users that are currently accessing the application.
// C# public override int GeNumberOfUsersOnline();
An integer value indicating the total number of users currently accessing the application.
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
.
See Also:
This method returns the password for the specified user name from the database.
// C# public override string GetPassword(string userName, string passwordAnswer);
userName
The user to retrieve the password for.
passwordAnswer
The password answer for the user.
A password string for the specified user name.
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).
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.
See Also:
This method returns user information from the database based on the unique identifier for the user.
This method returns user information from the database based on the supplied unique identifier.
This method returns user information from the database based on the supplied the user name.
See Also:
This method returns user information from the database based on the supplied unique identifier.
// C# public override MembershipUser GetUser(Object providerUserKey, bool userIsOnline);
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.
A MembershipUser
object populated with the specified user's information from the database.
ArgumentException
- The providerUserKey
parameter is not of type GUID
.
ArgumentNullException
- The providerUserKey
parameter is null.
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.
See Also:
This method returns user information from the database based on the supplied user name.
// C# public override MembershipUser GetUser(string userName, bool userIsOnline);
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.
A MembershipUser
object populated with the specified user's information from the database.
ArgumentException
- The userName
parameter is an empty string, contains a comma, or is longer than 256 characters.
ArgumentNullException
- The userName
parameter is null.
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.
See Also:
This method returns the user name associated with the specified e-mail address.
// C#
public override string GetUserNameByEmail(string emailAddress);
emailAddress
The email address to search for.
The user name associated with the specified e-mail address. If no match is found, then it returns a null reference.
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
.
If the value of the RequiresUniqueEmail
property is true
, then a unique e-mail address must be associated with each user name.
See Also:
This method initializes the OracleMembership
provider with the property values specified in the ASP.NET application configuration file (web.config
).
// C# public override void Initialize(string name, NameValueCollection config);
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.
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.
The Initialize
method is not intended to be called directly by the application.
See Also:
This method resets a user's password and returns a new automatically generated password.
// C# public override string ResetPassword(string userName, string passwordAnswer);
userName
The user to reset the password for.
passwordAnswer
The password answer for the specified user.
The new password for the specified user.
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.
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.
See Also:
This method unlocks a user so that the user can be validated.
// C#
public override bool UnLockUser(string userName);
userName
The name of the user to be unlocked.
Returns true
, if the user was successfully unlocked; false
, if otherwise.
ArgumentException
- The userName
parameter is an empty string, contains a comma, or is longer than 256 characters.
ArgumentNullException
- The userName
parameter is null.
Leading and trailing spaces are trimmed from the userName
parameter value.
See Also:
This method updates information about a user in the database.
// C#
public override void UpdateUser(MembershipUser membershipUser);
membershipUser
A MembershipUser
object populated with user information.
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.
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.
See Also:
This method validates the user.
// C# public override bool ValidateUser(string userName, string password);
userName
The name of the user to be validated.
password
The password for the specified user.
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.
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.
See Also:
OracleMembershipProvider
public event is listed in Table 2-10.