NetQuarry.Data Namespace

Data

The NetQuarry Enterprise Application Platform (EAP) allows you to build and deploy n-tiered, enterprise quality applications. The EAP sits on the Microsoft .NET common language runtime and provides rich functionality at all layers of an application.

The NetQuarry EAP does not generate code, rather, it uses the NetQuarry Core Runtime, custom configuration, metadata, and developer coded extensions to construct world class, quality applications.

Data Sources

Business applications depend on data. Increasingly, this data comes from multiple data “sources” across the enterprise. These sources of data may exist in relational databases such as Oracle, Microsoft SQL Server, or IBM DB2. Some of the sources of data, however, exist as Web Services, XML documents, or remote procedure calls. NetQuarry makes aggregating disparate data into a single, functional user interface simple and fast.

Extensions

Extensions are a key concept of the NetQuarry platform. Extensions are libraries that receive events from the running application objects. For example, when a record in a page is changed, the IMapper representing that data fires update events (notifications) through all of the extensions configured (via metadata) on that object.

This is a powerful programming pattern that is extremely simple for application developers, even those unfamiliar with Microsoft .NET to quickly grasp and master.

To create an extension, the developer can run a wizard from the Studio that allows them to specify the name, location, language (C#, VB.NET), and which objects they want to attach the extension.

Some objects support the idea of “global” extensions (e.g. Mapper-based objects). A global extension is automatically attached to all objects of a particular class. This is particularly useful for functionality such as auditing and summary information handling.

Extensions must implement a known interface (IExtension) or derive from a provided base class. The most common type of extension is the mapper extension which typically derives from MapperExtensionKernel or TypedMapperExtension). Most non-declarative business logic is implemented in mapper extensions. Most applications also include a small number of page extensions (derived from PageExtensionBase for handling wizard and console page events, and a single application extension (derived from ApplicationExtensionBase).

Examples

using System;
using NetQuarry;        // Include the NetQuarry objects

namespace XCustomer
{
    public class XExt : MapperExtensionKernel
    {
        public XExt() {}

           public override void RowBeforeUpdate(IMapper sender, NQEventArgs e)
           {
            IField        fld = sender.Fields["forecast_discount_amount"];

            if (System.Convert.ToInt32(fld.Value) > 10)
                fld.Value = 10;
        }
    }
}

Handling business logic using this methodology is both simple and robust. Extensions can be reused across multiple objects, they can be debugged interactively using Visual Studio, and they hide the complexity of the infrastructure from the application developer allowing them to concentrate on the task of building business applications.

Mappers

A Mapper (IMapper) is the primary means of mapping object-oriented programming objects to data sources managed by relational databases or other sources of data. A Mapper provides 2-way (Read and Write) access to the underlying Data Source.

There are several subclasses of the Mapper object. The most important are the MapperDatasheet and MapperDetail. Each provides an implementation that uses the data in the Mapper to render a view of the data using HTML.

Application (IAppContext)

The Application object holds information that is used throughout each page (or server) request. The Application is available to all objects, most importantly the extensions. The Application object is created as the first object in any request, and when possible it is cached for performance purposes.

The Application object handles connecting to the authentication provider, authenticating the user, checking object permissions for that user, storing user (UserContext) information, holding the list of available PageInfo objects, and connecting to the metadata (Repository) data source. It also has a collection of DataSources specified in metadata.

More than one Application object may be specified in metadata, and connecting to an application allows the user to see more than one “view” of an implemented NetQuarry application.

Pages and Templates

A Page is the smallest object that renders user interface. Some pages display data from a IMapper, while others allow the user to perform a quick search, quick creation of an object, or perform some sort of navigation.

A Template is a code-based layout of one or more areas (called Slots). Each slot in a template is specified using a Page property at design time.

Properties and TextItems

Many NetQuarry platform objects support a collection of custom Properties. Properties are fields of information that varies between objects and object instances. Most properties are loaded from the metadata when the object is created. A property that is loaded from metadata has an associated parameter object (a metadata only object) defined in the metadata. Properties can be added at runtime or design time. At design time, parameters form the definition for the NetQuarry studio’s property sheet.

TextItems are similar to properties but hold only strings. Additionally, each TextItem object is specific to a locale (or culture). At runtime, Textitems are loaded for the current user’s culture. If there is no string for the type of text for the current culture, the default culture is used. All strings used in the platform are represented as TextItems. This provides a simple way to support multiple user languages (cultures) on a single site, with a single codebase.

Properties and TextItems provide programmatic access to virtually all meta-data associated with an object.

Logging

The platform is proactively logging a rich set of data to help the developer diagnose problems during development and runtime. Additionally, the developer can use the built-in object called DevLog to add messages to the log.

Using Mappers

If you create a resource that has a connection to a database (IDatabase) object such as a Mapper, you must close the Mapper before exiting the procedure.

TypedMappers

Generated TypedMapper derived classes are useful when manipulating a mapper and you would like to treat it more like a type-safe object. They are also useful as a base class for higher level business objects that you may require in your extensions. A TypedMapper has a Get and Set property for every field defined in the mapper. If you have fields with an include flavor you may need to add a Get and Set property in your derived class as the generator will not pickup these fields.

You typically use a TypedMapper in your extensions. You can create a TypedMapper and attach it to the sender (IMapper) of the event or you can use the TypedMapper derivative to create a new mapper - either for the purpose of creating a new row or reading/updating an existing one. Connecting a TypedMapper via one of the constructors or TypedMapper.Attach is very inexpensive and generally a safer way to work with a mapper. You should, however, use good judgement when creating a new instance of a TypedMapper as a query of the operational database is generally required.

Generating TypedMappers

To generate typed mappers you run the command line utility EAP.Tools.CodeGen.EXE installed in the <application root>/bin folder. The utility takes the following arguments (the first argument (-AppID) is required):

1. -AppID:<appid> - the ID for your application.
2. -CamelCase - (optional) include this to convert property names to a CamelCase representation. By default, property names are the same as the mapper field's key name
3. -NullableNumerics - (optional) include this to declare the numeric field properties as Nullable. By default, numeric properties are defined as their value types and 0 (or false) is returned if the value is null.
4. -NoNullStrings - (optional) include this to force string properties to return an empty string instead of null when the field value is null. By default, null values are returned as null strings.

<configSections>
    <section name="IssueTrak" type="System.Configuration.NameValueSectionHandler" />
</configSections>

<IssueTrak>
 <!-- connection strings -->
 <add key="repository_connect" value="Provider=SQLOLEDB;Data Source=.;Initial Catalog=issues_meta;Integrated Security=SSPI" />    
 <add key="IssueTrak_connect" value="Provider=SQLOLEDB;Data Source=.;Initial Catalog=issues_data;Integrated Security=SSPI" />

 <!-- optional, normally set by the web application context -->
 <add key="RootPath" value="c:\inetpub\wwwroot" />
 <add key="RootURL" value="http://localhost" />

 <!-- full path to the file to be generated -->
 <add key="GeneratedFileName" value="C:\NetQuarry\IssueTrak\Source\Data\Generated\TypedMappers.cs" />
 <!-- namespace to use for the generated TypedMapper classes -->
 <add key="Namespace" value="IssueTrak.Data" />
</IssueTrak>

Example:

SET APP_KEY=IssueTrak
EAP.Tools.CodeGen -AppID:%APP_KEY% -CamelCase -NoNullStrings