As Published In
Oracle Magazine
November/December 2008

DEVELOPER: ODP.NET

Instant ODP.NET Deployment

By Mark A. Williams Oracle ACE Director

Deploy ODP.NET applications instantly with Oracle Data Access Components.

Deploying applications can sometimes be a challenging process, involving large, complex installations. Oracle Data Access Components 11g with Xcopy deployment, however, enables Oracle Data Provider for .NET (ODP.NET) developers deploying their applications to take advantage of key features that reduce client installation size, complexity, and maintenance.

Oracle Data Access Components 11g with Xcopy deployment includes the lightweight Oracle Database Instant Client, which is less than one-third the size of a full client installation. In addition, Oracle Database Instant Client enables developers to install their client software (including ODP.NET) without Windows Registry or Oracle Home settings on the client machine. (Note that although this column focuses on ODP.NET, Oracle Database Instant Client also supports SQL*Plus, JDBC-OCI [Oracle Call Interface], ODBC, Oracle Providers for ASP.NET, Oracle Provider for OLE DB, Oracle Objects for OLE, and Oracle Services for Microsoft Transaction Server.)

You can maintain or upgrade Oracle Database Instant Client installations by simply overlaying a new version over an existing one, and best of all, Oracle Database Instant Client is a free component. This means that you can develop and distribute your ODP.NET applications at no cost.

This column walks you through the steps necessary to install Oracle Data Access Components 11g with Xcopy deployment (which includes Oracle Database Instant Client and ODP.NET) on a developer machine, build a simple console-based ODP.NET application using Microsoft Visual C# 2008 Express Edition that connects to Oracle Database, and then distribute the client and application to a target (client) computer.

What You Need to Get Started

Every environment is different, and you can make adjustments to the steps presented here, as necessary, to fit your environment. However, to best take advantage of these steps, you should have access to the following:

 

  • Oracle Data Access Components 11g with Xcopy deployment.
  • Oracle Database (Oracle9i Database Release 2 or higher; any edition, including Oracle Database 10g Express Edition).
  • Microsoft Visual C# 2008 Express Edition (or any full version of Microsoft Visual Studio).
  • A separate development machine, deployment target machine, and database server. This column uses three machines, but you can follow the steps with a single machine.


Here is some important information about each of the three machines in my environment:

 

  • liverpool: Oracle Database 10g Express Edition running Oracle Enterprise Linux. The HR sample schema will be used in this database in the sample application. No installation activity will take place directly on this machine.
  • chesham: The developer machine running Microsoft Windows XP. This machine has Visual Studio C# 2008 Express Edition installed. There are no Oracle components on this machine at the beginning of the process.
  • chepstow: The deployment target machine running Windows XP. This machine has the .NET Framework 3.5 installed. There are no Oracle components installed on this machine at the beginning of the process.


To download and install Oracle Data Access Components 11.1.0.6.21 with Xcopy deployment:

1. Download the ODAC1110621Xcopy.zip file from Oracle Technology Network (see Next Steps for the specific location) to the C:\Temp directory on the developer machine (chesham in my case). Create this directory if necessary.
2. Extract the zip file to the C:\Temp directory, using the correct means on your machine.
3. To install Oracle Data Access Components on the developer machine, execute the install.bat batch file. Click the Start button, select Run... , type cmd in the Run dialog box, and click OK . This opens a new command prompt window.
4. In the command prompt window, type cd /d C:\Temp and press Enter to change directories to the C:\Temp directory.
5. Type install.bat odp.net20 c:\oracle\11.1\odac odac11 and press Enter to install Oracle Data Access Components. This will install the ODP.NET 2.0 and Oracle Database Instant Client components into the c:\oracle\11.1\odac directory and create a registry key called KEY_odac11. For full details of the options available with install.bat, see the readme.txt file in the C:\Temp directory.
6. Type exit and press Enter to exit the command prompt window.
7. Now you can remove the downloaded and extracted files from the C:\Temp directory if you choose.
8. The last step in installing Oracle Data Access Components and Oracle Database Instant Client on the developer machine is to add two items to the Path environment variable. Right-click the My Computer icon and select Properties from the context menu. Next, click the Advanced tab in the System Properties dialog box and then click the Environment Variables button. In the System variables group, locate the Path variable in the list (scroll down if necessary). Click the Path variable in the list and then click Edit. In the Edit System Variable dialog box, place the cursor at the beginning of the entries and type C:\oracle\11.1\odac;C:\oracle\11.1\odac\bin; . Click OK to close the Edit System Variable dialog box, click OK to close the Environment Variables dialog box, and finally click OK again to close the System Properties dialog box.

