| 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 |
| 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.
|
 Copyright © 2007, 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|