AllFusion Plex r6.00 .NET Support
Getting Started Guide
The following guide will outline the basic steps required in order to run a simple AllFusion Plex
C++ client to C# server application.
In order to run this example, you will
need a minimum of the following installed on your PC.
AllFusion Plex r6.00 Alpha.
You should use the latest recommended version of the
alpha for all evaluation. For information on the latest version, please refer to the
Plex r6.00 Alpha forum.
icrosoft SQL Server
You should be able to build the database schema
example against any version of SQL Server, although SQL Server 2005 is
recommended. For a comparison of SQL Server 2005 editions, refer to the
Microsoft .NET Framework Version 2.0 Redistributable Package
recommended is v2.0.50727, and is available from the
Microsoft .NET Framework
. It is also installed by default with Microsoft Visual Studio 2005.
Microsoft Visual Studio 2003.
This is used in order to build the Plex generated
unmanaged C++ client a
pplication. Version 7.1.3088 or above is recommended.
In addition to the above, you may wish to install the following features to make the most of the
new AllFusion Plex r6.00 .NET support:
Microsoft Visual Studio 2005.
Although the .NET Framework Version
Redistributable Package contains the tools necessary to build generated C# source code,
you may wish to install Visual Studio 2005 in order to integrate your generated Plex .NET
Server applications with
party client applications. This is esp
ecially true if you
would like to take advantage of the new AllFusion Plex r6.00 .NET Runtime API layer.
Version 8.0.50727 or above is recommended.
Running a Simple Client
The following example uses the sample model
. Unzip the sample to your
machine. It doesn’t matter where you install the example, but the remainder of this example will
The sample consists of three relatively simple entities that comprise a Sales Order
Order.Header, Order.Detail and SalesSurrogateSystem; the latter is a support entity used to
maintain information on order keys that have been allocated.
As you can probably imagine, Order.Detail is owned by Order.Header. Both Header and Detail
obtain their primary keys automatically by inheriting from patterns that allocate surrogate keys.
Header inherits from FOUNDATION/Surrogate and Detail inherits from
FOUNDATION/SurrogateOwned (so that the primary keys are allocated uniquely within
All three entities have database tables and views associated with them, and as such, they inherit
from STORAGE/Relational Table.
In order to generate and build this example targeting a Windows C++ client running to a C# .NET
e simply need to set the relevant variants for the libraries attached to SalesSystem from
which it inherits. Because the Windows C++ client is the default variant for the client pattern
libraries, this only means we have to set the STORAGE library to a var
iant of ‘.NET server’.
This has already been set in the SalesSystem model for you. The only thing you need to do in
order to run the
is to generate it, build it and configure the Plex .NET runtime so that the
client can call the server. The fol
lowing steps will walk you through this process.
Steps To Create The Application
First, you will need to configure the database to which to wish to run to.
In order for Plex
to build the necessary table and view schemas, you will need to configure an
rce to connect to the database. The remainder of this document will reference a
datasource called ‘development’ that connects to a SQL Server 2005 instance.
With the model open, go to the
Generate and B
uild window (Tools
ake a few moments to review the settings associated with the model
Generate and Build Options…). Out of all the settings, take special note of the
Make sure if you have installed the sample model to any
SALESSYSTEM that you set the generate and
build directories accordingly.
C# Generation Options:
This tab contains options that affect the generated C#
source code. Currently, the only option is the Default generation package. This
the .NET namespace into which a Plex generated C# function will be
placed if it is not
assigned to a Plex Package object. As none of the functions in
this simple example have been modeled into packages, this will be the
namespace into which our generated C
# classes will be placed.
System Definitions/<Local machine name>
This tab contains the
options required for building C# source code.
Build for .NET CLR Debugging
oes exactly what it says.
Default Code Library Name
efines the name of the
which Plex generated C# functions will be placed when they are built
from the standard Generate and Build window
. Deploying Plex generated
.NET applications will be the subject of a separate discussion on Code
Allows you to specify additional .NET
assemblies that your Plex generated C# functions might reference. For
example, you may add C# source code to your action diagrams that
reference external .NET components or pre
built Plex C# functions from
System Definitions/<Local machine name>/
This is where you
set the options used when generating database schemas to an SQL database.
Make sure you select the ODBC datasource you defined in (1) so that Plex can
automatically generate t
he necessary database schemas.
Select the subject area ‘Generate and Build Me’, and generate
the source for this subject
). You should be prompted to generate 36 objects. Once the
generation has completed
take a look at the directory i
nto which the source has been
generated and take a look.
Reselect the subject area ‘Generate and Build Me’, and build the source for this subject
Build). You should be prompted to build 15 C++ Functions and 21 C#
Highlight the Function the Subject Area ‘
Create an Executable for Me
’ and select
in order to create a client executable entry point for the application.
Now look at the generation directories to see the locations of the various binarie
comprise this application.
GEN directory contains all the C++ source and
A new directory called ‘Src’ is created under
where the C# source is to be generated. The actu
source is generated into directories that match the
Plex Package names into which the Function objects
will be generated. Note that as we didn’t define a
Packages for Functions, that they are assigned to the
Default Generation Package from the C# Gener
new ‘Bld’ directory corresponds to the ‘Src’
directory created during generation. It contains the
entire source built from the ‘Src’ directory. In this
example, it relates to a single assembly called
SalesSystem.dll. This is the assem
bly that the Plex
.NET runtime will need to reference in order for clients
to make calls to it.
‘Debug’ directory contains all of the unmanaged
C++ client binaries, consisting of dll, pnl, exe and ini
In order for the Plex generated .NET Server application to connect to the database, an
OLEDB.NET connection must be used.
This example uses a Microsoft Data Link (UDL)
file in order to connect to the database. A s
ample udl file is located in the
SALESSYSTEM directory for you to configure for your particular database.
click the udl file in order to configure it. The following shows SalesSystem.udl
configured to access the development database describe
d in (1).
Now locate the Plex .NET runtime directory under the main AllFusion Plex r6.00 Alpha
directory (called ‘Ob.NET’). The Plex .NET runtime is structured as follows.
level Ob.NET directory contains va
files used to simplify the installation of the Plex .NET
‘bin’ directory contains both Debug and Release
versions of the Plex .NET runtime.
‘bld’ directory contains build support files used to
compile Plex generated
C# source; these files were
used when compiling the C# source in (4).
If you have not installed the AllFusion Plex r6.00 .NET Dispatch Service
, then now is the
time to do so. To install the service, double
click on the batch file
Once installed, you should be able to see the
Dispatcher installed as a service. Do not start the service yet
we need to configure the
x .NET runtime first.
Configure the Plex .NET runtime using the new AllFusion Plex .NET Management Studio.
To do this, start
. You should be
prompted to select a Plex .NET runtime executable to configure the runtim
e for. Select
to configure the runtime
associated with the service you installed in (8).
The .NET Management Studio currently allows you to maintain configuration information
on the following items.
level node contains the global configuration
information for the .NET Dispatcher, such as maximum
clients, default culture information, logging type and
configuration data that is on a
connection basis, such as assembly and additional
resource locations, connection culture information,
format preferences and special field values.
‘.NET/Java/System i Servers’ nodes contain the
ation data needed to make n
to other platforms that host Plex generated
Environment nodes also contain one or more
Database nodes. These contain configuration
information used when connecting to databases via
the Plex .NET r
untime. The primary one of interest is
the ConnectionString setting.
Highlight the environment called ‘Default’ to see its settings. Highlight the Assembly
parameter, and enter the path to the
built in step (5).
Highlight the database called ‘Default’ under the environment. Enter the following value:
<Path to .udl file>
is the absolute path to the .udl file,
using forward slashes
Save the configuration file by selecting File
Save All, and exit the Plex .NET
Start the AllFus
ion Plex r6.00 .NET Dispatch Service. You should see a log file called
created under the Event Viewer created that contains the following
[PLEX0016] Starting AllFusion Plex .NET Dispatcher on port 1998.
Locate the Plex generated cli
ent application in
In order for the Plex generated client to call the server application, it needs to be
configured to connect to the server (although the client and server are running on the
same machine, the principle is t
he same as if they were located on different machines).
To configure the client runtime, open the file
. This contains a section
that contains the connection information to connect to the .NET
server. The primary values
of interest are:
: The name of the system on which the Plex .NET Server application
: The port number that the remote machine is listening on.
: The name of the environment
on the server that contains the
tion for the application.
Because this example is running to the local machine,
on port 1998 using the default
environment, these values can be left as they are.
To run the application, double
to start the client application. Try out
the application by doing the following:
Enter some header records using the ‘Add new data.’ Button.
Enter some detail records for a selected header by selecting the ‘Detail’ button.
You can check the server status by checking the
see trace messages created each time a server function is called (this can be switched
off by a configuration setting against the dispatcher). The trace messages should
informational, and should
look as follows.
[PLEX0003] Received reque
st to call function SalesSystem.DetailSingleFetch_ObFnc.
[PLEX0002] Ended client session. Client=0.0.0.0:1998
[PLEX0006] Client calls made: 4 Client=0.0.0.0:1998
The Event Log (or trace file if you are directing messages to a file) is
also the first place
to look if your Plex .NET Dispatcher crashes. It is the information in these messages that
we will use to try and solve any runtime bugs that might still need to be ironed out.
(2) Visual Studio 2005 Integration
Open Visual Studio
2005 and create a new Visual C# Windows Application project. The
following shows a screenshot with the settings for the completed example under the
Open Form1 in design view, and add a DataGridView control to the dialog.
click on the main body of the form to add
an event to handle the Load event for
Form1. Visual Studio should jump to the code view for Form1.cs file, in a new method
from the main menu. From the Browse tab, navigate to
Runtime is located
(this should be
Add the CA.Plex.ObRun.dll as a reference to your project.
Add the following code at the st
art of Form1.cs after the
sections for the .NET
Add the following code to the method
// A DataSet to hold the input
// A DataSet to hold the output parameters
// Create a new Plex .NET Runtime instance
// Initialize dsInput with the format of the input data
// Set up the call information
// Set up the parameters for the call
] = 0;
// Call the Plex function
// Set the DataGridView.DataSource object to the FetchedData MOV
// FetchedData is one of the output variables re
turned in dsOutput
dataGridView1.DataSource = dsOutput.Tables[
Compile the project by selecting Build
Before running the example, you need to have Plex .NET Runtime configuration
information in the
file associated with the
Windows Forms executable. The
simplest way to do this is to copy the configuration file you used to run the previous
. Copy the file
location where your client executable wil
l be executed, and change it’s name to
Run the example by selecting Debug
Start Debugging. You should see a Windows form
appear, loaded with the Order Header data that you entered in the previous example.
to have the Plex .NET Dispatch Service running in order for this
example to work. The Windows Forms application contains the Plex .NET Runtime
instance being used.
The completed example in the
Visual Studio 2005 Clients
y contains additional code to save the parameter DataSet objects as XML
and also to save their schema format. The schema information is conceivably useful to
copy of the .NET Dispatch Service
.config file used in the previous
initialize the DataSet objects used for the call to the correct shape. Additionally, you cou
use XML data saved in the input variable group format to populate the input dataset.