OpenPETRA Project Structure and Namespace Descriptions
(imported from Petra Wiki in September 2010)
openPETRA Project Structure
openPETRA consists of many Projects (>80 DLL Projects plus some Executable Program Projects).
See also Explanation of Directory Structure and Rules!
Conceptual Overview
- Petra Server and Petra ServerAdmin are small EXE projects (result in console applications)
- Contain only little functionality, main functionality is located in referenced DLL's
- allows rather easy creation of WinForm EXE by reusing functionality from the same DLL's
- Petra Client EXE is a small EXE project (results in a WinForm application)
- Contains only little functionality, main functionality is located in referenced DLL's
- small classes provide main functionality (eg. establish .NET Remoting connection to Petra Server, start 'Keep Alive' Thread, different Cache Managers, etc);
- WinForms, Logic etc. for Petra Modules are contained in separate DLL's
- Contains only little functionality, main functionality is located in referenced DLL's
- all other Projects are DLL projects (resulting in a DLL)
Reasons for having many DLL's
- separation of functionality between Client and Server (and Petra-independent [ICT Common] functionality)
- logical structure: files in one project are in one directory (most of the times)
- logic and verification are not in the same file as the WinForm -> much cleaner
- smaller compilation targets -> quicker compilation of changes
- to resolve circular references/dependencies
- contrary to Win32 programming, having many DLLs in .NET causes nearly no run-time overhead
- no run-time speed difference whether a class/procedure/function is locally available or in a different namespace, different dll, etc.
openPETRA Namespace Descriptions
(last updated on January 5th, 2010)
This description of the openPETRA Namespace structure is intended for developers so that they can get an understanding of the project structure and to help them in deciding in which Namespace to put Units and Classes that are to be added.
It covers most of the Namespaces that currently exist and Namespaces that will be used in the future. It is not always going down to detail level.
Ict.*
Main namespace for all ICT applications. No Projects/no program code is to be put directly in this Namespace - it just serves as a root namespace!
Ict.Common.*
Namespace for anything that is not specific to Petra and which therefore can be used by other ICT applications (no other ICT applications exist yet, though).
Ict.Common
Namespace for universal utility and helper functions. Contains eg. string helper functions, logging, helper functions, enums, etc. Can be used by all parts of openPETRA (Petra Client and Petra Server, etc).
Ict.Common.Controls
Namespace containing universal custom .NET WinForms controls. Some controls merely extend an existing control with some functionality, other controls are 'compositions' of controls with special functionality. Used eg. by the Petra Client.
Ict.Common.Conversion
Namespace containing Classes for data conversions.
Ict.Common.Data
Namespace containing base classes for Typed DataTables, Typed DataSets and the DataStore.
Ict.Common.DB
Namespace containing the DBAccess unit (for RDBMS-agnostic DB access) and other DB-related units. Used eg. by the Petra Server.
Ict.Common.EMailing
Namespace containing classes for accessing e-mail clients.
Ict.Common.IO
Namespace containing various Input/Output utilities, eg. MS-Excel automating class, XML Parser class.
Ict.Common.Printing
Namespace containing printing routines. At the moment used only by the Petra Reports.
Ict.Common.Verification
Namespace containing Classes for data verifications and for returning detailed errors and lists of detailed errors. Can be used by all parts of openPETRA (Petra Client and Petra Server, etc).
Ict.Petra.*
Main namespace for the openPETRA application. No Projects/no program code is to be put directly in this Namespace - it just serves as a root namespace for the Petra application!
Namespace containing shared libraries, used by the Petra Server and the Petra Client (as well as the Petra ServerAdmin program). This Namespace contains Classes that are used both by the Petra Server and the Petra Client (or by the Petra Server and the Petra ServerAdmin program) and classes that can be passed from the Petra Server to the Petra Client (and vice versa). Also contains custom Exceptions.
Except for Interfaces, DataTables, DataSets and DataAccess Libraries we should keep the Ict.Petra.Shared.* Libraries as small as possible - we want to share as little as possible functional code with the Client!
Namespace containing Classes and other things that need to be present on Server and Client side of openPETRA.
Examples: common Constants, common Remoted Exceptions, common Enums, etc.
Namespace containing a number of Interfaces to Classes on the Petra Server side. These are used by the Petra Client (some as well by the Petra ServerAdmin program) to make remote calls to classes for which they don't have the executable code of the classes. The Interfaces are a kind of 'contract' between Petra Client and Petra Server - the Petra Client knows through them what methods exist in the Petra Server, the Petra Server's Objects provide all the properties and methods as advertised in the Interfaces and execute the actual code. (Interfaces are not Objects themselves, but get implemented by Server Objects.)
Every Petra Module has several interfaces, eg. to create UIConnectors.
Reasons why we use Interfaces
- needed for .NET Remoting calls: Petra Client needs to call something on the Petra Server, for this it needs to know which methods and parameters are available - for compiling and running
- we don't want to distribute large parts of the Petra Server code to the Petra Client
- create a virtual Object Hierarchy in the Petra Server
All Interfaces that are located in files whose name ends in '.AutoHierarchy.cs' are auto-generated from the NamespaceHierarchy.xml file. Do not edit those files manually, otherwise your changes will be overwritten once those files are re-generated!!!
Namespace containing shared resources (eg. Strings, Icons).
Namespace containing a shared class that holds information about the currently connected user.
Namespace containing data verifications that can be used in procedures and functions to perform certain data verifications. Can be used both on Petra Server and Petra Client side.
This is a central place for verification code that is general rather than a concrete verification of certain fields of a certain DataTable.
None of the data verifications in here must access the DB since the Client doesn't have access to the database!
Examples: Date checks (eg. Date1 earlier then Date2), e-mail validity check (logical only), is-string-numeric, etc.
Namespaces containing Classes that can be passed from the Petra Server to the Petra Client (and vice versa) as well as functions which perform certain calculations that are needed on both sides - specific for the one Petra Module (Partner, Personnel, etc). Also may contain shared Exceptions, Types, Enums, Constants, etc.
Namespaces containing Typed DataTables for all Petra DB tables - specific for the one Petra Module (Partner, Personnel, etc). Automatically created from Petra XML file.
Namespaces containing Typed DataSets - specific for the one Petra Module (Partner, Personnel, etc). Automatically generated from Typed DataSet XML files. We maintain these XML files on our own and need to re-generate the Typed DataSets after each change.
Namespaces containing DataAccess objects for all Petra DB tables - specific for the one Petra Module (Partner, Personnel, etc). Automatically created from Petra XML file.
Namespaces containing DataAccess objects for cascading data operations (eg. cascading delete) for all Petra DB tables - specific for the one Petra Module (Partner, Personnel, etc). Automatically created from Petra XML file.
Ict.Petra.Server.*
Namespace for the PetraServer libraries.
Ict.Petra.Server.App
- Ict.Petra.Server.App.Core
Namespace containing core classes (eg. Server settings) for the Petra Server that are used by many parts of the Server.
- Ict.Petra.Server.App.ClientDomain
Namespace containing classes that manage the set-up and destruction of AppDomains for Client connections and the set-up of .NET Remoting Lifetime Management for those AppDomains.
- Ict.Petra.Server.App.ClientDomain.CallForwarder
Namespace containing helper classes for making remoted calls to AppDomains.
- Ict.Petra.Server.App.Main
Namespace containing the main logic for the Petra Server.
Ict.Petra.Server.MCommon
Namespace containing utility and helper functions that are Petra Server specific and are shared between several Petra modules.
Ict.Petra.Server.MPartner
Namespace for the Partner Module.
- Ict.Petra.Server.MPartner.Common
Namespace for utility and helper functions that are Partner Module specific.
- Ict.Petra.Server.MPartner.Partner
Namespace for all Partner-related processing, business rules, data verification and data segmentation.
Also contains Classes that return cacheable Typed DataTables (used by the Client-side data cache). Contains functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors. Example: TPPartnerAddressAggregate. Will in the future also contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples (not yet existing): TPartnerVerification, TPartnerDataSegmentation, etc.
- Ict.Petra.Server.MPartner.Extracts
Namespace that will hold all Extract-related functionality.
- Ict.Petra.Server.MPartner.Subscriptions
Namespace that will hold all Subscription-related functionality.
- More examples of sub-namespaces
Ict.Petra.Server.MPartner.PartnerMerge, Ict.Petra.Server.MPartner.PartnerMerge.Locations, Ict.Petra.Server.MPartner.ImportExport, Ict.Petra.Server.MPartner.Reports, Ict.Petra.Server.MPartner.Mailing, Ict.Petra.Server.MPartner.TableMaintenance, etc.
Ict.Petra.Server.MPartner.UIConnectors
Namespace for Business Objects that send and receive only necessary data (for a specific screen) in a most efficient way.
See 'UIConnectors (User Interface Connectors) = Business Objects of openPETRA'
Contains eg. TPartnerEditUIConnector, TPartnerFindUIConnector, etc.
Ict.Petra.Server.MPartner.Instantiator
Namespace for Objects that create (=instantiate) UIConnector objects on behalf of the PetraClient.
Code that is located in the 'Instantiator.AutoHierarchy.cs' is auto-generated from the NamespaceHierarchy.xml file. Do not edit anything outside the '#region ManualCode' section in this file manually, otherwise your changes will be overwritten once that file is re-generated!!!
Ict.Petra.Server.MPersonnel
Namespace for the Personnel Module.
- Ict.Petra.Server.MPersonnel.Common (not yet created)
Namespace for utility and helper functions that are Personnel Module specific.
- Ict.Petra.Server.MPersonnel.Person (not yet created)
Namespace for all Person-related processing, business rules, data verification and data segmentation.
Will in the future- contain Classes that return cacheable Typed DataTables (used by the Client-side data cache).
- contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
- contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TPersonVerification, TPersonDataSegmentation, etc.
- Ict.Petra.Server.MPersonnel.Unit (not yet created)
Namespace for all Unit-related processing, business rules, data verification and data segmentation.
Will in the future- contain Classes that return cacheable Typed DataTables (used by the Client-side data cache).
- contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
- contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TUnitVerification, TUnitDataSegmentation, etc.
Ict.Petra.Server.MPersonnel.UIConnectors
Same as Ict.Petra.Server.MPartner.UIConnectors.
Would contain eg. THierarchyUIConnector, TJobsUIConnector, TCostsUIConnector, etc.
Ict.Petra.Server.MPersonnel.Instantiator
Same as Ict.Petra.Server.MPartner.Instantiator.
Ict.Petra.Server.MFinance
Namespace for the Finance Module.
- Ict.Petra.Server.MFinance.Common (not yet created)
Namespace for utility and helper functions that are Finance Module specific.
- Ict.Petra.Server.MFinance.Gift
Namespace for all Gift-related processing, business rules, data verification and data segmentation.
Will in the future- contain Classes that return cacheable Typed DataTables (used by the Client-side data cache).
- contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
- contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TGiftVerification, TGiftDataSegmentation, etc.
- Ict.Petra.Server.MFinance.AccountsPayable (not yet created)
Namespace for all AccountsPayable-related processing, business rules, data verification and data segmentation.
Will in the future- contain Classes that return cacheable Typed DataTables (used by the Client-side data cache).
- contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
- contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TPartnerVerification, TPartnerDataSegmentation, etc.
Ict.Petra.Server.MFinance.UIConnectors
Same as Ict.Petra.Server.MPartner.UIConnectors.
Ict.Petra.Server.MFinance.Instantiator
Same as Ict.Petra.Server.MPartner.Instantiator.
Ict.Petra.Server.MConference
Namespace for the Conference Module.
- Examples of sub-namespaces
Ict.Petra.Server.MConference.Common, Ict.Petra.Server.MConference.Setup, Ict.Petra.Server.MConference.Management, etc.
Ict.Petra.Server.MConference.UIConnectors (not yet created)
Same as Ict.Petra.Server.MPartner.UIConnectors.
Ict.Petra.Server.MConference.Instantiator
Same as Ict.Petra.Server.MPartner.Instantiator.
Ict.Petra.Server.MFinDev
Namespace for the Financial Development Module.
- Examples of sub-namespaces
Ict.Petra.Server.MFinDev.Common, etc.
Ict.Petra.Server.MFinDev.UIConnectors (not yet created)
Same as Ict.Petra.Server.MPartner.UIConnectors.
Ict.Petra.Server.MFinDev.Instantiator
Same as Ict.Petra.Server.MPartner.Instantiator.
Ict.Petra.Server.MSysMan
Namespace for the System Manager Module.
- Ict.Petra.Server.MSysMan.UserDefaults
Namespace containing System Manager maintenance functionality for User Defaults.
- Ict.Petra.Server.MSysMan.SystemDefaults
Namespace containing System Manager maintenance functionality for System Defaults.
- Ict.Petra.Server.MSysMan.ErrorLog
Namespace containing Petra Error Logging functionality.
- More examples of sub-namespaces
Ict.Petra.Server.MSysMan.Common, Ict.Petra.Server.MSysMan.Application, Ict.Petra.Server.MSysMan.PrintManagement, etc.
Ict.Petra.Server.MSysMan.UIConnectors (not yet created)
Same as Ict.Petra.Server.MPartner.UIConnectors.
Ict.Petra.Server.MSysMan.Instantiator
Same as Ict.Petra.Server.MPartner.Instantiator.
PetraServerConsole.exe
The Petra Server application. Implemented as console application.
Ict.Petra.ServerAdmin.Core
Contains logic for the PetraServerAdmin application.
PetraServerAdminConsole.exe
'Remote control' application for the PetraServer. Implemented as console application.
Ict.Petra.Client.*
Namespace for the PetraClient libraries.
Ict.Petra.Client.App.*
Namespace for the internal logic of the GUI application.
- Ict.Petra.Client.App.Core
Core classes (eg. for Server connection, caching, user preferences) for the Petra Client that are used by many parts of the Client.- Ict.Petra.Client.App.Core.RemoteObjects
Contains a class which holds all references to instantiated Server-side objects that are remoted by the Server. - Ict.Petra.Client.App.Core.Shared
Contains things that should be in Ict.Petra.Client.App, but would create too many dependencies in other projects.
- Ict.Petra.Client.App.Core.RemoteObjects
- Ict.Petra.Client.App.Formatting
Contains functions and procedures for custom formatting/parsing on the Client side.
- Ict.Petra.Client.App.Gui
Contains procedures and functions to help with various GUI issues.
Ict.Petra.Client.CommonControls, Ict.Petra.Client.CommonDialogs, Ict.Petra.Client.CommonForms
Namespaces containing Petra-specific re-usable parts of the GUI that are not tied to a certain Petra Module.
- CommonControls
contains Petra-specific .NET WinForms Custom Controls and UserControls
- CommonDialogs
contains Petra-specific Dialog-style windows (eg. Login, Progress Dialog, etc)
- CommonForms
contains Petra-specific inheritable WinForms which help maintain a common look-and-feel and functionality.
Ict.Petra.Client.M*.Gui
Contains the screens (WinForms) of the GUI (Graphical User Interface) for each of the Petra Modules. Classes in this Namespace should only be WinForms and they should not contain logic or verification code at all!
Contains screens like PartnerEdit, PartnerFind, etc.
Ict.Petra.Client.M*.Logic
Contains the logic parts that make the GUI for each of the Petra Modules work. Each Class contains logic for one associated screen, such as loading/processing/saving data.
Ict.Petra.Client.M*.Verification
Contains code for data verification of each of the Petra Modules. Each Class contains data verification for one associated screen.
Example: Checking whether 'From Date' lies before 'To Date', e-mail verification, etc.
Note: Code in here will in most cases just make a series of calls into Ict.Petra.Shared.Verification with the data and texts as applicable to the one screen.
PetraClient.exe
The Petra Client application. Implemented as WinForms application.
Resulting Assemblies
Apart from some exceptions (see below), we create an assembly (DLL) from the fourth level namespace onwards:
- Ict.Petra.Server.MPartner.dll (contains all classes in Ict.Petra.Server.MPartner.Partner, Ict.Petra.Server.MPartner.Partner.Cacheable, ...)
- Ict.Petra.Server.MPersonnel.dll (contains all classes in Ict.Petra.Server.MPersonnel.Person, Ict.Petra.Server.MPersonnel.Unit, ...)
- Ict.Petra.Server.MFinance.dll (contains all classes in Ict.Petra.Server.MFinance.Gift, Ict.Petra.Server.MFinance.AccountsPayable, ...)
- Ict.Petra.Server.MConference.dll (contains all classes in Ict.Petra.Server.MConference.Setup, Ict.Petra.Server.MConference.Management, ...)
- Ict.Petra.Server.MSysMan.dll (contains all classes in Ict.Petra.Server.MSysMan.Security, Ict.Petra.Server.MSysMan.Maintenance, ...)
- Ict.Petra.Server.MFinDev.dll (similar than those above)
...except for some fifth-level namespaces that are either a) likely to change frequently, b) likely to not change frequently, c) are quite big, d) are shared between Server and Client:
- Examples for a): Ict.Petra.Server.M*.UIConnectors.dll, Ict.Petra.Server.M*.Instantiator.dll
Contain/create business objects (eg. TPartnerEditUIConnector) that are called by the Client. These form the server-side logic of a certain Petra Screen/functionality.
- Example for b): Ict.Petra.Server.M*.Common.dll
Contain common functions that are not likely to change often.
- Examples for c): Ict.Petra.Server.MPartner.PartnerMerge.dll, Ict.Petra.Server.MPersonnel.Person.dll
Namespaces that are likely to result in a lot of code lines and are rather independent of a) the fourth-level namespace business objects in the same Petra module (eg. Partner Merge), b) or other fifth-level namespaces in the same Petra module (Person).
- Examples for d): Ict.Petra.Shared.Interfaces.*.dll, Ict.Petra.Shared.M*.DataAccess.dll and Ict.Petra.Shared.M*.DataTables.dll
Shared between Server and Client and therefore in separate assemblies.
For the Client, some fifth-level namespaces are separate assemblies as well:
- Ict.Petra.Client.MPartner.Gui.dll
- Ict.Petra.Client.MPartner.Logic.dll
- Ict.Petra.Client.MPartner.Verification.dll
The reasons for that are: 1) keep GUI definition separated from logic (and database field names), 2) building a project that contains WinForms takes considerably longer than other projects because of resource compiling and linking, therefore if we change something in the logic (eg. database field names) or data verification we don't want to compile the WinForm (that hasn't changed at all), 3) allows smaller libraries (although they will have hundreds of files in them...), which compile faster.
For certain namespaces and the executables for Server, ServerAdmin and Client we create separate assemblies as well:
- Ict.Common.dll
- Ict.Common.DB.dll
- Ict.Petra.Shared.dll
- PetraServer.exe
- PetraServerAdmin.exe
- PetraClient.exe