OracleRoleProvider Class

The OracleRoleProvider class allows ASP.NET applications to store role and user information in an Oracle database.

Class Inheritance

System.Object

  System.Configuration.Provider.ProviderBase

    System.Web.Security.RoleProvider

      Oracle.Web.Security

Declaration

// C#
public class OracleRoleProvider : RoleProvider

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 role information in an Oracle database.Note that the role information that this provider manages are application roles and not database roles.

Example

The following is a web.config example for an ASP.NET application that uses the OracleRoleProvider class 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>
    <roleManager enabled="true" defaultProvider="OracleRoleProvider"/>
  </system.web>
</configuration>

The following is a web.config example for an ASP.NET application that uses an OracleRoleProvider as the default provider 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_role_app_con_string" connectionString=
      "User Id=scott;Password=tiger;Data Source=Oracle"/>
  </connectionStrings>
  <system.web>
    <!-- Enable and customize OracleRoleProvider -->
    <roleManager enabled="true" defaultProvider="MyOracleRoleProvider">
      <providers>
        <add name="MyOracleRoleProvider"
             type="Oracle.Web.Security.OracleRoleProvider,
             Oracle.Web, Version=2.112.2.0, Culture=neutral,
             PublicKeyToken=89b483f429c47342"
             connectionStringName="my_role_app_con_string" 
             applicationName="my_role_app"/>
      </providers>
    </roleManager>
  </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

---

OracleRoleProvider Members

OracleRoleProvider members are listed in the following tables.

OracleRoleProvider Constructors

The OracleRoleProvider constructor is listed in Table 3-1.

OracleRoleProvider Static Methods

OracleRoleProvider static methods are listed in Table 3-2.

OracleRoleProvider Public Properties

OracleRoleProvider public properties are listed in Table 3-3.

OracleRoleProvider Public Methods

OracleRoleProvider public methods are listed in Table 3-4.

---

OracleRoleProvider Constructors

OracleRoleProvider constructors create instances of the OracleRoleProvider class.

Overload List:

• OracleRoleProvider()

  This constructor creates an instance of the OracleRoleProvider class.

OracleRoleProvider()

This constructor creates an instance of the OracleRoleProvider class.

Declaration

// C#
public OracleRoleProvider();

Remarks

This constructor creates a new instance of the OracleRoleProvider class.

---

OracleRoleProvider Static Methods

The OracleRoleProvider static methods are listed in Table 3-5.

---

OracleRoleProvider Public Properties

The OracleRoleProvider public properties are listed in Table 3-6.

ApplicationName

This property gets or sets the name of the application that stores the role provider 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

HttpException - The user setting the ApplicationName property does not have high ASP.NET hosting permission.

System.Configuration.Provider.ProviderException - The ApplicationName property is set to a string greater than 256 characters.

Remarks

The string value of the ApplicationName property is used to associate user names and role names with different applications. Multiple applications can use the same database to store user names and role names without running into any conflict between duplicate names. This property can be set programmatically, or it can be set declaratively in the Web application configuration file using the applicationName attribute. The attribute name in the configuration file is case-sensitive.

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

CommandTimeout

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

Declaration

// C#
public int CommandTimeout {get;}
 

Property Value

An int.

Remarks

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

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

---

OracleRoleProvider Public Methods

The OracleRoleProvider public methods are listed in Table 3-7.

AddUsersToRoles

This method adds the specified users to the specified roles.

Declaration

// C#
public override void AddUsersToRoles(string[] userNames, string[] roleNames);

Parameters

• userNames

  An array of user names to be added to roles.

• roleNames

  An array of role names to add the user names to.

Exceptions

ArgumentNullException - One of the users in userNames or one of the roles in roleNames is null.

ArgumentException - Either the roleNames or userNames parameter is an empty string, contains a comma, is longer than 256 characters, or contains a duplicate element.

System.Configuration.Provider.ProviderException - One or more role names were not found, or one or more user names are already associated with one or more role names.

OracleException - An Oracle-related error has occurred.

Remarks

This method adds one or more user names to one or more of the specified roles. The updates are performed in a transaction. If an error occurs, then the transaction is rolled back and no updates are made.

If one of the user names does not exist in the database, then the user name will be created and added to the database.

CreateRole

This method adds a new role to the database.

Declaration

// C#
public override void CreateRole(string roleName);

Parameters

• roleName

  The role name to be created in the database.

Exceptions

ArgumentNullException - The roleName parameter is null.

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

System.Configuration.Provider.ProviderException - The role name already exists in the database.

OracleException - An Oracle-related error has occurred.

Remarks

This method creates a new role in the database.

DeleteRole

This method deletes a role in the database.

Declaration

// C#
public override bool DeleteRole(string roleName, bool throwOnPopulatedRole);

Parameters

• roleName

  The role name to be deleted from the database.

• throwOnPopulatedRole

  A Boolean value that, if set to true, causes an exception if the role contains any user names. If the value is set to false, deletes the role from the database.

Return Value

Returns true if the specified role was successfully deleted; otherwise, returns false.

