In the next example, we create a new project in Visual Studio and add the reference to the project. You can skip this step if you already have a project where you would like to use the .NET Business Connector.

Open Visual Studio and create a new project as shown in the next screenshot:

When you click on OK, you will have a new C# file called Program.cs. Before we start writing any code in the file, we have to add the .NET Business Connector as a reference.

In the Solution Explorer right-click on the References node and select Add Reference.

In the form that opens select Microsoft.Dynamics.BusinessConnectorNet.dll under the Browse tab.

The file is found in the ClientBin catalog of your AX installation. The default path is:

C:Program FilesMicrosoft Dynamics Ax50ClientBin

Click on OK and note that the reference has now been added under the References node in the Solution Explorer.

Using the .NET Business Connector in .NET classes

In the next sections of this article we will look at some examples that show how we can use methods in the .NET Business Connector to call AX methods, insert data into AX tables, and read data from AX tables.

Calling a static class method in AX

You now have to go back to AX, open the AOT and find the Global class. Add the following method to the Global class:

static str AxHelloWorld()
{
    return "HelloWorld!";
}

In the Visual Studio project we open the Program.cs file again and enter the following code that will create a connection to AX through the .NET Business Connector. We then call the method we created in the Global class before it prints the result to the console:

using System;
using Microsoft.Dynamics.BusinessConnectorNet;
namespace GetAxInfo1
{
    class Program
    {
        /// <summary>
        /// This class connects to AX throught the
        /// .NET Business Connector and call the static method
        /// AxHelloWorld in the Global class in AX.
        /// The result is sent to the console (command prompt).
        /// </summary>
        /// <param name="args"></param>
        static void Main(string[] args)
        {
            Axapta ax;
            Object axObject;
            try
            {
                // Create a new Axapta object.
                ax = new Axapta();
                // Logon using the default settings
                // in the AX configuration for the .NET
                // Business Connector
                ax.Logon(null, null, null, null);
                // Call the static method and return the
                // result to the axObject variable
                axObject =
                  ax.CallStaticClassMethod("Global", "AxHelloWorld");
                // Print the result to the console
                Console.WriteLine("The message from AX is {0}",
                  axObject.ToString());
                ax.Logoff();
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
            Console.ReadKey();
        }
    }
}

Execute the program by pressing Ctrl + F5. You should now see the following result in the console (command prompt) that opens up:

If you get a different result it might be because you haven't set up the .NET Business Connector correctly. If so, please refer to the installation guide to set it up properly. Also, check the Windows Event Viewer to see if there are any error messages that can lead you in the right direction.

Insert data into an AX table

As mentioned earlier in this article, you can use the methods in some of the marshaled classes in the .NET Business Connector to manipulate data. However, it is better to avoid this and instead have AX handle all data selection and manipulation. It would be even better to have your .NET application call a method in AX that does the job and returns the results back to the .NET application again. However, this is not always feasible, for instance, when you would like to insert records from your .NET application to an AX table. The next section will guide you through the steps needed to achieve this.

First, you should create a new project in Visual Studio as we did earlier in this article. In this example, we will call the new project "InsertAxRecord".

Then you have to add a reference to the .NET Business Connector.

In the Program.cs file (or whatever you call your file), you write something like this:

using System;
using Microsoft.Dynamics.BusinessConnectorNet;
namespace InsertAxRecord
{
    class Program
    {
        static void Main(string[] args)
        {
            Axapta ax;
            AxaptaRecord record;
            try
            {
                // Create AX object and logon to AX
                ax = new Axapta();
                ax.Logon(null, null, null, null);
                // Create a new AxaptaRecord object with
                // the name of the table as input parameter
                using (record = ax.CreateAxaptaRecord("CarTable"))
                {
                    // Remember to clear the tablebuffer if
                    // you are inserting inside a loop
                    record.Clear();
                    record.InitValue();
                    // Set the fields in the table
                    record.set_Field("CARID", "XXX1");
                    record.set_Field("MODELYEAR", 1998);
                    record.set_Field("CARBRAND", "FORD");
                    record.set_Field("MODEL", "F1");
                    record.set_Field("MILEAGE", 89378);
                    // Insert the record
                    record.Insert();
                }
                // End the AX session
                ax.Logoff();
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

If you open the table browser and look at the contents of CarTable in AX now (find the table in the AOT and pressing Ctrl + O to open the table browser) you should see that the record has been added.

Read data from an AX table

For our next example we will repeat the procedure from the previous example, except that now we will read data from the table instead of writing to the table.

Start off by creating a new project and add the .NET Business Connector as  a reference to the solution.

Enter the following code into the Program.cs file (or whatever you call your program):

using System;
using Microsoft.Dynamics.BusinessConnectorNet;
namespace ReadAxRecord
{
    class Program
    {
        static void Main(string[] args)
        {
            Axapta ax;
            AxaptaRecord record;
            Object carId, carBrand, model, modelYear, mileage;
            try
            {
                // Create AX object and logon to AX
                ax = new Axapta();
                ax.Logon(null, null, null, null);
                // Create an AxaptaRecord object from the
                // table that will be used
                using (record = ax.CreateAxaptaRecord("CarTable"))
                {
                    // Execute the statement entered as parameter
                    record.ExecuteStmt("select * from %1
                      where %1.CarBrand like 'BMW'");
                    // Loop through the result of the statement.
                    while (record.Found)
                    {
                        // Set our local variables to be
                        // equal to the fields in the table
                        // for the current record.
                        carId = record.get_Field("CARID");
                        carBrand = record.get_Field("CARBRAND");
                        model = record.get_Field("MODEL");
                        modelYear = record.get_Field("MODELYEAR");
                        mileage = record.get_Field("MILEAGE");
                        // Write the result to the console
                        Console.WriteLine(carId + "t" +
                                          carBrand + "t" +
                                          model + "t" +
                                          modelYear + "t" +
                                          mileage);
                        // Go to the next record in the result set
                        record.Next();
                    }
                    // End the AX session
                    ax.Logoff();
                    // Make sure the console stays up
                    // until a key is pressed
                    Console.ReadKey();
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

Execute the program by pressing Ctrl + F5 and take a look at the result. It should look something like this:

Exception classes

The .NET Business Connector also consists of a number of exceptions that AX can raise. These exceptions are controlled by exception classes that will help you determine further actions if an exception occurs. In the previous example I have only used the standard .NET exception class, but if you would like to write solid code you should consider using the exceptions from the .NET Business Connector instead.

The topics covered in this article are:

• A brief description of Common Language Runtime (CLR)
• Adding .NET references to classes in AX
• Using a .NET class in X++
• Adding references to the .NET Business Connector
• Using the .NET Business Connector in .NET classes

When you are done with this article, you should be able to use .NET classes as reference classes in AX through the Common Language Runtime (CLR). The article will also guide you through the process of creating a .NET class in Visual Studio, and how to use it in AX. You will also learn how to use AX logic from external applications by using the .NET Business Connector.

All the Visual Studio examples in this article are written in C#.

Common Language Runtime

You might have done some .NET development before looking into X++ right? Maybe you're even a .NET expert? If so, you must have heard of CLR before. The CLR is a component of .NET that enables objects written in different languages to communicate with each other. CLR can be used in AX to combine functionality from .NET classes and libraries, including the ones you have yourself created in .NET. However, you cannot consume AX objects in .NET by using the CLR. Instead, you will then have to use the .NET Business Connector.

To learn more about the CLR, check out the following link: http://msdn.microsoft.com/en-us/library/ddk909ch(VS.71).aspx

One very useful feature in AX when dealing with integration between AX and .NET is the way AX implicitly converts the most common data types. For the data types listed in the next table you do not need to convert the data manually. For all other data types, you will have to convert them manually.

Enums are stored as integers in AX and are treated as integers when they are implicitly converted between .NET and AX.    

We prove this by executing the next example that shows the conversion between System.String and str. The same can be done for any of the other data types in the above table.

 static void ImplicitDataConversion(Args _args)
{
    System.String netString;
    str xppString;
    ;

    // Converting from System.String to str
    netString = "Hello AX!";
    xppString = netString;
    info(xppString);
    // Converting from str to System.String
    xppString = "Hello .NET!";
    netString = xppString;
    info(netString);
}

X++ is case insensitive, except when dealing with CLR. This means that writing System.string in the previous example will result in     a compile error, whereas writing Str instead of str will not.

The result will look like this:

Adding a reference to a .NET class in AX

To be able to use .NET classes in AX you have to make sure that the .NET assembly that you would like to use in AX exists under the References node in the AOT. If you can't find it there, you have to add it by adding a reference to the DLL file that contains the assembly in the AOT under References.

When adding a reference node in the AOT you have to make sure that the DLL exists on all client computers. If there is a client computer in which the DLL does not exist, it will result in compile errors when compiling code on that client computer.

Assembly exist in the Global Assembly Cache

Follow these steps to add a reference that exists in the Global Assembly Cache:

1. If the DLL has been added to the Global Assembly Cache, you can right-click on the Reference node in the AOT and select Add Reference.
2. In the form that opens (see next screenshot), you should be able to find the desired DLL. Add it by clicking on the Select button.
3. When you have selected the desired reference, click on the OK button. The assembly has now been added to the AOT, and can be used when writing X++ code.

        

Assembly not in Global Assembly Cache

If the file does not exist in the Global Assembly Cache follow these steps:

1. Click on the Browse button in the Add Reference form shown above and find the DLL file.
2. Click on Open. If the DLL is a valid assembly it will be added to the AOT under References.

Another option is to add the DLL to the Global Assembly Cache first and select it as described in the previous section, Assembly exist in the Global Assembly Cache.

Using a .NET class in X++

After having added a reference to the .NET assembly you want to use in AX, you can start writing the X++ code that will use the assembly.

When referencing the classes in the assembly you will need to write the whole namespace and class name. In my example I'm using an assembly that has been added to the AOT in the SYS layer. The example shows a nice feature that enables AX to send info messages to the Windows Event Log.

This can be particularly useful when you would like to use the Windows Event Log to monitor AX batch Jobs.

First, we add a new static method called writeLogEntry to the Global class:

static void writeLogEntry(Exception e, str caller, int line, str text)
{
    // Use the standard .NET class EventLog from
    // the System.Diagnostics assembly
    System.Diagnostics.EventLog     eventLog;
    // Also use a .NET enumeration from the
    // System.Diagnostics assembly
    System.Diagnostics.EventLogEntryType    entryType;
    System.Exception    clrException;
    str stack;
    Batch batch;
    str batchInfo;
    ;
    try
    {
        // Create a new object of the EventLog class
        eventLog = new System.Diagnostics.EventLog();
        eventLog.set_Source("Dynamics AX");
        // Set the enumeration value based on the Exception
        // type in AX
        switch (e)
        {
            case Exception::Info :
                entryType =
                  System.Diagnostics.EventLogEntryType::Information;
                break;
            case Exception::Warning :
                entryType =
                  System.Diagnostics.EventLogEntryType::Warning;
                break;
            case Exception::Error :
                entryType =
                  System.Diagnostics.EventLogEntryType::Error;
                break;
        }
        // If the current user is running a batch job
        // we can assume that the info message came
        // from the batch job and add additional information
        // to the event log

        while select batch
            where batch.Status == BatchStatus::Executing &&
                  batch.ExecutedBy == curuserid()
        {
            batchInfo += batch.GroupId + ': '+
              classid2name(batch.ClassNumber) + 'n';
        }
        if (batchInfo)
            eventLog.WriteEntry(strfmt("Batch info from AX: %1 nn
              The message originated from :%2 nat line %3 nn
              Message: %4", batchInfo, caller, line, text),
              entryType);
        else
            eventLog.WriteEntry(strfmt("Info from AX: nn
              The message originated from :%1 nat line %2 nn
              Message: %3", caller, line, text), entryType);
    }
    catch(Exception::CLRError)
    {
        // If not able to write the info to the eventlog
        // print an error in the print window instead.
        print "EventWriter:
          Unable to write entry to the windows eventlog";
    }
}

Then we add a line of code at the end of the add method in the Info class so that the end of the method will look like this:

       writeLogEntry(_exception, conpeek(packedAction,2) ,
          conpeek(packedAction,3), _txt);
        this.addSysInfoAction(_helpUrl, actionClassId, packedAction);
    }
    return super(_exception, (buildprefix?getprefix():'')+_txt);
}

To test the feature, simply create a new Job that prints something to the infolog:

static void TestEventLog(Args _args)
{
    ;
    info("This is a test");
}

You will now see an infolog message in AX, and if you open the Windows Event Viewer you should see the following message in the list:

Double-clicking on the event will bring up information about the origin of the info and the message that was printed to the infolog in AX.

This example could easily be extended so you can enable or disable the feature for different users and select the level of messages to be sent to the EventLog.

.NET Business Connector

If you have external applications that need to integrate directly to AX logic you can easily achieve this by using the .NET Business Connector. A typical scenario can be that you would like your .NET application to execute some code in AX and have the result sent back to the .NET application.

The .NET Business Connector requires additional licenses. Make sure that the AX installation in which you want to make use  of the .NET Business Connector has the necessary licenses before you start developing the solution.

In standard AX, the .NET Business Connector is also used by the Enterprise Portal through the Web Parts in SharePoint so that they can expose AX data and logic directly to the Web. It is also used by the standard Application Integration Framework (AIF).

The way that the .NET Business Connector works is that it offers a set of .NET managed classes that .NET applications use in order to log on to AX and execute methods in AX classes.

Here is a list of the different managed classes that can be used in .NET when you want to integrate to AX through the .NET Business Connector. The list is taken from the Dynamics AX SDK.

In this article, I'll explain the basic yet essential processes involved in building a .NET application that uses an Oracle database, including:

• How to add project references to support Oracle class libraries in your .NET project
• How to create Oracle Database connection strings
• How to work with Connection, Command, and DataReader objects

You will have the opportunity to apply what you have learned in three practice labs, ranging in difficulty from the relatively simple to the more complex. The article's screenshots are taken from Visual Studio 2008, but the experience is very similar in Visual Studio 2005.

For information and labs about how to secure your application, see my article "Securing a .NET Application on the Oracle Database". (Also, see the OTN .NET Developer Center for technical articles covering a range of Oracle.NET application lifecycle issues.)

Note that the free Oracle Developer Tools for Visual Studio, available for download from OTN, provides a Visual Studio add-in that makes the development of .NET apps on Oracle much easier and more intuitive. That subject is beyond our scope here, however.

.NET Data Provider

In addition to basic Oracle client connectivity software, .NET applications require the use of what is known as a managed data provider (where "managed" refers to code managed by the .NET framework). The data provider is the layer between the .NET application code and the Oracle client connectivity software. In almost every case, the best performance is achieved by using a provider optimized for a specific database platform instead of the generic .NET OLE DB data provider.

Oracle, Microsoft, and third-party vendors all offer .NET data providers optimized for Oracle. Oracle and Microsoft make their Oracle data providers available for free. (Microsoft's provider for the .NET Framework 2.0 is included in the framework, but it still requires Oracle client software installation.) In this article, we will use of the Oracle Data Provider for .NET (ODP.NET), which is included with the Oracle Database or as a separate download.

ODP.NET provides standard ADO.NET data access, while exposing Oracle database-specific features, such as XML DB, data access performance optimizations, and Real Application Clusters connection pooling.

When ODP.NET and Oracle client software are installed, application development using Visual Studio can begin. It's a good idea to confirm client connectivity before starting development. If you can connect to Oracle using Oracle client software such as SQL*Plus on the same machine as Visual Studio, then you know that your Oracle client-side software is properly installed and configured.

If you are new to Oracle, see the section "Installing .NET Products" in the Oracle Database 2 Day Developer's Guide for background information regarding installing and configuring ODP.NET specifically, or to the Oracle Database Documentation Library for general information about Oracle Database.

Creating a Project in Visual Studio 2005 or 2008

Let's create an ODP.NET application that retrieves data from an Oracle database. Later, we'll see how to perform error handling with ODP.NET and handle an additional data retrieval scenario.

After starting Visual Studio, the first task is to create a project. You can either select File | New | Project as shown below or click the New Project button located directly under File.

A New Project dialog box appears. On the left side of the dialog box under Project Types, select the programming language of your choice. In our example, "Visual Basic" was chosen. On the right side under Visual Studio installed templates, choose a project template. To keep things simple, a "Windows Forms Application" is selected.

You'll want to specify meaningful names for the project name (we used OraWinApp) and the solution name (we used OraWinApp). A solution contains one or more projects. When a solution contains only one project, many people use the same name for both.

Adding a Reference

Because our project must connect to an Oracle database, it is necessary to add a reference to the ODP.NET DLL containing the data provider of our choice. Within the Solution Explorer, select the project name, right click and select Add Reference. Alternatively, you can go to the menu bar and select Project and then select Add Reference.

The Add Reference dialog box appears.

ODP.NET is found under the Oracle.DataAccess component name. Select Oracle.DataAccess from the list, then click OK to make the ODP.NET data provider known to your project.

Visual Basic/C# Statements

After adding references, it is standard practice to add Visual Basic Imports statements or C# using statements. Technically, these statements are not required but they do allow you to refer to database objects without using lengthy, fully qualified names.

By convention, these statements appear at or near the top of a code file, before the namespace or class declaration.

Imports Oracle.DataAccess.Client ' Visual Basic ODP.NET Oracle managed provider

using Oracle.DataAccess.Client; // C# ODP.NET Oracle managed provider

If you added the reference, Intellisense will help you complete the addition of an Imports or using statement as shown in Figure 5.

Connection Strings and Objects

An Oracle connection string is inseparable from Oracle names resolution. Suppose you had a database alias of OraDb defined in a tnsnames.ora file as follows:

OraDb=
  (DESCRIPTION=
    (ADDRESS_LIST=
      (ADDRESS=(PROTOCOL=TCP)(HOST=ORASRVR)(PORT=1521))
    )
    (CONNECT_DATA=
      (SERVER=DEDICATED)
      (SERVICE_NAME=ORCL)
    )
  )

The OraDb alias defines the database address connection information for the client. To use the OraDb alias defined in the tnsnames.ora file shown above, you would use the following syntax:

Dim oradb As String = "Data Source=OraDb;User Id=scott;Password=tiger;" ' Visual Basic

string oradb = "Data Source=OraDb;User Id=scott;Password=tiger;"; // C#

You can modify the connection string to obviate the need for the tnsnames.ora file, however. Simply replace the name of the alias with how it would be defined in a tnsnames.ora file.

' Visual Basic
Dim oradb As String = "Data Source=(DESCRIPTION=" _
           + "(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=ORASRVR)(PORT=1521)))" _
           + "(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=ORCL)));" _
           + "User Id=scott;Password=tiger;"

// C#
string oradb = "Data Source=(DESCRIPTION="
             + "(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=ORASRVR)(PORT=1521)))"
             + "(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=ORCL)));"
             + "User Id=scott;Password=tiger;";

As you can see above, the username and password are embedded in the connection string in clear text. This is the simplest approach to creating a connection string. However, the clear text approach is undesirable from a security perspective. In particular, you must understand that compiled .NET application code is only marginally more secure than the clear text source code files. It is very easy to decompile .NET DLL and EXE files and view the original clear text contents. (Encryption is in fact the appropriate solution, but that subject would be a quite lengthy digression from our discussion here.)

Next, you must instantiate a connection object from the connection class. The connection string must be associated with the connection object.

Dim conn As New OracleConnection(oradb) ' Visual Basic

OracleConnection conn = new OracleConnection(oradb); // C#

Notice that the connection string is associated with the connection object by being passed through the object's constructor, which is overloaded. The constructor's other overload allows the following alternative syntax:

Dim conn As New OracleConnection() ' Visual Basic
conn.ConnectionString = oradb

OracleConnection conn = new OracleConnection(); // C#
conn.ConnectionString = oradb;

After associating a connection string with a connection object, use the Open method to make the actual connection.

conn.Open() ' Visual Basic

conn.Open(); // C#

We'll cover error handling later.

Command Object

The Command object is used to specify the SQL command text that is executed, either a SQL string or a stored procedure. Similar to the Connection object, it must be instantiated from its class and it has an overloaded constructor. In this sample, ODP.NET will perform a SQL query to return the department name (DNAME) from the departments table (DEPT) where the department number (DEPTNO) is 10.

Dim sql As String = "select dname from dept where deptno = 10" ' Visual Basic
Dim cmd As New OracleCommand(sql, conn)
cmd.CommandType = CommandType.Text

string sql = "select dname from dept where deptno = 10"; // C#
OracleCommand cmd = new OracleCommand(sql, conn);
cmd.CommandType = CommandType.Text;

Using different overloads, the syntax can be structured slightly differently. The Command object has methods for executing the command text, which will be seen in the next section. Different methods are appropriate for different types of SQL commands.

Retrieving a Scalar Value

Retrieving data from the database can be accomplished by instantiating an OracleDataReader object and using the ExecuteReader method, which returns an OracleDataReader object. Returned data is accessible by passing either the column name or zero-based column ordinal to the OracleDataReader.

Dim dr As OracleDataReader = cmd.ExecuteReader() ' Visual Basic
dr.Read()

Label1.Text = dr.Item("dname") ' retrieve by column name
Label1.Text = dr.Item(0) ' retrieve the first column in the select list
Label1.Text = dr.GetString(0) ' return a .NET data type
Label1.Text = dr.GetOracleString(0) ' return an Oracle data type

There are typed accessors for returning .NET native data types and others for returning native Oracle data types, all of which are available in C#, Visual Basic, or any other .NET language. Zero-based ordinals are passed to the accessors to specify which column to return.

OracleDataReader dr = cmd.ExecuteReader(); // C#
dr.Read();

label1.Text = dr["dname"].ToString(); // C# retrieve by column name
label1.Text = dr.GetString(0).ToString();  // return a .NET data type
label1.Text = dr.GetOracleString(0).ToString();  // return an Oracle data type

In this simplified example, the returned value of DNAME is a string and is used to set the value of the label control's text property, which is also a string. But if DEPTNO, which is not a string, had been retrieved instead, there would be a data type mismatch. The .NET runtime attempts to implicitly convert from one data type to another when the source and destination data types don't match. Sometimes the data types are incompatible and the implicit conversion fails, throwing an exception. But even when it works, it's still better to use explicit data type conversions instead of implicit data type conversion.

An explicit cast to integer is shown below:

Label1.Text = CStr(dr.Item("deptno")) ' Visual Basic integer to string cast

C# is not as forgiving as Visual Basic on implicit conversions. You'll find yourself doing explicit conversions: 

label1.Text = dr.GetInt16("deptno").ToString(); // C#

You can explicitly cast scalar values as well as arrays.

Close and Dispose

Either the connection object's Close or the Dispose method should be called to close the connection to the database. The Dispose method calls the Close method.

conn.Close()   ' Visual Basic
conn.Dispose() ' Visual Basic

conn.Close();   // C#
conn.Dispose(); // C#

You don't have to explicitly call Close or Dispose if you use VB's Using keyword or C#'s using keyword.

using (OracleConnection conn = new OracleConnection(oradb)) // C#
{
    conn.Open();

    OracleCommand cmd = new OracleCommand();
    cmd.Connection = conn;
    cmd.CommandText = "select dname from dept where deptno = 10";
    cmd.CommandType = CommandType.Text;

    OracleDataReader dr = cmd.ExecuteReader();
    dr.Read();

    label1.Text = dr.GetString(0);
}

In addition, OracleCommand includes a Dispose method; OracleDataReader includes a Close and Dispose method. Closing and disposing .NET objects free up system resources, ensuring more efficient application performance, which is especially important under high load conditions. You can experiment with some of the concepts we've learned here in Lab 1 (Retrieving Data from the Database) and Lab 2 (Adding Interactivity).

Error Handling

When an error occurs, .NET applications should gracefully handle the error and inform the user with a meaningful message. Try-Catch-Finally structured error handling is a part of .NET languages; here is a relatively minimalist example of using the Try-Catch-Finally syntax:

' Visual Basic
Try
    conn.Open()

    Dim cmd As New OracleCommand
    cmd.Connection = conn
    cmd.CommandText = "select dname from dept where deptno = " + TextBox1.Text
    cmd.CommandType = CommandType.Text

    If dr.Read() Then
        Label1.Text = dr.Item("dname") ' or use dr.Item(0)
    End If
Catch ex As Exception ' catches any error
    MessageBox.Show(ex.Message.ToString())
Finally
    ' In a real application, put cleanup code here.
End Try

// C#
try
{
    conn.Open();

    OracleCommand cmd = new OracleCommand();
    cmd.Connection = conn;
    cmd.CommandText = "select dname from dept where deptno = " + textBox1.Text;
    cmd.CommandType = CommandType.Text;

    if (dr.Read()) // C#
    {
        label1.Text = dr["dname"].ToString();
                   // or use dr.GetOracleString(0).ToString()
    }
}
catch (Exception ex) // catches any error
{
    MessageBox.Show(ex.Message.ToString());
}
finally
{
    // In a real application, put cleanup code here.
}

Although this approach will gracefully capture any errors in attempting to get data from the database, it is not user friendly. For example, look at the following message displayed when the database is unavailable:

An ORA-12545 is quite meaningful for an Oracle DBA or developer, but not for an end user. A better solution is to add an additional Catch statement to trap for the most common database errors and provide user-friendly messages.

Catch ex As OracleException ' catches only Oracle errors
    Select Case ex.Number
        Case 1
            MessageBox.Show("Error attempting to insert duplicate data.")
        Case 12545
            MessageBox.Show("The database is unavailable.")
        Case Else
            MessageBox.Show("Database error: " + ex.Message.ToString())
    End Select
Catch ex As Exception ' catches any error
    MessageBox.Show(ex.Message.ToString())

catch (OracleException ex) // catches only Oracle errors
{
    switch (ex.Number)
    {
        case 1:
            MessageBox.Show("Error attempting to insert duplicate data.");
            break;
        case 12545:
            MessageBox.Show("The database is unavailable.");
            break;
        default:
            MessageBox.Show("Database error: " + ex.Message.ToString());
            break;
    }
}
catch (Exception ex) // catches any error not previously caught
{
    MessageBox.Show(ex.Message.ToString());
}

Notice the two Catch statements in the code sample above. If there aren't any Oracle errors to catch, the first statement branch is skipped, leaving any other non-Oracle error to be caught by the second statement. Catch statements must be ordered in the code from most specific to most general. After implementing the user-friendly exception handling code, the ORA-12545 error message appears as follows:

The Finally code block is always executed regardless of whether or not an error occurred. It is where cleanup code belongs. If you don't use Using or using, you should dispose your connection and other objects in the Finally code block.

Retrieving Multiple Values Using a DataReader

So far our examples have only showed how to retrieve a single value. An OracleDataReader can retrieve values for multiple columns and multiple rows. First consider a multiple column, single row query:

select deptno, dname, loc from dept where deptno = 10

To obtain the values of the columns, either zero-based ordinals or column names can be used. Ordinals are relative to the order in the query. Thus, the LOC column's value can be retrieved in Visual Basic by using either dr.Item(2) or dr.Item("loc").

Here is a code snippet that concatenates the DNAME and LOC columns from the previous query:

Label1.Text = "The " + dr.Item("dname") + " department is in " + dr.Item("loc") ' VB

label1.Text = "The " + dr["dname"].ToString() + " department is in " +
              dr["loc"].ToString();  // C#

Now consider a query that returns multiple rows:

select deptno, dname, loc from dept

To process multiple rows returned from an OracleDataReader, some type of looping construct is needed. Furthermore, a control that can display multiple rows is desirable. An OracleDataReader is a forward-only, read-only cursor, so it can't be bound to an updateable or fully scrollable control such as a Windows Forms DataGrid control. An OracleDataReader is compatible with a ListBox control, as the following code snippet illustrates:

While dr.Read() ' Visual Basic
   ListBox1.Items.Add("The " + dr.Item("dname") + " department is in " + dr.Item("loc"))
End While

while (dr.Read()) // C#
{
    listBox1.Items.Add("The " + dr["dname"].ToString() + " department is in " +
                       dr["loc"].ToString());
}

Lab 3 (Retrieve Multiple Columns and Rows with an OracleDataReader) highlights some of these concepts.

Building and Running on x64

When running Visual Studio 2008 on an x64 operating system, the Active solution platform defaults to Any CPU. Change that to x86 before building your project.

Conclusion

This article has introduced you to the process of accessing Oracle databases using .NET programming languages. You should now have the capability to connect to the database and retrieve multiple columns and rows.

John Paul Cook

Oracle Streams Advanced Queuing provides database-integrated message queuing functionality. Because Oracle Streams Advanced Queuing is implemented in database tables, queue data enjoys the Oracle Database benefits of high availability, scalability, and reliability.

Oracle Data Provider for .NET (ODP.NET), Oracle’s ADO.NET-compliant data provider, includes Oracle Streams Advanced Queuing classes to expose the messaging capabilities of Oracle Streams Advanced Queuing. Oracle Developer Tools for Visual Studio, a plug-in for Microsoft Visual Studio 2008 and Visual Studio 2005, includes administration tools that assist with tasks such as creating and modifying queues and queue tables.

This article guides you through creating a set of .NET applications that make up a stock ticker system that demonstrates many Oracle Streams Advanced Queuing features. You will first create a queue in Oracle Database that holds stock ticker symbols and the corresponding stock prices. Every time a stock price changes, it will be loaded onto this queue by the StockQueueLoader application that you create next. You will also create the StockTickerListener application that receives notifications whenever a new stock price arrives in the queue and then retrieves the stock information and displays it on a ticker screen. StockTickerListener can receive notifications for all stocks that are loaded in the queue, but the queue can also be configured with rules specifying that StockTickerListener receives notifications only when specific stocks and, optionally, price ranges for specific stocks are loaded in the queue. To make it easy for a user to dynamically modify these rules, you will also run a helper application called StockQueueSubscriberAdmin.

Setup

To follow along with the steps in this article, you will need the following:

• SYSDBA privileges for Oracle Database Release 9.2 or later, which may be required to grant some of the Oracle Streams Advanced Queuing privileges
• Microsoft Visual Studio 2008 or Visual Studio 2005
• Oracle Developer Tools for Visual Studio and Oracle Data Provider for .NET Release 11.1.7.10 or later

Before you build the sample applications, you will create connections to Oracle Database from Visual Studio and grant the appropriate privileges to enable the use of queuing.

To connect to Oracle Database from Visual Studio, create a new connection in Data Connections, the top-level node of Server Explorer. (If Server Explorer is not yet visible, select View -> Server Explorer from the main menu.)

Right-click Data Connections, and select Add Connection. In the dialog box that appears, confirm that Oracle Database (Oracle ODP.NET) appears in the Data source field. If you do not see Oracle Database (Oracle ODP.NET), click the Change button and select Oracle Data Provider for .NET from the list of providers. Select the database you want to connect to from the Datasource name list. Click Use a specific user name and password. In the User name field, enter SYS. In the Password field, enter the password for SYS, and ensure that Role is set to SYSDBA. Click Test connection to verify that you can connect, and click OK to complete the connection setup.

To create and modify queues and queue tables and to enqueue and dequeue from them, you need the EXECUTE privilege on the DBMS_AQ and DBMS_AQADM PL/SQL packages. (If you wanted to modify queues you did not create, you would also require privileges on the AQ_ADMINISTRATOR_ROLE role.) You will grant the required privileges, using the Grant/Revoke Privilege dialog box in Visual Studio.

Right-click the SYS connection node, and choose Privileges from the context menu. In the Grant/Revoke Privileges dialog box that appears, set Object Type to Package. Leave Schema set to SYS. Click the first radio button, labeled Grant/Revoke privileges to a user/role on one or more database object(s). Hold down the Ctrl key, and in the Object Names list, highlight both DBMS_AQ and DBMS_AQADM. From the User/Role list, select User and choose HR or some other username. In the list of privileges, in the Grant column, check the check box next to the EXECUTE privilege. Click OK to accept the changes, and close the dialog box.

Now connect to Oracle Database as HR (or whichever user you just granted the Oracle Streams Advanced Queuing package privileges). In Server Explorer, right-click Data Connections and select Add Connection. Follow the same steps to connect as HR that you used to connect as SYS, except to set Role to Default.

Creating the STOCK User-Defined Type

Oracle Database queues typically hold objects of a single type (unless they are defined as ANYTYPE queues) and can be an XMLType, a user-defined type (UDT), or a RAW type. For more information on Oracle Streams Advanced Queuing queue types, including the benefits and limitations of each, see the Oracle Streams Advanced Queuing User’s Guide.

The queue for this article will be made up of a user-defined type called STOCK, whose definition will include a stock symbol name as well as the price of the stock. (For a deep dive into Oracle user-defined types with Visual Studio and .NET, see “It Takes All Types” in the May/June 2008 issue of Oracle Magazine).

To create the user-defined type, in Server Explorer, under the HR data connection, right-click the User Defined Types node and choose New Object Type from the menu. This will launch Object Designer. In the Type name field, enter STOCK. Click the Add button to add an attribute, and in the Attribute Properties Name field, enter SYMBOL. From the Type list, choose VARCHAR2. Click the Add button again to add another attribute. In the Name field for this new attribute, enter PRICE and choose NUMBER from the Type list. Click OK to create the type. The type will now be visible in Server Explorer under the User Defined Types node and will also be available in datatype lists in various Oracle designers, such as Queue Designer.

Creating the Queue and the Queue Table

Next, create a queue named STOCK_Q and its queue table, STOCK_QTAB. Under the HR data connection node in Server Explorer, expand the Advanced Queues node, which will expose the Queues and Queue Tables collection nodes (see Figure 1). Right-click the Queues node, and select New Queue from the menu. This will launch Queue Designer (see Figure 2).

Figure 1: Server Explorer Advanced Queues and User-Defined Types nodes (left); Queues node context menu (right)

Figure 2: Queue Designer

In the Queue name field, enter STOCK_Q. From the Queue type list, choose Normal Queue. For Payload Type, click the Complex radio button, and then from the list next to it, choose the STOCK user-defined type.

Click the Queue Table tab in the lower half of the designer. In the Queue Table area, click the New radio button and enter STOCK_QTAB as the name of the queue table. Leave the rest of the default settings as they are. (The most important settings are the Multi-Consumer and Secure check boxes, which must be checked, because multiple stock ticker applications can be run at the same time and all of them will need access to the contents of the queue.)

Still in the Queue Designer, click the Subscribers tab. Click the grid in the lower half of the designer, which will cause SUBSCRIBER1 to be entered for Consumer Name. Leave the Rule field blank. Click a new line in the grid to create another subscriber entry. Change the name of this one from SUBSCRIBER2 to DEFAULT. Leave the rule for this subscriber entry blank.

Click Save to create the queue and the queue table. The STOCK_Q queue and the STOCK_QTAB queue table will now be visible in Server Explorer (see Figure 1). The designer automatically starts the queue after creating it.

Note that an exception queue named AQ$_STOCK_QTAB_E has been automatically created for you and that the exceptions will be stored in the STOCK_QTAB queue table. Oracle Streams Advanced Queuing exceptions are generated in a variety of circumstances, such as when a message expires before it is dequeued. For more information on Oracle Streams Advanced Queuing exceptions, see Oracle Streams Advanced Queuing User’s Guide.

Building the StockQueueLoader Application

With the queue and the queue table created, you will now build the StockQueueLoader application that generates fictional stock price fluctuations in a fantasy stock market consisting of 10 ticker symbols and loads these stock prices (using a STOCK user-defined type) into the STOCK_Q queue you just created. (In a real-world scenario, actual stock price updates could be obtained via Web services and then inserted into an Oracle queue.)

(Note that all of the applications created and used in this article—StockQueueLoader, StockTickerListener, and QueueSubscriberAdmin—are available prebuilt in the article’s application download.)

To begin construction of the queue loader application (StockQueueLoader), choose File -> New -> Project from the main menu. In the dialog box that appears, under Project type Visual C#, choose Windows, and then on the right side of the dialog box, choose the Console Application template. In the Name field, enter StockQueueLoader.

In the newly opened project, go to Solution Explorer; right-click the ConsoleApplication project; and from the menu, choose Add Reference. On the .NET tab in the Add Reference dialog box, scroll down until you see the Oracle.DataAccess assembly. You may see multiple versions, but select version 2.111.7.10—the version in which Oracle Streams Advanced Queuing support was first introduced—or later.

Next, download the sample applications at otn.oracle.com/oramag/oracle/09-nov/o69odt.zip, unzip the file, and copy the contents of the AQ_ORAMAG\CodeListings\aqloader.txt file on top of the default template code. (Excerpts of the new code appear in Listing 1.) Notice that the key ODP.NET classes being used are OracleAQQueue and OracleAQMessage. Furthermore, note that the payload for the OracleAQMessage class is another .NET class called STOCK. STOCK is the .NET custom class for the STOCK Oracle user-defined type. (Custom classes enable .NET code to pass user-defined type values to and from Oracle Database.)

Code Listing 1: StockQueueLoader application code excerpt

OracleAQQueue queue = new OracleAQQueue("HR.STOCK_Q", con);
queue.MessageType = OracleAQMessageType.Udt;
queue.EnqueueOptions.Visibility = OracleAQVisibilityMode.Immediate;
OracleAQMessage enqMsg = new OracleAQMessage();

Console.WriteLine("Connected to Oracle.... Will start enqueuing in 10 seconds");
System.Threading.Thread.Sleep(10000);

string[] symbols = new string[10] { "ORCL", "MSFT", "INTC", "CSCO", "ADBE", "GOOG", "AAPL", "AMZN", "EBAY", "JAVA" };

double[] prices = new double[10] { 19.5, 19, 18.25, 15, 24, 383.25, 121, 79.75, 15, 9 };

Random rand = new Random();
while (true)
{
    for (int i = 0; i < 10; i++)
    {
        //...code to randomly increase or decrease prices[i] goes here
        }

        //We don't want multiple copies of the same stock on the queue
        //at the same time, so the message will expire after 5 seconds
        enqMsg.Expiration = 5;

        enqMsg.SenderId = new OracleAQAgent("QUEUELOADER");
        enqMsg.Payload = new STOCK(symbols[i], (decimal)prices[i]);
        queue.Enqueue(enqMsg);

Now generate the STOCK custom class from the STOCK user-defined type, by using a wizard. To start the wizard, in Server Explorer, under the HR data connection, expand the User-Defined Types node (see Figure 1). Find and right-click the STOCK node. From the menu, choose Generate Custom Class. In the wizard, click Next to move past the splash screen. In the next screen, uncheck the Inherit from Project check box, directly above the Namespace field. Then change Namespace to Stock, click Next until you get to the final screen, and click the Finish button. This will generate a Stock.cs file and place it in your project.

Now add the following constructor to the Stock class, below the automatically generated constructors:

public STOCK(string sym, decimal pr)
{
   SYMBOL = sym;
   PRICE = pr;
}

Finally, build the application, by selecting Build from the Visual Studio main menu and then selecting Rebuild Solution. Run the application, by choosing Debug from the main menu, and then select Run Without Debugging.

As you see messages appear in the console indicating that stock prices are being loaded into the queue, you can inspect the STOCK_QTAB table in Oracle Database to see these values being added there. In Server Explorer, under the HR data connection, expand the Tables node and double-click the STOCK_QTAB node to open the data window. If you right-click the data window and choose Refresh from the context menu, you can watch this queue table grow and notice that after five seconds, each entry in this table is replaced with an advanced queuing exception. Because the StockQueueLoader .NET code sets an expiration of five seconds for each item loaded into the queue, these exceptions indicate that the item was not dequeued before this expiration.

Building the StockTickerListener Application

Consumer applications have several options for finding out if there is something in a queue they are interested in. They can poll a queue by inspecting it from time to time to see if there is a message they need; they can listen to the queue with a dedicated thread; or they can register a callback, a subroutine that gets called and is passed a notification when a message that meets certain criteria is put into the queue.

There are various ways a consumer application can choose whether a message is of interest. Messages can be addressed to specific recipients or recipient groups. Messages can also be assigned correlations, which are ad hoc identifiers assigned by the producing applications. Messages also have priorities for filtering. Finally, messages can be inspected via rules, which are essentially WHERE clauses added to SELECT statements that query against the queue.

A consumer application can specify an interest in certain messages in a queue by becoming a subscriber. Each subscriber can define a named rule. You will now build an application—StockTickerListener—that receives callbacks whenever stock prices appear in the queue that match a subscriber rule. These stock prices will be output to a window much like a stock ticker.

To build the StockTickerListener application, in a new instance of Visual Studio, first create a new console application, including an Oracle.DataAccess reference (in the same way you did in the previous section). Now add the Stock.cs custom class file (from the StockQueueLoader application) to your new project, by right-clicking the new project name in Solution Explorer, choosing Add an Existing Item, and then browsing to the file. Visual Studio will then make a local copy of that file in your project, saving you the trouble of re-creating it.

Code Listing 2: StockTickerListener application code excerpt

OracleAQQueue queue = new OracleAQQueue("HR.STOCK_Q", con);
queue.MessageType = OracleAQMessageType.Udt;
queue.NotificationConsumers = new string[1] { "SUBSCRIBER1" };

queue.MessageAvailable +=
  new OracleAQMessageAvailableEventHandler(QueueCallback.MsgReceived);
.....

static void MsgReceived(object src, OracleAQMessageAvailableEventArgs arg)
{
    try
    {
        Console.WriteLine("Notification Received...");
        byte[] notifiedMsgId = arg.MessageId[0];

        OracleConnection con = new OracleConnection(constr);
        con.Open();

        // Prepare to dequeue message by its MessageID
        OracleAQQueue queue = new OracleAQQueue("HR.STOCK_Q", con);
        queue.MessageType = OracleAQMessageType.Udt;
        queue.UdtTypeName = "HR.STOCK";
        queue.DequeueOptions.MessageId = notifiedMsgId;
        queue.DequeueOptions.ConsumerName = "SUBSCRIBER1"; 

        queue.DequeueOptions.DequeueMode = OracleAQDequeueMode.Browse;

        //Dequeue
        OracleAQMessage deqMsg = queue.Dequeue();
        STOCK st = (deqMsg.Payload as STOCK);

        Console.WriteLine(st.SYMBOL + ": " + st.PRICE);

From the sample applications you downloaded earlier, copy the contents of the AQ_ORAMAG\CodeListings\stocktickerlistener.txt file on top of the console template code. (Excerpts of this code appear in Listing 2.) The main part of the code contains two key methods. The first is

queue.NotificationConsumers

which is set to SUBSCRIBER1. This indicates that callbacks should be received only when the SUBSCRIBER1 subscription rules are satisfied. The second key method is

queue.MessageAvailable += new
OracleAQMessageAvailableEventHandler
(QueueCallback.MsgReceived);

This registers the MsgReceived method as a callback.

In the code for the MsgReceived callback, note that the advanced queuing AQ MessageID is included as part of the arguments that are passed to the method. This ID is set to

queue.DequeueOptions.MessageId

to specify the message you want. Finally,

queue.DequeueOptions.DequeueMode = OracleAQDequeueMode.Browse

indicates that the message should not be removed from the queue after viewing, because other client applications may need to view that stock.

Build this application, by selecting Build from the Visual Studio main menu and then selecting Rebuild Solution. Run the application, by choosing Debug from the main menu, and then select Run Without Debugging.

Now go back to the earlier instance of Visual Studio, rerun the StockQueueLoader application, and place both console application windows side by side. You should see the StockTickerListener application display every stock price that is loaded by the StockQueueLoader application (see Figure 3). This is because SUBSCRIBER1’s rule is currently set to null. Because these rules are essentially WHERE clauses in a query over the queue contents, a null rule means that every item on the queue will be included. Keep both applications running while you move on to the next section.

Figure 3: StockQueueLoader (top) and StockTickerListener (bottom)

Modifying a SUBSCRIBER Rule at Runtime

Earlier, you saw a subscriber rule in the Queue Designer in Visual Studio. This rule selects specific STOCK user-defined type stock symbols and enables users to specify a range of stock prices in which they are interested. Now you will run a helper application that makes it easier to change this rule at runtime while the stock ticker application is running.

The download provided with this article includes a Windows Forms application called StockQueueSubscriberAdmin.This application presents a user interface (see Figure 4) that includes a list of stock symbols; an optional field for providing a stock price; and a list of conditions that enables the user to set up a subscriber rule for receiving stock prices that are less than, greater than, or equal to the provided value.

Figure 4: StockQueueSubscriberAdmin user interface

Run the StockQueueSubscriberAdmin application. Select the ORCL symbol from the stock list, and click Add to Rule. In the text box, you will see

tab.user_data.SYMBOL=''ORCL''

This rule will cause your stock ticker to receive notifications only when ORCL stock values are placed in the queue. Next, select the JAVA symbol from the list and enter 3 in the Price field. Choose > (greater than) from the Condition list. Click Add to Rule. Now the text box contains

tab.user_data.SYMBOL=''ORCL'' OR
(tab.user_data.SYMBOL=''JAVA'' AND
tab.user_data.PRICE>3)

This rule will cause your stock ticker to receive notifications when all ORCL stock prices as well as any JAVA prices above $3 are loaded into the queue.

Finally, click Alter Subscription!. This will execute the DBMS_AQADM.ALTER_SUBSCRIBER procedure and pass the rule you have created. (The code that calls this procedure is shown in Listing 3.) To see the new rule, in Server Explorer right-click the STOCK_Q node, choose Design Queue, and then click the Subscribers tab.

Code Listing 3: StockQueueSubscriber

private void button2_Click_1(object sender, EventArgs e)
{
//Executes DBMS_AQADM.ALTER_SUBSCRIBER to modify the SUBSCRIBER1 subscription
string conString = "User Id=hr;Password=hr;Data Source=;";
OracleConnection con = new OracleConnection();
con.ConnectionString = conString;
con.Open();

OracleCommand cmd = con.CreateCommand();

string cmdtxt = "DECLARE " +
    "SUBSCRIBER SYS.AQ$_AGENT; " +
    "BEGIN " +
    @"SUBSCRIBER := SYS.AQ$_AGENT('""SUBSCRIBER1""', NULL, 0); " +
    "DBMS_AQADM.ALTER_SUBSCRIBER(" +
    @"queue_name => '""STOCK_Q""'," +
    "subscriber => SUBSCRIBER," +
    "rule => '" + textBox2.Text +"'," +
    "transformation => ''" +
    "); " +
    "END;";

OracleCommandBuilder oc = new OracleCommandBuilder();
cmd.CommandText = cmdtxt;

//Execute batched statement
cmd.ExecuteNonQuery();
}

If both of the earlier applications are still running, you should notice that your stock ticker application is now displaying only ORCL and JAVA ticker symbols. Each time the rule is modified, your running stock ticker will immediately reflect the change.

Now go back to the Queue Subscription GUI application, click Clear Rule, and click Alter Subscription!. This will set the rule to null. Watch as the stock ticker immediately resumes displaying all the stock symbols that are loaded into the queue.

Summary

This article showed you how you can leverage Oracle Streams Advanced Queuing database-integrated messaging from .NET applications. You loaded a queue from one application, subscribed to that queue from another application, and received callback notifications based on subscription rules you modified by using the DBMS_AQADM package.

Christian Shay

The solution demonstrated in this article uses WebORB for .NET, a free product by Midnight Coders that facilitates connectivity between Flex and .NET. WebORB functions as a gateway between Flex clients and .NET objects. Using WebORB, your Flex applications can use the standard remoting API to communicate with .NET applications. WebORB includes a code generator enabling integration between Flex and .NET applications.

Requirements

Flex Builder 3

• Try
• Buy

Microsoft Internet Information Services Server (version 5.x or later)

• Learn more

Microsoft .NET version 2.0 or later (installed on the system and integrated into IIS)

• Learn more

Visual Studio 2003 or 2005

• Learn more

WebORB for .NET (version 3.3 or later)

• Learn more

The code generator described in this article produces ActionScript code enabling remoting invocations for the methods for a given class. Code generation uses XSLT-style sheets which describe the structure and the content for the generated code.

To get started, review the class shown below. The class is already included into the WebORB distribution and is provided here for the reference and to establish the context:

C# class:

using System;
using System.Collections;
using System.Text;
using System.Data;
using System.Data.OleDb;
namespace Weborb.Examples
{
    public class DataBinding
    {
        private static string connectionString = "..Skipped for brevity...";
        public DataSet getCustomers()
        {
            DataSet dataSet = new DataSet();
            OleDbConnection connection = new OleDbConnection( connectionString );
            OleDbDataAdapter adapter = new OleDbDataAdapter();
            adapter.SelectCommand = new OleDbCommand( "SELECT * FROM Customers order by CustomerID", connection );
            try
            {
                adapter.Fill( dataSet );
            }
            finally
            {
                connection.Close();
            }
            return dataSet;
        }
    }
}

VB.NET class:

Imports System
Imports System.Collections
Imports System.Text
Imports System.Data
Imports System.Data.OleDb

Namespace Weborb.Examples
   Public Class DataBinding
      Private Shared connectionString As String =  "..Skipped for brevity..." 

       Public Function getCustomers() As DataSet
         Dim dataSet As DataSet =  New DataSet()
         Dim connection As OleDbConnection =  New OleDbConnection(connectionString)
         Dim adapter As OleDbDataAdapter =  New OleDbDataAdapter()
         adapter.SelectCommand = New OleDbCommand("SELECT * FROM Customers order by CustomerID", connection)

         Try
             adapter.Fill(dataSet)
         Finally
             connection.Close()
         End Try

         Return dataSet
     End Function

    End Class
End Namespace

You can see and inspect the class in the service browser which is a part of the WebORB management console. You can access the console at the following URL after installing the product: http://localhost/weborb30

Open the Management tab and navigate to the following path (see Figure 1):

weborb.dll > Weborb > Examples > DataBinding 

Figure 1. Navigation path

When you select the class, the console automatically generates and displays the code which can be used to invoke class methods using the Flex Remoting API (RemoteObject). The structure of the generated code is very simple. It consists of the 'service' and 'model' classes (plus any DTO (data transfer object) classes representing the complex types used in the method signatures) (see Figure 2):

Figure 2. Generated code structure

The generated 'service' class (has the same name as the selected .NET class) contains the logic for setting up an instance of RemoteObject and invoking the remote methods. The 'model' class aggregates server responses and can be used for data binding in the user interface. The diagram below illustrates the relationship between the generated classes and a View component created by developer (see Figure 3):

Figure 3. Relationship between the generated classes and a View component

Create a project in Flex Builder for your application as described in this article.

To keep the naming consistency with this article, name your project DataBindingProject.

Click the Download Code button in the WebORB management console to download a zip file with the generated code. Extract the contents of the zip file into the created Flex Builder project. If you are using Flex Builder 3, make sure to extract the code into the /src folder in the project structure. The image below demonstrates the project structure in Flex Builder 3 after the generated code has been added to the project (see Figure 4):

Figure 4. Project structure in Flex Builder 3

Open the MXML Application file and add the following code:

<mx:Script>
 <![CDATA[
  import weborb.examples.DataBindingModel;
  import weborb.examples.DataBinding; 

  [Bindable]
  private var model:DataBindingModel;
  private var dataBindingService:DataBinding;
  private function init():void
  {
    // create the model object
    model = new DataBindingModel();
    // create the service proxy - responsible for carrying out
    // remote method invocations and updating the model
    dataBindingService = new DataBinding( model );
    // invoke remote method
    dataBindingService.getCustomers();
  }
]]>
</mx:Script>

Modify the root mx:Application element to invoke the init() method shown above on the creationComplete event:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" creationComplete="init()"> 

Place a data grid component into the application by adding the following MXML code:

<mx:DataGrid x="10" y="37" width="467" height="143" dataProvider="{model.getCustomersResult}">
</mx:DataGrid>

Notice the mx:columns declaration is not present, as a result, the data grid will render all columns in the returned resultset. The datagrid uses data binding by setting its data provider to be a bindable property from the model. The property in the model is automatically updated by the generated code when a response from the remote method invocation is available.

Save the file and run the application. When the application is loaded, it makes a remote method invocation which runs a query. The query results are displayed in the data grid.

Conclusion

Code generation is a very efficient and productive way to start Flex and .NET integration. Proven code generators provide less error-prone, high quality code. The technique described in this article additionally provides support for complex type generation which saves a lot of time for more complex projects.

Mark Piller

Many people have observed that unit testing fits the mold of Heisenberg's Uncertainty Principle which says, among other things, that at the quantum level, the act of observing an event changes the nature of that event. Unit tests often have the same effect, but it extends beyond the runtime event being tested. It affects the design of the code that is to be tested, as well.

In this column, we'll examine 10 different ways you can change your .NET code to make it ready to be tested. By doing so, you will be creating a more loosely coupled, flexible and transparent architecture, which will benefit you not only in testing but in documentation, maintenance and, eventually, modification. With a little forethought and some careful implementation, the unit tests can drive more than the QA process; it can help you design a more robust application in the first place.

Use Interfaces

Those of us who came through the COM days with our registries intact remember that most strident of admonitions: "it's the interfaces, stupid." To write COM code, you had to employ interfaces as the primary coupling mechanism. For the un- (or under-)initiated, interfaces are lightweight constructs which define the publicly accessible method signatures exposed by a class; they contain no implementation details whatsoever. Instantiated objects can be referred to by references of the interface type, but the interface can never be instantiated itself.

Here is a simple interface example: we'll define an interface for interacting with different kinds of agents. The interface is called IAgent:

Agents all have a name, and can attempt to accomplish a mission in a given amount of time.

We'll implement two different kinds of agents, SecretAgents and AirlineAgents. Airline agents perform their mission by getting people on planes, and secret agents have clandestine rendezvous points. In addition, the SecretAgent, if in undercover mode, won't reveal her name.

In projects based entirely on concrete types, you may often hear complaints about the amount of time it takes to write the unit tests. This is due to the fact that test cases are meant to exercise the methods of a type; as long as each class is defined only by its own instantiable self, then unit tests are not reusable. There is a one-to-one correlation between the classes and the test cases.

Using interfaces, though, can allow you to reuse your unit tests. When you employ this architectural strategy, you are defining a common subset of available functionality that your concrete classes can implement. Unit tests, since they target methods on a type, can be written to exercise an implementation of a given interface. For every concrete type that implements that interface, the same test case can be used to exercise and verify the methods.

To test these different agents, we will want to run tests against the public interface IAgent. Tests for accomplishMission will all be remarkably identical; test known values for timeLimit and check true or false on the return. We need to create a specific unit test for each concrete type of agent in our application, but we don't want to rewrite the test for accomplishMission each time. Instead, start by defining a base class for your unit test that can adequately test accomplishMission:

Notice that the class is not marked with [TestFixture] though it does contain at least on [Test]. TestAgents will never be instantiated directly by the NUnit test runner because you have not marked it as a TestFixture, which is precisely the behavior you want. The test method itself relies on protected fields that will be filled in by the derived tests.

The test for AirlineAgent is only testing the accomplishMission method, since AirlineAgent currently has no other functionality. SecretAgent, on the other hand, has the extra ability to not return its name if it is undercover. The TestSecretAgent class therefore has an extra [Test] method to cover this. The code that actually exercises accomplishMission, though, is written only once, and can be maintained and upgraded in a single place.

Define a base test class

To create a test case for NUnit, you need only define a class and mark it with the TestFixture attribute from the NUnit Framework assembly. This designation provides a marker for the test runner to identify your test cases and run them. It provides no other functionality for your class, and since it is only metadata, your class does not inherit any meaningful functionality or data from it.

However, you will find very quickly that there are techniques and strategies you employ again and again for your unit tests. It might be that you have to perform a task to set up a test data store, and run it often to clean out cruft from earlier tests, or that you have to create or destroy session information to enable proper test values. These types of repetitive activities cry out to be centrally located so that you can eliminate the extra work of typing them again and again. In keeping with the principle of "don't repeat yourself', it is, in fact, imperative.

The solution is to create a base test class that your specific tests can derive from. This base class will host a series of utility methods and data structures that you can call on from any individual test. In addition, if all (or even most) of your tests require some common code in setUp and tearDown, you can implement those methods on the new base class. When your individual tests require the functionality, they can call up the chain and invoke it.

For example, with our agents application, perhaps we want our unit tests to be able to validate that the agent's name matches a certain pattern (no numbers, or if numbers, starts with "00", or something). We would make a base class for our tests that exposes an isValidNameString method:

Simply have your other tests derive from this one. In the case of our example above, we'll have TestAgents derive from AgentTestBase, thus providing our common testing functionality to all our current tests.

Another favorite technique of mine for testing .NET code is to make my mock objects be internal classes in the base test class. This is especially useful when I only have a few mock objects, and most of my tests can share the same versions. See "Mock the data access layer" below for an example of this.

Do not decorate the base class as a TestFixture. This just clutters your test runs with ignored tests (since it won't have any actual [Test] methods on it).

As much as feasible, make everything return a value

This obviously isn't a hard-and-fast, all-or-nothing rule, but as much as possible, avoid void methods and sub procedures. Unit tests are easier to write when the primary value to test is the return from a method. When a unit test has to scurry off to the database or another object or a text file to verify a simple method, then not only have you created more work for your unit test but you are also testing more than just your business logic; you are testing the infrastructure that leads from your business logic to that external data store. You are additionally adding the exact same infrastructure into your unit test, and if there is a problem, it will be a problem in the test as well as the thing being tested.

A method that returns the logical outcome of its processing can clearly enunciate its view of the world to its client, whether that be a user, other process or unit test. It may or may not reflect the true state of things, since obviously the full state of the application will probably be based on more than the code in this single method, but it will reflect what the method thinks is the state of things, which is what you should be unit testing. Testing the full application state is a job for integration testing.

Say that AirlineAgents have to be able to submit a timecard at the end of the day. The business rules for the application state that the agent should create the timecard, then save it to the database. Such a method might normally be written as:

To test that, you would have to go to the database and look up the timecard and verify its format. This is open to a number of problems, and isn't really testing the code in your method; it is testing a complex collection of activity, most of which won't have anything to do with the agent's ability to create the timecard.

A better way to write this method is:

Now, you can write a unit test that calls the method then verifies that the string returned matches the known state of the agent and the expected format of the document. You are not testing the database code, since that is orthogonal to the problem at hand.

So what happens if your method has more than one logical return value? If your architecture already calls for this, you will already have devised an answer to the problem. But what if you are trying to convert a void method to one with a return value (or values) just for the benefit of your unit tests? In this case, you really have three options:

1. pick the most relevant value and return it and nothing else
2. pick the most relevant value and return it as the return value of the method, but make the other values REF parameters
3. package all the values into a strongly typed data transfer object, which is just a fancy description of a struct

Avoid option #2 as much as possible unless your architecture specifically calls for it. Using REF parameters adds complexity to your application, and your unit tests should not force you to add complexity to your code. All of the other suggestions given in this article actually reduce complexity, which is the key to testable code.

Separate data access from business logic

Following from the last suggestion, make sure that your data access code is separated into its own layer. You might be using direct ODBC calls, or typed datasets, or an O/R mapping tool like NHibernate, but whichever method you use, make sure it lives in its own namespace and object model.

If your business objects are focused on the actual problem domain (rather than the common, and already solved, problem of storing data) then it is much easier to test whether or not you are solving the real problem. In addition, you can now implement a series of unit tests that exercise the data storage infrastructure for your application without jumping through hoops to ensure that the data you are storing is correctly formatted.

Instead of writing the timecard directly to the database inside of AirlineAgent, as in our example above, you would write a new data access class that handles saving and loading timecards.

The method submitTimeCard now becomes much cleaner:

In addition, now you can write unit tests that exercise just the data access layer.

Mock the data layer to test the business logic

When you are writing the unit tests that target the domain logic, mock the data access layer to ensure the separation of concerns. Just because you have separated the data access code into is own namespace, if the business logic is inseparably dependent on it, you still have the same problem: testing the business logic is dependent on successful data access logic.

You can either choose to create your own mock data access classes, or employ a mock object framework like nmock. We'll save mock-object frameworks for another column. Today, let's just create a mock version of TimeCardDA that throws exceptions when it is given a well-known input.

This mock version of the data access defines some well-known error-inducing inputs. If the input is anything other than the defined error procuring values, then the methods will return something resembling a real value. When the well-known input is given, the method will error out.

Make use of configuration

If you have followed the advice given so far, then you have an architecture based on interface implementation, with a variety of concrete implementations of your .NET code. Multiple domain objects implementing the same interface, separated domain and persistence layers, and a variety of mock or test objects that can be used in place of the real thing. In order to make full use of all of this, you need to take advantage of the configuration abilities of .NET.

Let's examine the case of the persistence layer. For normal use, your domain model will rely on the real data access layer to perform its data storage. During testing, though, you will want to use the mock persistence layer. If your domain model is tightly coupled to the real persistence layer, then you will not be able to easily replace it at test-time.

Instead of making the domain model directly coupled to the persistence model, employ the indirection pattern. Create some kind of broker or router that your domain model relies on to provide concrete implementations of the persistence layer. This broker will look up the classes that are needed for the storage operations and create instances of those classes reflectively, based on the values in the configuration file. When the application is deployed, it will have a configuration file pointing to all of your real persistence classes. The test environment, though, should have its own copy of the configuration that points to your mock data object layer.

For our agents application, we'll want to have a way to get the real version of the TimeCardDA in a deployment scenario, but the mock version for unit testing. First, let's add a configuration element to the .config file for our application:

Next, we'll modify TimeCardDA so that you cannot instantiate it directly. Instead, we'll use the factory pattern (calling a static method on the class to return a new instance). The static method will look in the configuration file to determine whether to return the real or mock object.

Finally, we need only change our code to use the new factory method instead of the direct constructor.

Now, whenever we run the unit test suite, we make sure that the value of the TimeCardDA key in the config file is set to the mock object instead of the real, and our unit tests will test only the logic of the business model.

You could, instead, implement a method or property on the domain objects that tell it whether or not to use the real mock object.

This makes it very explicit from the test code's perspective what is being tested; nobody reading your tests will miss the fact that the data generated during the test will be sent off to some mock objects instead of the real thing. However, it means that your domain objects have to implement some code that is ONLY useful during testing, and this is usually a bad idea. Your domain objects should be devoted to the single purpose of solving your business problem; extraneous testing-specific code at best clutters the interface, and at worst, can have unintended ripple-effects throughout the class and possibly the rest of the code.

Make Your Classes Do Only One Thing

This is a fairly common design principle that deserves its own point. When you write a class, it is the domain model representation of some idea. Too often, we clutter these classes with code that is only tangentially related to the idea. In "Separate data access from business logic", we examined one of the many ways that programmers clutter their code with extraneous functionality.

The rule of thumb is that there should only ever be one reason for you to modify a class. If you find yourself going back to the class to make changes again and again as different requirements change, then the class is probably overcrowded. When this happens, determine what the class was intended to do, and refactor everything else into one or more other classes. If our SecretAgent class was spending too much time in file i/o, or the AirlineAgent kept looking things up via LDAP, then we would want to remove that non-core logic and put it in another class dedicated to that kind of task.

Have Domain Object Factories

Often, the unit of functionality that you are testing is dependent on other parts of your domain model. In general, you will not want to use mock objects to impersonate the objects your functionality relies on. Mock objects are generally used to impersonate external objects from third-party libraries whose internal state you cannot control nor directly observe.

Your domain objects might have very convoluted construction requirements. If the object needs more than a single call to a simple constructor to be initialized into a state that is useful for your test, you should think about creating a test factory for that class. The test factory should provide a static method for returning an instance of the class in a ready state for use in your tests. On top of that, it should provide some static constants defining known property values that can be used to verify the state during your tests.

For example, we might need to create a series of SecretAgents for testing. We will want to create them in known states with known values. Here is a sample factory for SecretAgents:

Whenever one of your tests needs to introduce a SecretAgent into the test, perhaps passing one or more into a method that operates on a collection of IAgents, then you can use the factory to create them. Moreover, when you are handed back a reference to an IAgent in the course of a test, you can compare its data values against known values on the test factory.

Think carefully about packaging, assemblies and namespaces

Eventually, almost all "enterprise level" applications will grow to the point that running the entire suite of unit tests becomes a severe burden on the development team. Since running unit tests often is one of the central tenets of agile development (and it really is a good idea) this problem can quickly lead to fewer runs of the tests (and at worst, fewer tests written).

One way to avoid this problem is to plan your application for natural divisions of the codebase. Instead of allowing everything to be part of one monolithic assembly, the application should be built around the idea of multiple, interrelated assemblies. Your tests should follow the same architectural separation. When you work on a specific piece of the application, you can focus on running the tests associated with the assembly you are knee-deep in, and ignore the rest.

Don't be afraid of multiply-nested namespaces. If your application naturally breaks down in a nested tree structure, then let it. The only strong rule for breaking your application up into multiple assemblies and namespaces is to be careful not to overly entwine them. You generally only want dependencies running one direction between any two packages. If classes in one assembly are dependent on classes in a second, the reverse should not be true. This will allow you to replace entire assemblies more easily (for instance, if all your persistence code lives in its own assembly, you could swap it out for a new assembly that targets a different database, or one composed entirely of mock objects).

Pick a logging strategy early

Even given the earlier recommendation to have your methods return values, sometimes you can't test everything you need to just by examining the return from a method. Since unit tests are usually run from outside your development environment, it makes step through debugging during testing difficult. In truth, most unit tests are run as batches anyways, and even if you could step into the code, you won't be sitting there and be able to.

What you need is an external store of application state that you can examine and correlate back to the test results. You need a logging strategy. It is vital to implement your chosen logging strategy as early as possible in the development effort, so that you don't have to layer it back into existing code later.

Beyond that, logging will be enormously beneficial to your application post-deployment. Since bugs are difficult enough to trace when you have a full development environment available to you, tracing bugs at the customer site is next to impossible. Detailed logging allows you, and your customer, to get a detailed look at application state in both a real-time and historical perspective.

You may choose to use the built-in Trace mechanism in the FCL, or move to an external tool like log4net. Regardless, make sure you learn the basics of categorizing your messages, sorting by priority and, most importantly, routing them to different output stores. The console is a great place to get realtime logging information, but what happens when your unit tests run as a batch overnight? Where is the console tomorrow? You need to be able to store the log information in files or data tables for retrieval and examination later.

Summary

This is by no means an exhaustive treatment on the testability of applications. Entire articles can be written just about the testability of user interfaces and data access layers. Instead, these ten suggestions form a good starting point for re-examining the assumptions inherent in your design, and thinking through the decisions that will affect your code's testability. Since testability determines how well you can verify your application, it should follow that a testable application is a better application.

In this article, I’ll build a .NET application with Oracle Database and take you step by step through the development lifecycle. Along the way, you will learn how to

• Create users and roles and grant privileges to them
• Import tables and table data from Microsoft Excel spreadsheets (and many third-party databases)
• Automatically generate .NET code for an ASP.NET Web application
• Use Microsoft Query Builder to design SQL
• Generate a SQL script for all the Oracle schema objects your application uses
• Check your application and related SQL scripts into source control from Visual Studio

I’ll also touch on other aspects of the development lifecycle, including PL/SQL debugging and performance tuning.

Setup

To follow along with the steps in this article, you will need the following:

• Oracle9i Database Release 9.2 or later (SYSDBA privileges are required for a few steps)
• Oracle Developer Tools for Visual Studio Release 11.1.0.7.10 (beta) or later
• Microsoft Visual Studio 2008 or Visual Studio 2005
• A source control system with a plug-in for Visual Studio, such as Microsoft SourceSafe, Team Foundation source control, or Subversion

To connect to Oracle Database from Visual Studio, create a connection in Server Explorer. (If Server Explorer is not yet visible, select View -> Server Explorer from the main menu.) Now create the new connection in Data Connections, the top-level node of Server Explorer. Right-click Data Connections, and select Add Connection. In the dialog box that appears, confirm that Oracle Database (Oracle ODP.NET) appears in the Data source field. If you do not see Oracle Database (Oracle ODP.NET), click the Change button and select Oracle Data Provider for .NET from the list of providers. Select the database you want to connect to from the Datasource name list. Click Use a specific user name and password. In the User name field, enter SYS. In the Password field, enter the password for SYS, and ensure that Role is set to SYSDBA. Click Test connection to verify that you can connect, and click OK to complete the connection setup.

Creating a New User with User Designer

Now create an Oracle Database user that you will use during development. In Server Explorer, expand the new SYS connection you just created. You should see two child nodes: Schemas and Roles. Right-click Schemas, and choose New User from the context menu. This will launch User Designer.

I’m creating a user named CSHAY, so in User Designer, for User name, I enter CSHAY (see Figure 1). For Profile I leave the “DEFAULT” value, and for Authentication I select Password. For Password and Confirm password, I enter my chosen password. In the Tablespaces section, I select the location of the default and temporary tablespaces for the CSHAY user. When I installed Oracle Database earlier, I let the Oracle installer create a database for me, so for the default tablespace, I select the USERS tablespace, and for the temporary tablespace, I choose TEMP. Finally, I click Save, which will create my new user account. The SQL that creates the new user account will appear in the output window in Visual Studio.

Figure 1: Creating a user in User Designer

Granting Privileges to the New User Account

Before you can do anything with this new user, you will need to provide some basic privileges. Specifically, you will grant the CONNECT and RESOURCE roles. To do this in Server Explorer, first right-click the SYS connection node and choose Privileges from the context menu. In the Grant/Revoke Privileges dialog box that appears, set Object Type to Role. Select User, and then select CSHAY from the list of users. At the bottom of the dialog box, there will be a list of roles. Select both the CONNECT and the RESOURCE roles, and then click Apply.

In Server Explorer, again right-click the SYS connection node and choose Privileges to reopen the Grant/Revoke Privileges dialog box. This time set Object Type to System Privileges. Select User, and then select CSHAY from the list of users. At the bottom of the dialog box will be a list of privileges. Select the CREATE ROLE privilege, and click Apply. Finally, click OK to dismiss the dialog box.

Now connect to Oracle Database, using the new CSHAY user in Server Explorer. Right-click Data Connections, and select Add Connection. Follow the same steps to connect as CSHAY that you used to connect as SYS, except set Role to Default.

Importing Tables and Table Data

Now you need some tables and table data for the application to use. There are several ways you can achieve this. If you already have a SQL script, you can run it by choosing Tools -> Run SQL Plus Script from the main menu. Or you can create the tables and table data from scratch, by using the table designer and the data window. Additionally, you can use the Import Table Wizard to import tables and table data from any datasource listed in Server Explorer that is using a data provider for .NET that supports ADO.NET 2.0. This could include any other Oracle Database instance, a Microsoft SQL Server database, Microsoft Access, a Microsoft Excel spreadsheet, or many other datasources.

For this article, you will import data from two tables contained within the EMP_DEPT.xls spreadsheet. Download this data via the link in the Next Steps box at the end of this article.

First, connect to the EMP_DEPT.xls spreadsheet in Server Explorer. Right-click Data Connections and select Add Connection. In the dialog box that appears, click the Change button and select <other> from the list. In the Data Provider list, select .NET Framework Data Provider for OLEDB and then click OK. In Server Explorer, right-click Data Connections and select Add Connection, and in the dialog box, under OLEDB provider, select Microsoft Jet 4.0 OLEDB Provider. (Note that if you wanted to use the new Excel 12.0 .xlsx spreadsheet format, you would need to select Microsoft Office 12.0 Access Database Engine OLEDB Provider.) In the Server or File name field, enter the full path to EMP_DEPT.xls, and click the Advanced button, which will open a property sheet. For the Extended Properties property, enter Excel 8.0;HDR=YES. (If you were using the Excel 12.0 .xlsx format, you would enter Excel 12.0;HDR=YES.) Click OK to close the property sheet, click Test to test the connection, and click OK once more to close the Add Connection dialog box.

Now import the data from the connected spreadsheet. Right-click the CSHAY connection node, and select Import Table. This will start the Import Table Wizard. Click Next until you see the Choose Data Source Connection screen. For the data connection source, choose the emp_dept.xls connection. Click Next to go to the Select Tables to Import screen. Under Source Table, click the check boxes next to both DEPARTMENTS$ and EMPLOYEES$. Click each destination table name, and then edit each name to remove the dollar sign at the end (see Figure 2). The Import Data check box is checked by default, which is what you want.

Figure 2: Import Table Wizard: Renaming the destination table

Click Next to go to the Customize Columns Settings screen (see Figure 3). For each column of type BINARY_DOUBLE, highlight the row, and in the Data Type list, choose NUMBER. For EMPLOYEES.EMPLOYEE_ID, uncheck the Allows NULL check box and then check the Primary Key check box. Do the same for DEPARTMENTS .DEPARTMENT_ID. (Note that you will need to use the Select a Table list at the top of the screen to switch between the two tables.) Click Finish to import the data.

Figure 3: Import Table Wizard: Choosing the destination column datatype

After the data has been successfully imported, click OK and then go to Server Explorer, right-click the CSHAY connection, and select Refresh. Navigate to the Tables node to view the newly imported tables.

Automatically Generating the .NET Code for a Web Application

Now, taking advantage of Visual Studio’s automatic .NET code generation features, create an ASP.NET Web application to display the data you just imported into Oracle Database. You could just as easily create a client/server Winform application or a Microsoft Office application by using similar steps.

From the Visual Studio main menu, select File -> New Project. For Visual C# Project Type select Web, and then select the ASP.NET Web Application template. Click the Design button, below the HTML code window. If the toolbox is not already visible, choose View -> Toolbox from the main menu.

Scroll down to the Data section of the toolbox, and drag and drop a GridView control onto the design surface. The GridView Tasks window should immediately open, but if it does not, click the small > icon to open it. From the Choose Data Source list, select :<New Data Source>. This will open the Data Source Configuration Wizard to the Choose a Data Source Type screen. Select the Database icon, and then click OK. On the Choose Your Data Connection screen (the next screen), select CSHAY for the data connection, and click Next. On the Save a Connection String to the Application Configuration File screen, accept the defaults and click Next.

On the Configure the Select Statement screen, select Specify a Custom SQL Statement and click Next. On the Define Custom Statements screen, click the Query Builder button. When Microsoft Query Builder launches and the Add Table dialog box appears, select the DEPARTMENTS and EMPLOYEES tables and click the Add button. In the top section of Query Builder, you will see both tables automatically joined by DEPARTMENT_ID (see Figure 4).

Figure 4: Microsoft Query Builder

Now you need to decide which columns to select in your query. In the EMPLOYEES table, select the EMPLOYEE_ID, FIRST_NAME, LAST_NAME, and SALARY columns. In the DEPARTMENTS table, select the DEPARTMENT_NAME column. In the second pane from the top, order the column list by dragging and dropping so that EMPLOYEE_ID is the first Select list item and DEPARTMENT_NAME is last. Click the Execute Query button to test the query. Click OK to finish and return to the Define Custom Statements screen of the Data Source Configuration Wizard. Click Next; test the query again (if you wish), by clicking the Test Query button; and then click Finish.

From the main menu, select Debug -> Start Without Debugging, which will open your Web browser and display your running application (see Figure 5).

Figure 5: The application running in a Web browser

Creating an Oracle Database Project

You will want to store the SQL scripts for the Oracle Database schema objects the application uses and eventually check them into source control along with the application. This will allow other developers who obtain the application code to also check out and run the SQL scripts to create the Oracle schema objects the application requires.

Before you store the SQL and application code, create a project location for the code. To add an Oracle Database project to the Visual Studio solution, first right-click the topmost node in Solution Explorer and select Add -> New Project from the context menu. Under Project Types, select Other Project Types and then Database, and then select the Oracle Database Project template. When asked to select a database reference to be stored with the project, choose the CSHAY connection and click OK.

Creating a Role for the Application

You may want to create a role that represents the privileges required to access the database objects the application uses. Using Oracle roles is a good way to ensure that application users have the correct privileges. Also, if your application later requires additional privileges, modifying a single role is much easier than making new privilege grants to each individual user. This article’s sample application, for example, will need access to the EMPLOYEES and DEPARTMENTS tables.

To create the application user role, right-click the Roles node under the CSHAY connection, and select New Role from the context menu. Enter EMPDEPT_WEBAPP in the Role Name field, and then click Save.

Next, grant privileges to the role you just created. Right-click the EMPDEPT_WEBAPP node under the Roles node, and select Privileges from the context menu. When the Privilege Wizard launches, set Object Type to Table (see Figure 6). The Schema field should be set to CSHAY. Select Grant/Revoke privileges to a user/role on one or more database object(s), and then in the Object Name(s) list, select both DEPARTMENTS and EMPLOYEES (by holding down the Shift key while you click). Select Role, and then select EMPDEPT_WEBAPP from the list of roles.

Figure 6: Granting permissions on tables to the EMPDEPT_WEBAPP role

At the bottom of the dialog box, there will be a list of privileges. Select the DELETE, INSERT, SELECT, and UPDATE privileges. Click the Preview SQL button, and then click Add to Project. This will create a SQL script that contains the GRANT statements and will add it to the Oracle Database project. (You will use these GRANT statements in the next section.) Click OK to dismiss the Preview SQL window, and then click the Apply button to execute the SQL needed to grant the privileges. Then click OK to dismiss the dialog box.

Generating SQL Scripts

Now generate the SQL scripts for the tables the application uses, so that you can check them into source control along with the application. In Server Explorer, under the CSHAY node, while holding down the Control key, select the DEPARTMENTS table, the EMPLOYEES table, and the EMPDEPT_WEBAPP role. With all three selected, right-click and select Generate Create Script to Project. Provide a script name, and click OK. After the script is added, the Oracle SQL script editor will open and display the script (see Figure 7).

Figure 7: The Oracle SQL script editor (left) and project with source control menu items (right)

Under Solution Explorer, in the Security -> Permissions folder, open the script containing GRANT statements that you created earlier. Copy these GRANT statements, and paste them at the end of the just-generated SQL script. Save this script. You can now delete the GRANT script from the Permissions folder. Although it is not necessary to merge these two scripts, it is generally simpler to use one deployment SQL script for each application in source control.

Adding Application and SQL Scripts into Source Control

The first time you use source control in Visual Studio, you will need to enable it. From the main menu, select Tools -> Options, and then select Source Control. Under Current Source Control Plug-in, select the plug-in corresponding to your source control system. If you don’t see it listed here, you will need to obtain it from the vendor and install it.

To add your solution into source control, right-click the solution name in Solution Explorer and select Add Solution to Source Control. After the solution is added to source control, new icons will appear next to the filenames and source control menu items such as Check Out for Edit will be available (see Figure 7). When users check out SQL scripts from source control, they will be able to run them (using a built-in SQL*Plus execution engine) by right-clicking and selecting Run from the context menu. This will ensure that their database schema matches the one required by the application.

Debugging Your Application’s PL/SQL

Although this application doesn’t use PL/SQL, note that you can use all the powerful features of the Visual Studio debugger with your stored functions or procedures. Debugging the PL/SQL your application uses is a very important part of the application lifecycle that was covered extensively in an earlier Oracle Magazine article (“Debugging PL/SQL from .NET”).

Performance Tuning

Now you are ready to tune the application and its use of Oracle Database. The main performance tuning feature provided by Oracle Developer Tools for Visual Studio is Oracle Performance Analyzer. You can launch it by clicking a SYSDBA connection in Server Explorer and choosing Oracle Performance Analyzer from the context menu. It monitors the use of the database under load and provides performance-improving recommendations, some of which can be implemented automatically. I’ll be deep-diving into Oracle Performance Analyzer and performance tuning tricks in an upcoming article.

Christian Shay

• What exactly is the .NET platform?
• How does the .NET architecture measure up against J2EE?

And, if you think more long-term, you might have a third question rattling around your head:

• What can we learn from the .NET architecture about pushing the envelope of enterprise software development?

The .NET framework is at a very early stage in its lifecycle, and deep details are still being eked out by the Microsoft .NET team. But we can, nevertheless, get fairly decent answers to these questions from the information that's already out there.

What is it?

Current ruminations about .NET in various forums are reminiscent of the fable of the three blind men attempting to identify an elephant: It's perceived as very different things, depending on your perspective. Some see .NET as Microsoft's next-generation Visual Studio development environment. Some see it as yet another new programming language (C#). Some see it as a new data-exchange and messaging framework, based on XML and SOAP. In reality, .NET wants to be all of these things, and a bit more.

First, let's get some concrete details. Here's one cut at an itemized list of the technical components making up the .NET platform:

• C#, a "new" language for writing classes and components, that integrates elements of C, C++, and Java, and adds additional features, like metadata tags, related to component development.
• A "common language runtime", which runs bytecodes in an Internal Language (IL) format. Code and objects written in one language can, ostensibly, be compiled into the IL runtime, once an IL compiler is developed for the language.
• A set of base components, accessible from the common language runtime, that provide various functions (networking, containers, etc.).
• ASP+, a new version of ASP that supports compilation of ASPs into the common language runtime (and therefore writing ASP scripts using any language with an IL binding).
• Win Forms and Web Forms, new UI component frameworks accessible from Visual Studio.
• ADO+, a new generation of ADO data access components that use XML and SOAP for data interchange.

How do .NET and J2EE compare?

As you can see, the .NET platform has an array of technologies under its umbrella. Microsoft is ostensibly presenting these as alternatives to other existing platforms, like J2EE and CORBA, in order to attract developers to the Windows platform. But how do the comparisons play out item-by-item? One way to lay out the alternatives between .NET and J2EE is shown in the following table:

The comparisons in this table only scratch the surface. Here's an executive summary of .NET vs. J2EE:

Features: .NET and J2EE offer pretty much the same laundry of list of features, albeit in different ways.

Portability: The .NET core works on Windows only but theoretically supports development in many languages (once sub-/supersets of these languages have been defined and IL compilers have been created for them). Also, Net's SOAP capabilities will allow components on other platforms to exchange data messages with .NET components. While a few of the elements in .NET, such as SOAP and its discovery and lookup protocols, are provided as public specifications, the core components of the framework (IL runtime environment, ASP+ internals, Win Forms and Web Forms component "contracts", etc.) are kept by Microsoft, and Microsoft will be the only provider of complete .NET development and runtime environments. There has already been some pressure by the development community for Microsoft to open up these specifications, but this would be counter to Microsoft's standard practices.

Read more on the .NET platform in this in-depth interview by O'Reilly Windows editor John Osborn:

Deep Inside C#: An Interview with Microsoft chief architect Anders Hejlsberg–John gets to the bottom of not only Microsoft's detailed plans for the C# programming language but also the .Net framework.

J2EE, on the other hand, works on any platform with a compliant Java VM and a compliant set of required platform services (EJB container, JMS service, etc., etc.). All of the specifications that define the J2EE platform are published and reviewed publicly, and numerous vendors offer compliant products and development environments. But J2EE is a single-language platform. Calls from/to objects in other languages are possible through CORBA, but CORBA support is not a ubiquitous part of the platform.

The Bigger Picture

These last points highlight some of the key differentiators between .NET and J2EE, and point towards Microsoft's real play here. Microsoft is doing two very notable things with .NET: It is opening up a channel to developers in other programming languages, and it is opening up a channel to non-.NET components by integrating XML and SOAP into their messaging scheme.

By allowing cross-language component interactions, .NET is enfranchising Perl, Eiffel, Cobol, and other programmers by allowing them to play in the Microsoft sandbox. Devotees of these languages are particularly amenable to gestures like this, since for the most part they have felt somewhat disenfranchised and marginalized in the Microsoft/Sun/Open Source wars. And by using XML and SOAP in their component messaging layer, Microsoft is bolstering their diplomatic face and adding an element of openness to their platform, providing ammunition against claims of proprietary behavior.

What's the correct response?

For Microsoft developers:

.NET is a good thing for those of you committed to Microsoft architectures. ASP+ is better than ASP, ADO+ is better, but different, than ADO and DCOM, C# is better than C and C++. The initial version of .NET won't be real until sometime in 2001, so you have some time to prepare, but this will undoubtedly become the default development environment for Microsoft platforms. And if you're developing within the Microsoft development framework now, you will undoubtedly benefit from adopting elements of the .NET framework into your architectures.

However, several of the goals of the .NET platform are fairly lofty and not at all guaranteed to fly, at least not in the short term. The IL common language runtime, for example, has some fairly significant hurdles to overcome before it has any real payoff for developers. Each language that wants to integrate with the component runtime has to define a subset/superset of the language that maps cleanly into and out of the IL runtime, and has to define constructs that provide the component metadata that IL requires. Then compilers (x-to-IL and IL-to-x) will have to be developed to both compile language structures (objects, components, etc.) into IL component bytecodes, and also generate language-specific interfaces to existing IL components.

There is some historical precedence here. Numerous bridges from non-Java languages to the Java VM have been developed, such as JPython, PERCobol, the Tcl/Java project, and interestingly enough, Bertrand Meyer and some other Eiffel folks put together an Eiffel-to-JavaVM system a few years back. With the possible exception of JPython, these tools have not been widely adopted, even within their respective language communities, even though they seem to offer a way to write code for the Java environment (albeit not the entire J2EE framework) using your favorite language. Why this lack of enthusiasm? I believe it's because people are hesitant to take on the headaches of adding yet another translation step from their development language to the target framework. If the Java environment is the goal, people will generally choose to learn Java. I predict that the same will be true of .NET: People will generally choose to learn C# and write .NET components in that language.

Another caution: Beware of performance issues with .NET's SOAP-based distributed communications. SOAP essentially means XML over HTTP. HTTP is not a high-performance data protocol, and XML implies an XML parsing layer, which implies more compute overhead. The combination of both could significantly reduce transaction rates relative to alternative messaging/communications channels. XML is a very rich, robust metalanguage for messaging, and HTTP is very portable and avoids many firewall issues. But if transaction rates are a priority for you, keep your options open.

For the Java and Open Source communities:

It would be easy to dismiss .NET as more Microsoft marketing-ware and continue on your merry way. But don't. .NET is a sign of a subtle but significant shift in Microsoft's strategy to evangelize their platforms. They have been fighting alternative frameworks and platforms at the management level pretty well, touting the usual questionable "statistics" about cost of ownership and seamless integration. Now they are fighting Java and open source initiatives on their own terms, putting their own spin on "open" and attempting to directly address the needs of developers, two things that they have been faulted for not doing very well in the past. If you consider yourself an evangelist for Java or open source platforms, then the nature of the war is changing. Be prepared.

Also, Microsoft's IL runtime has at least one notable, if improbable, goal: eliminate the programming language as a barrier to entry to the framework. Java eliminates the platform barrier (within limits, of course: You can't make up for missing hardware resources with software, for example), but in order to work in J2EE, you have to work in Java. .NET wants to let you use the language of your choice to build .NET applications. This is admirable, though there are big questions as to whether and when the IL approach in .NET will actually become broadly useful (see above). Regardless, this points to a weakness in the single-language J2EE approach. The importance of this weakness is questionable, but it exists nonetheless, and deserves some consideration by the Java community. If this is really desired by developers, then maybe the efforts in Java bytecode generators for non- Java languages should be organized and consolidated.

Focusing on J2EE, there are a few issues that should be addressed immediately in order to bolster the advantages of that platform compared to what .NET is shooting for. First, XML support needs to be integrated seamlessly into the framework. I'm not talking about bolting an XML SAX/DOM parser to the set of standard services, or extending the use of XML in configuration files. XML messaging and manipulation need to be there, ready to use. Admittedly, you can use XML payloads on top of JMS messaging, but the platform doesn't facilitate this at all. The XML space is a cluttered mess of standards, de facto standards, APIs and DTDs, which is to be expected when you're dealing with a meta-language.

But Microsoft has put a stake in the ground with SOAP, and they're pushing hard to put something understandable and useful in the hands of developers. J2EE proponents need to do the same with their platform. One possibility that comes to mind is to add an XML messaging "provider" layer on top of JMS, along the lines of the pattern followed by Java Naming and Directory Interface, or JNDI, with LDAP, NIS, COS Naming, etc. This in combination with a standard SOAP/BizTalk provider, an ebXML provider, etc. would be an impressive statement.

Clarifications and Corrections

Since the publication of this article in August 2000, 40 readers have responded with their own thoughts about .Net vs. J2EE. Jim Farley, the author of this article, has sifted through those comments, as well as email he's received, and added the following clarifications and corrections.

Clarifications

The description of C#'s compilation features vs. those of Java seems to have confused some readers. To put it another way: C# code always runs natively. Java code typically runs as interpreted bytecodes, and can run natively. C# is either compiled entirely to native code, or it is compiled into the common language runtime bytecodes and then just-in-time compiled to native code during execution. Java code, on the other hand, typically runs as runtime-interpreted bytecodes (from which its cross-platform abilities spring), and can also run in a just-in-time compiled context. Some Java native-code compilers also exist (Jove, BulletTrain, JET, etc.).

As a side note, Microsoft claims that the default interpretive mode of Java is a liability, in that bytecodes designed for a virtual machine do not lend themselves as well to native optimization. I haven't seen any hard data to prove or disprove that claim, either generally (bytecodes vs. native-compiled languages) or specifically (Java vs. C#).

Several readers, in response to the call to include XML support in J2EE, mentioned the fact that J2EE 1.3 (currently in public draft) requires that any J2EE-compliant product must include Java XML SAX and DOM parsers. But this is just "bolting an XML SAX/DOM parser" to J2EE, as I mentioned. I was calling for it to be taken a step farther, to incorporate XML support directly in the J2EE support APIs. Ideally, J2EE-based components and services would have XML support (for messaging, interface description exports, etc.) automatically built-in, to some extent.

Corrections

I state in the article that C# "borrows some of the component concepts from JavaBeans." This statement can't be proven, and, as several readers pointed out, it's more likely that Microsoft based the component functionality of C# more on their own COM and VB models, with influences from other pre-existing component models.