General Guidelines for Writing Code

Please review these guidelines for important information that will assist you when writing code for Aptify.

• Loading the Sample Code and Templates
• Use Option Explicit and Option Strict
• Set Version Number Properly for Executables
• Avoid Data Readers
• Use Stored Procedures to Retrieve Database Values
• Override the Overload Method with the Most Parameters
• Coding for Sub-Type Records Should Be Done in the Context of the Top-Level Record

Loading the Sample Code and Templates

When you first open the source code provided with the sample application or a project template provided by Aptify, the project will most likely load with errors due to missing references.

After loading the project for the first time, you need to set the references for the Aptify assemblies to C:\Program Files\Aptify 5.5 (or whatever location you installed the Aptify desktop application on your computer).

Follow these steps to correct the reference path when loading a sample Aptify project:

1. Open the desired project in Visual Studio.
2. Open the Properties for the project. (One way to do this is to double-click My Project in the Solution Explorer.)
3. Click the References heading in the Properties screen to view the project's references.
4. If one or more Aptify references cannot be found, click the Reference Paths... button.
   
   
5. Browse to the location of your computer's Aptify application files (typically, C:\Program Files\Aptify 5.5) and click Add Folder.
   
   
6. Click OK to close the dialog and update the Aptify references.
   
   
7. Save your changes to the project.
   
   

Use Option Explicit and Option Strict

Aptify recommends that all classes turn on Option Explicit and Option Strict using the following statements at the start of a class file:

• Option Explicit On
• Option Strict On

Option Explicit forces the explicit declaration of all variables. Option Strict prevents data conversions that could result in loss of data. Refer to the Microsoft Visual Studio Documentation or the Microsoft MSDN for more information.

Set Version Number Properly for Executables

When you are developing executables that use the Aptify objects, it is important to set the Major version number of the executable to match the Major version number of Aptify. For Aptify 5.x, the Major version number is 5. This is required because the Login component requires a License check, and that License check verifies that the version number of the License matches the Major version number of the application. If there is no match, the License check will fail. Note that the sa login bypasses the License check so you will not experience this failure when logging in as sa.

Avoid Data Readers

The use of DataReaders for retrieving information from the Database in Aptify is not recommended. DataReaders are usually the most efficient/lightweight method of retrieving multiple rows of data in ADO.NET. However, that efficiency doesn't come without risks. It is the responsibility of the developer who requests a DataReader to properly manage and dispose of the DataReader. A DataReader maintains a live connection to the database while it is open. Failure to close and dispose of the DataReader can lead to connection management issues. The recommended method for retrieving multiple rows of data from the database in Aptify is to use a DataTable.

If you believe that your design will obtain significant benefits from using a DataReader in a specific function, Aptify strongly recommends that your project team perform an additional code review for that functionality in order to ensure that any DataReaders are properly used and disposed in the process.

Use Stored Procedures to Retrieve Database Values

Where possible Aptify recommends that you create stored procedures to retrieve values from the database. This approach is more efficient than including a SQL SELECT statement in your code and also allows modifications to the search logic without having to recompile the code.

Within the Visual Studio project, you should populate the stored procedure parameters using IDataParameter objects to set inputs for and receive output from the stored procedure.

The Visual Studio projects included with the sample application include several examples of how to retrieve data via a stored procedure, including the following:

• spGetStatusIDfromName: This stored procedure is used by the Rental Agreements and Service Tickets entity objects to obtain the ID of a Vehicle Statuses record.
  
  
• spGetVehicleCurrentStatus: This stored procedure is used by the Rental Agreements entity object to obtain the current status of a Vehicle.
  
  
• spGetVehicleServiceTicketCount: This stored procedure is used by the Service Tickets entity object to obtain the number of outstanding service tickets for a particular vehicle.
  
  
• spCheckForCustomerMatch: This stored procedure is used by the Customers entity's duplicate check object to determine if potential matches exist for a new record.
  
  
• spCheckForVehicleModelMatch: This stored procedure is used by the Vehicle Models entity's duplicate check object to determine if absolute or potential matches exist for a new record.

To add the stored procedure to SQL Server, create a Database Objects record for it within Aptify. See Creating Database Objects for information on the Database Objects service. Also, to ensure that these organization-specific objects are correctly migrated along with the entity, you should add a link to any Database Objects record you create to the corresponding Entities record's DB Objects tab.

Override the Overload Method with the Most Parameters

In many cases, a developer may find that a particular method has a number of overloads, and it can be difficult to determine which overload to override.

In these situations, check the Aptify Software Development Kit (SDK) first to see if the documentation indicates which overload is typically overridden. If not identified in the SDK, then the general rule is to override the overload that has the most parameters.

Coding for Sub-Type Records Should Be Done in the Context of the Top-Level Record

If writing code to create or update sub-type records, any save operations should occur for the top-level record and not for the sub-type record directly.