Exceptions

ArgumentNullException - The roleName parameter is null.

System.Configuration.Provider.ProviderException - The role name contains at least one user name and the throwOnPopulatedRole parameter is set to true.

OracleException - An Oracle-related error has occurred.

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

Remarks

If the throwOnPopulatedRole parameter is set to false, then it deletes the specified role from the database regardless of whether or not it contains any users. If the throwOnPopulatedRole parameter is set to true, then an exception is thrown if the specified role in the database contains any users, but the role is not deleted.

FindUsersInRole

This method returns an array of user names that match the specified user name, for the specified role name.

Declaration

// C#
public override string[ ] FindUsersInRole(string roleName, string
   userNameToMatch);

Parameters

• roleName

  The role name being searched for in the database.

• userNameToMatch

  The user name being searched for.

Return Value

A string array that contains user names in the specified role that match the specified userNameToMatch parameter.

Exceptions

ArgumentNullException - The roleName or userNameToMatch parameter is null.

OracleException - An Oracle-related error has occurred.

System.Configuration.Provider.ProviderException - The role name does not exist in the database.

ArgumentException - One of the following conditions exists:

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

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

Remarks

This method returns an array of user names that match the specified user name, for the specified role name. This method supports Oracle wildcard characters. If the userNameToMatch parameter is set to "oraUser%", then an array is returned for users such as "oraUser1", "oraUser2", and so on. However, if the userNameToMatch parameter is set to "oraUser", then the array is returned with just the username "oraUser", if there is an "oraUser".

GetAllRoles

This method returns an array of all the roles for an application.

Declaration

// C#
public override string[ ] GetAllRoles();

Return Value

A string array containing all the role names in a database for the application.

Exceptions

OracleException - An Oracle related error has occurred.

GetRolesForUser

This method returns an array of role names for the specified user.

Declaration

// C#
public override string[] GetRolesForUser(string userName);

Parameters

• userName

  The user name for which an array of role names is returned.

Return Value

An array of role names for the specified user name.

Exceptions

ArgumentNullException - The userName parameter is null.

ArgumentException - The userName parameter contains a comma or is longer than 256 characters.

OracleException - An Oracle-related error has occurred.

GetUsersInRole

This method returns an array of users in the specified role name.

Declaration

// C#
public override string[ ] GetUsersInRole(string roleName);

Parameters

• roleName

  The role name for which an array of users is returned.

Return Value

An array of user names in the specified role name.

Exceptions

ArgumentNullException - The roleName parameter is null.

OracleException - An Oracle-related error has occurred.

System.Configuration.Provider.ProviderException - The role name does not exist in the database.

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

Initialize

This method initializes the OracleRoleProvider instance 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 OracleRoleProvider instance to initialize.

• config

  A Systems.Collections.Specialized.NameValueCollection object that contains the names and values of configuration options for the role provider.

Exceptions

System.Web.HttpException - ASP.NET is not running at medium trust or higher.

ArgumentNullException - The config parameter is null.

System.Configuration.Provider.ProviderException - The connectionStringName attribute is empty or does not exist in the configuration file, the applicationName attribute exceeds 256 characters, or the configuration file contains an invalid attribute.

Remarks

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

IsUserInRole

This method indicates whether or not the specified user is in the specified role.

Declaration

// C#
public override bool IsUserInRole(string userName, string roleName);

Parameters

• userName

  The user name being searched for.

• roleName

  The role name being searched in.

Return Value

Returns true if the specified user name is in the specified role name; otherwise, returns false.

Exceptions

ArgumentNullException - The userName or roleName parameter is null.

OracleException - An Oracle-related error has occurred.

ArgumentException - One of the following conditions exists:

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

• The userName parameter contains a comma or is longer than 256 characters.

Remarks

This method determines if the specified user name exists in the specified role name in the database.

RemoveUsersFromRoles

This method removes the specified array of users from the specified array of role names.

Declaration

// C#
public override void RemoveUsersFromRoles(string[] userNames, string[] roleNames);

Parameters

• userNames

  An array of user names to remove from the role names.

• roleNames

  An array of role names to remove the user names from.

Exceptions

ArgumentNullException - One of the users in the userNames parameter or one of the roles in the roleNames parameter is null.

OracleException - An Oracle-related error has occurred.

System.Configuration.Provider.ProviderException - One or more of the role names or user names does not exist in the database, or one or more of the user names is not associated a role name.

ArgumentException - The roleNames or userNames parameter is an empty string, contains a comma, is longer than 256 characters, or contains a duplicate element.

Remarks

This method removes the specified array of user names from the specified array of role names. The updates are made within a transaction. If an error occurs, the transaction is rolled back.

RoleExists

This method indicates whether or not the specified role name exists in the database.

Declaration

// C#
public override bool RoleExists(string roleName);

Parameters

• roleName

  The role name being searched for in the database.

Return Value

Returns true if the role name exists; otherwise, returns false.

Exceptions

ArgumentNullException - The roleName parameter is null

OracleException - An Oracle-related error has occurred.

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