Quick Start: Getting a New Project Up & Running

In this section

This page gives you a cookbook approach to what you need to do to setup your development environment for a new project using the openSEAL Component Model. What we do here is walk you thought the setup process for a typical project.

The steps we will follow are:

  1. Review the design
  2. Determine the project names and other values we'll need
  3. Setup the Project Directory
  4. Setup the Business Application Service
  5. Setup the Web Application Service

1. Review the design

The step-by-step guide here has been written to illustrate how to set up an openSEAL Component Model project common 3 tier application architecture, with a web tier, a business tier and a data tier (actually, we don't show the database setup here because that will be application specific). If your application has more or less tiers just repeat the appropiate section. Likewise, if you have, say, more than one Business Application Service, just repeat that section with the appropriate configuration.

diagram coming here soon!

The web tier of this application is implemented as a Web Application Service (WAS). This is the openSEAL web tier specific Application Service that is hosted by an ASP.NET web application running on IIS. The business tier is implemented as a Business Application Service (BAS) that is hosted in a Win32 service. By using the WAS and BAS, you are letting openSEAL do all the "infrastructure" heavy lifting, and you can concentrate on implementing your application specific functionality.

2. Determine your projects Names etc.

Before you begin, decide on the following values for your project:

Item Description Example
Project Short Name Alpha-numeric, no spaces or special characters helloworld
Project Long Name Descriptive name that can contain spaces openSEAL Helloworld Application
Project Root Dir Base directory where files for project will be stored under c:/projects/helloworld
Project Namespace Prefix Used as the prefix for the namespace of the project com.acme.helloworld

 

3. Setup the Project Directory

Regardless of whether your project has zero or more BAS, or zero or more WAS, this section of the setup process will always need to be completed first.

  1. Open a command shell and navigate to the scripts/build folder under where you previously downloaded and installed openSEAL.
  2. Run the nant -D:buildfile:new_project.build setup Nant task with the following arguments, separated by spaces (note: see the contents of the build file for additional optional arguments):
    1. -D:project.name=your name here (e.g. helloworld)
    2. -D:project.root.dir= your project dir (e.g C:\projects\helloworld)
    3. -D:project.src.prefix=your prefix (e.g. com\acme\helloworld)
  3. The above step should have created a project working directory for you and copied over a number of files that will make the setup and testing of the project much easier.
  4. (Optional) If your project has several BAS or WAS instances, you can run the setup tast multiple times with different arguments as applicable.
  5. In your new project directories scripts/build sub-directory, edit your projectname.build NANT build file in the following ways:
    1. If you have a specific version of the CLR you will be using (such as MS Net v 1.1), set the net.sdk.version to its corresponding value (e.g. net.sdk.version=net1.1 for MS Net SDK v1.1). You can override this when you run a specific nant task by adding the option -D:net.sdk.version=net1.0 etc to the end of your command.
    2. Set the default value of compile.version to either "debug" or "release". You can override this when you run a specific nant task by adding the option -D:compile.version=debug etc to the end of your command.
    3. Look for the properties with CHANGE_XXX_HERE (e.g. CHANGE_SRC_DIR_HERE) for the properties that need changing. These will probably include:
      1. project.name
      2. project.src.prefix (in this case use '\' not '.')
      3. project.version.*
      4. business.svc.title & schedule.svc.title etc.
    4. You should also look through the rest of the build file to make sure your projects preferences are reflected. For instance, clean out any tasks you don't need.
  6. Once you have edited it, you can test it by opening a command shell, cd to your scripts/build folder and type: nant init. Check that the output displayed is correct and that the task returned Sucess.

4. Setting up the Business Application Service

In this section we show you a how to set up a "Hello World" working business component hosted within a BAS. You can mimic this step-by-step approach to set up your own projects business tier. You will basically be creating up to four DLLs. While this is obviously overkill for one method, if you're creating an enterprise-class application this will allow better scaling and flexibility.

diagram to come soon!

The steps below are dependent on one another so do not start the next task until the previous one is completed successfully.

Setup your projects Types assembly.

It is recommended (but not necessary) to create an assembly that contains all your business applications types. The reference application, the new_project.build setup script, and the project_template.build script all assume you do this.

  1. Create a type object. Tip: You can copy the Ref Apps HelloWorldType.cs and change its namespace. Save it into your projects types source folder.
  2. Add TypesAssemblyInfo.cs to the types\meta-inf folder. You can create a new one using a text editor or IDE, or just copy and modify the corresponding file from the reference application. Set your appropriate assembly info, such as title and version number.
  3. In a command shell, cd to your scripts/build folder and type: nant build_types and check that the type assembly compiled and deployed correctly. You should see the DLL in the appropriate sub-folder under your projects bin folder.
Visual Studio.NET Tip:
To create a project for your types assembly, create an empty library project and save it in the src directory. To import the types file(s), select the menu option Project > Show All files, and then right-click on the HelloWorld.cs file and "Include in project". You can also set the project options to build to the ../bin directory (we recommend you delete the src/bin and src/obj directories that Visual Studio creates as you won't use them). Note also that you use a similar approach for the other assemblies below.

Setup your projects Business API assembly.

It is recommended (but not necessary) to create an assembly that contains all your business applications APIs. The reference application, the new_project.build setup script, and the project_template.build script all assume you do this.

  1. Create a Business Manager Interface object. Tip: You can copy the Ref Apps IHelloWorldMgr.cs and change its namespace. Save it into your projects business\api source folder.
  2. Add BusinessApiAssemblyInfo.cs to the business\meta-inf folder. You can create a new one using a text editor or IDE, or just copy and modify the corresponding file from the reference application. Set your appropriate assembly info, such as name and version number.
  3. In a command shell, cd to your scripts/build folder and type: nant build_biz_api and check that the type assembly compiled and deployed correctly. You should see the DLL in your projects bin folder.

Setup your projects Common assembly

It is recommended (but not necessary) to create an assembly that contains all your common classes, that is, classes that are common across tiers of the application. The reference application, the new_project.build setup script, and the project_template.build script all assume you do this.

  1. You may want to create a Factory that the client can use to get references to the remote service managers. Take a look at the refapps BusinessFactory.cs for an example of this. You can copy it (change its namespace and edit its methods as appropriate) and save it into your projects common\business\api source folder.
  2. Add CommonAssemblyInfo.cs to the common\meta-inf folder. You can create a new one using a text editor or IDE, or just copy and modify the corresponding file from the reference application. Set your appropriate assembly info, such as name and version number.
  3. In a command shell, cd to your scripts/build folder and type: nant build_common and check that the type assembly compiled and deployed correctly. You should see the DLL in your projects bin folder.

Setup your projects Business Implementation assembly

It is recommended (but not necessary) to create an assembly that contains the implementation of your business applications APIs. The reference application, the new_project.build setup script, and the project_template.build script all assume you do this.

  1. Create an object that implements the Business Manager Interface you created above. Tip: You can copy the Ref Apps HelloWorldMgrImpl.cs and change its namespace. Save it into your projects business\impl\manager source folder.
  2. Add BusinessImplAssemblyInfo.cs to the business\meta-inf folder. You can create a new one using a text editor or IDE, or just copy and modify the corresponding file from the reference application. Set your appropriate assembly info, such as name and version number.
  3. In a command shell, cd to your scripts/build folder and type: nant build_biz_impl and check that the type assembly compiled and deployed correctly. You should see the DLL in the appropriate subdirectory under your projects bin folder.

Configuring the Business Application Service (Win32Svc) host

The Business Application Sevice for this example is installed and hosted as a Windows 32 Service (henceforth denoted a Win32Svc). The reference application, the new_project.build setup script, and the project_template.build script host the process in this way. All you need to do to install and run this host is to make sure the configuration file is edited correctly and run some nant tasks.

  1. In a text editor, open the openSEAL.win32.exe.config file. Edit the values in the <application.service.setup.win32> section to correspond to your application.
  2. (Optional) This step is only required if you intend to encrypt the remoting traffic too and from your BAS. Run the hostkeygen.exe utility that comes with the openSEAL download (you will need to compile it) to generate a public and private key for your projects remoting encryption. By default, the files will be called host and host.pub and will be saved in the same directory as the hostkeygen.exe itself. Copy these files (and rename them if you like) into your projects config directory. Edit your configuration files remoting section to point to these files.
  3. Review the other sections of the openSEAL.win32.exe.dev|prod file to make sure that remoting and logging is configured correctly.
  4. To install the Win32Svc, in a command shell cd to your scripts/build folder and type nant install_bas_winsvc . Check the output to see if it installed correctly. If you run into problems here, check that the Win32Svc names are consistent in your nant build file and openSEAL.win32.exe.config, and that the install util path in your NANT script is correct.
  5. Test the Win32Svc by running it. To do this in a command shell,type nant start_bas_winsvc. Check that there are info messages in your event log. If the start didn't work, you'll more than likely see 1 error message and 1 info message. More often than not, problems here are related to configuration information, so check and double check your config files. The error message in the event viewer should give you pointers. If all is well you should see a log file created in your log folder (defined in the config file).

 

Setting up the Web Application Service

If your project contains a WAS, then this section will give you a step-by-step guide to setting up and configuring the your web application environment.

  1. Create a new Web.config file in the root of your virtual directory. It is recommended you copy the Refapp config file and then edit its contents as appropriate. Typical edits include:
    1. <httpModules> section will need the correct Authentication modules. Try starting with the simple implementation of org.openseal.ui.web.command.BasicAuthenticationModule and later customize for your specific authorization approach. The Refapp has an example of this.
    2. <openSEAL.config> will probably need a number of values changed, such as the remoting config file changed to the correct path, and the URI values of the Business Methods corrected. This should be reasonable intuitive, but see the Configuration Reference for more details.
    3. <openSEAL.webconfig> will also need a changed. This is more involved that above. See the Configuration Reference for details.
    4. <log4net> section will need to have the path to the log file set.
    5. <system.runtime.remoting> should have the application name and the host key path edited.
  2. Add a new Global.asax file to your virtual directory root. At this time it is enough to just contain the following line, which extends it from the openSEAL web application base class. <%@ Application Inherits="org.openseal.ui.web.service.BaseWebService" %>. (You can add your own web application base class later with business service helper methods etc., or add to your Global.asax file).
  3. Configure IIS. This requires the same steps as creating a new virtual directory when configuring IIS for the Reference Application.
  4. Copy a simple ASPX file that you know works somewhere in your web directory so that you can test your setup. info.aspx in the refapp web root is a good file for this.
  5. Start your W3SVC (you can do this via the start_w3svc task in your projects build file), and browse to the page added in the step above. Most of the "typo" errors in your configuration files will become apparent when you start and browse to the page.