Oracle® Providers for ASP.NET Developer's Guide 11g Release 2 (11.2.0.1.2) for Microsoft Windows Part Number E17192-03 |
|
|
View PDF |
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.1.2, 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
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.
Overload List:
This constructor creates an instance of the OracleMembershipProvider
class.
See Also:
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.
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.
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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.
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.
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.
See Also:
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.1.2, 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.
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.
See Also:
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.
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.
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.
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.
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.
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.
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
.
See Also:
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
.
See Also:
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.
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.
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.
See Also:
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.
See Also:
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
.
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.
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.
See Also:
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.
See Also:
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
.
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.
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
.
See Also:
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
.
See Also:
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.
See Also:
This method returns user information from the database based on the unique identifier for the user.
Overload List:
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.
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
OracleMembershipProvider
public event is listed in Table 2-10.