You can use the NLS_LANG environment variable to localize language settings. Refer to the Oracle Database Globalization Support Guide for additional information.

Create the Visual Studio Solution and Build the Application

To create the Visual Studio solution, do the following:

1. Start Visual C# 2008 Express Edition, select File -> New Project from the main menu, select Console Application from the New Project dialog box, enter NovDec2008 for Name , and click OK.
2. Once Visual Studio has finished creating the initial solution, right-click the References node in the Solution Explorer and select Add Reference from the context menu. In the Add Reference dialog box, scroll down the list and select Oracle.DataAccess in the Component column. Click OK to add the reference to the ODP.NET assembly to the solution. Right-click Oracle.DataAccess in the References list; select Properties ; and in the Properties list, be sure Copy Local is set to True.
3. Replace all the code in the Program.cs source file with that in Listing 1. (For details on the Easy Connect [EZCONNECT] naming method used in this code, see the Oracle Database Net Services Administrator’s Guide .)

Code Listing 1: Program.cs code for NovDec2008 solution

 

 
using System;
using Oracle.DataAccess.Client;

namespace NovDec2008 {
  class Program {
    static void Main(string[] args) {
      // create connection string using EZCONNECT format
      // this format specifies the server and the Oracle
      // service name as the datasource
      // using the format: server/oracle service name
      // no tnsnames.ora or sqlnet.ora file is needed

      string constr = "User Id=hr; " +
                           "Password=hr; " +
                           "Data Source=liverpool/xe";

      // create connection object
      OracleConnection con = new OracleConnection(constr);

      // use "try" block to open connection
      // if an error occurs, simply display the message
      // since there is a "catch" block a "using" statement is not used
      try {
        // attempt to open the connection
        con.Open();

        // if no exception was thrown this line will execute
        // display simple success message
        Console.WriteLine("Successfully connected to Oracle!\n");

        // display the connection string (without password)
        Console.WriteLine("Connection String: " + con.ConnectionString);
      }
      catch (OracleException ex) {
        // an OracleException was thrown
        // simply display the message
        Console.WriteLine(ex.Message);
      }
      finally {
        // clean up the connection object
        con.Dispose();
      }

      // prevent the console from closing when running in VS environment
      Console.WriteLine();
      Console.Write("ENTER to continue...");
      Console.ReadLine();
    }
  }
}


4. Select File -> Save All from the main menu and leave NovDec2008 for Name . Select an appropriate location, such as C:\NovDec2008, or accept the default. Uncheck the Create directory for solution check box and click Save to save the solution.
5. Build the application, by selecting Build -> Build Solution from the main menu.
6. Test the application, by selecting Debug -> Start Debugging from the main menu. If there are no errors, you should see output similar to the following in the command window:

 

Successfully connected to Oracle!

Connection String: User Id=hr; Data Source=liverpool/xe

ENTER to continue...


7. Now that you have built the solution, exit Visual Studio by selecting File -> Exit from the main menu.

Deploy Oracle Database Instant Client and Application

In this section, you will see firsthand why “Xcopy” is part of the Oracle Data Access Components distribution filename. You use the xcopy command to copy both the Oracle client files and the application files to the deployment target. (Note that you will need appropriate permissions on the deployment target machine. If you have any questions about permissions or need to make adjustments to the process, contact your local system administrator.)

To complete the deployment of Oracle Database Instant Client and the application you just created to the target machine, do the following:

1. On the developer machine (chesham in my case), open a command prompt window by first clicking Start -> Run , then typing cmd in the Run dialog box, and clicking OK.
2. Now execute the net use command to map the administrative share of the C drive on the deployment target machine to the developer machine. In the command prompt window, type the following command (making any necessary adjustments for your environment):

 

C:\>net use \\chepstow\c$
The password or user name is invalid 
for \\chepstow\c$.

Enter the user name for 'chepstow': oracle
Enter the password for chepstow: 

The command completed successfully.


Note that you may be prompted for credential information if the credentials you used to log in to the developer machine are not valid on the deployment target machine. (In this example, my credentials were not valid on the deployment target machine.)

3. Now deploy the Oracle installation to the deployment target machine:

 

xcopy /e /f c:\oracle \\chepstow\
c$\oracle\


The files will be listed as they are copied.

4. Next, deploy the application files to the deployment target machine. Be sure to use the path you specified when saving the solution (such as C:\NovDec2008), and if the path contains spaces, use double quotes around the pathname. I used the following command:

 

xcopy /e /f C:\NovDec2008\bin\Release \\chepstow\c$\temp\NovDec2008\


 

Next Steps


 READ more ODP.NET

DOWNLOAD
Oracle Data Access Components with Xcopy deployment
Oracle Database Instant Client
the sample application for this column

LEARN more about ODP.NET
The .NET Developer Center
Oracle Data Provider for .NET Developer's Guide
Oracle Database Net Services Administrator’s Guide
Oracle Database Globalization Support Guide

5. As you did on the developer machine, you need to add two items to the Path environment variable on the deployment target machine. On the deployment target machine (chepstow in my environment), right-click the My Computer icon and select Properties from the context menu. Next, click the Advanced tab in the System Properties dialog box and then click the Environment Variables button. In the System variables group, locate the Path variable in the list. (Scroll down if necessary.) Click the Path variable in the list and then click Edit . In the Edit System Variable dialog box, place the cursor at the beginning of the entries and type C:\oracle\11.1\odac;C:\oracle\11.1\odac\bin; . Click OK to close the Edit System Variable dialog box, click OK to close the Environment Variables dialog box, and finally click OK again to close the System Properties dialog box.


Execute the Application on the Target Machine

You have successfully deployed the Oracle client files and the application files to the deployment target machine, and now it is time to verify that the application works as expected. (Note that there are no network configuration files to create or manage in my deployment scenario.)

To verify that the deployed application is working properly on the target machine, do the following:

1. On the deployment target machine (chepstow in my environment), open a command prompt window by first clicking Start -> Run , then typing cmd in the Run dialog box, and clicking OK.
2. Change to the directory where the application files were copied:

 

cd /d C:\temp\NovDec2008


3. Execute the application, by typing NovDec2008 , and verify that the output is the same as what was produced on the developer machine.

Congratulations! You have successfully created and deployed an Oracle Data Access Components with Xcopy deployment application.

Conclusion

This column has demonstrated how to install Oracle Data Access Components 11.1.0.6.21 with Xcopy deployment components; develop a simple ODP.NET application to verify functionality; and deploy both the Oracle client and application files to a deployment target, using the xcopy command. Xcopy deployment is especially useful if you want to customize an install package with an Oracle client or you are seeking ways to deploy an Oracle client to numerous client machines.

These steps are just one way to accomplish the goal of simpler and smaller application deployments. I recommend taking these steps and adapting them to what works best in your environment.
 



Mark A. Williams
(mawilliams@cheshamdbs.com) is an Oracle ACE director, an Oracle Certified Professional DBA, the author of Pro .NET Oracle Programming (Apress, 2004), and a contributor to the Oracle Data Provider for .NET forum on Oracle Technology Network.

Send us your comments