TekNewell C# OOP Framework - User Manual and Instructions

Version v5.2 - Target: Release (OOP) - Built on: 3/27/2024 9:00:18 PM - Released on: 3/27/2024 9:01:23 PM

Home


Table of Contents


clapse    expand

expand A.How to use the document
1.Navigation
2.Search
3.Samples and Figures
4.Version Icons
expand B.About TekNewell C# OOP Framework
1.What is OOP Framework?
2.System requirements
3.Purposes
4.How it works
5.License Agreement
expand C.How to acquire OOP Framework
1.Trial Version
2.Product Version
expand D.How to set up and use
1.Unzip the file
2.Run for the first time
3.Upgrade Version
4.Rollback Version
expand E.The model
1.The model file
2.The input sheet files
expand F.The commands
1.Summary of The commands
2.OopPackage
3.OopClasses
expand G.Other commands
1.OopDll
2.OopDll
expand H.Create first code version
1.Main of Create first code version
2.Include the first version package
3.General c# file code lines
4.10 User Regions
expand I.Upgrade code version
1.Main of Upgrade code version
2.Include the new version package
3.Algorithm of the Upgrade
4.Cancel the Last Upgrade
5.Safety of Upgrade
expand J.Object Hierarchical Chart
1.Main of Object Hierarchical Chart
2.Hierarchy Detail
3.A Convenient Feature
expand K.The OOP Mindset
1.Main of The OOP Mindset
expand L.Summary of Benefits
1.Main of Summary of Benefits
expand M.Back up
1.Purpose
2.Backup a Must
3.How to
4.Method
expand N.History of Changes
1.

Presentation of Contents




A. How to use the document


1. Navigation

This document is well structured and easy to navigate through. Please navigate up and down through left panel Tabel of Contents.

2. Search

hit both 'Ctrl' + 'f', and type in the word and hit 'Enter' to search for. hit 'F3' to search for next occurrence.

3. Samples and Figures

Samples and figures provided in this document are not necessarily coherently in binding in design. It is up to the user to make his or her 'story' complete by applying the principles.

4. Version Icons

Icons like these     ... indicate the associated section is a new or revised section with a new version number.


B. About TekNewell C# OOP Framework


1. What is OOP Framework?

TekNewell C# OOP Framework is a software tool. It is built to run on MS Windows and the executable is 'oopf.exe' which is inherited from its brother product Excel Accocunting Tool's executable name. It takes input Excel file(s) and produces output Excel files and C# object files over previous version.

2. System requirements

It requires :
  1. a Windows 7, 8, 10 or 11 OS system
  2. a Windows Microsoft.NET Framework 4.6.1
  3. an Internet browser
  4. a Microsoft Office Excel program, Google Sheets On-line or other equivalents
  5. a license from Teknewell
  6. The download may be blocked by your browser. Choose 'Keep' or 'Keep Anyway'.
  7. The zip file may be blocked by Windows, goto the zip file's property, unblock it, and then extract to your desired disk location.
  8. The program executable may be blocked by Windows or Virus Protection. Choose 'Run' or 'Run Anyway' or Excludsion.

3. Purposes

The tool is very convenient and versatile. It allows developers design, implement Object Hierarchy with OOP mindset easily in time ever.

4. How it works

Each developer owns a copy of this tool. He or she uses it to create and upgrade the Object Oriented Programming source code version. The source code files are created in design based on Object Hierarchical Chart created by the tool previously, and once it upgrades, a new chart is again created for future design. Hence it creates a series of healthy cycles one after another. The collection of object code files are like an enterprice's factories, offices and building floors that were built already. A developer just need to assign furnitures, machines and work units into each room. This totally eliminates the lack of design in the procedure-oriented programming method and the shortcomings that comes with it.

5. License Agreement

Users should have at least once read the User Purchase and License Agreement at time of using the Trial version. Subsequent decision to purchase the software indicates user agrees without preservation the provisions set forth in the document of User Purchase and License Agreement.

Teknewell is a registered legal company in Massachusetts USA, The product tools are safe. Please also read the readme.txt if available.
Here you can access User Purchase and License Agreement


C. How to acquire OOP Framework


1. Trial Version

Goto Trial Download to download a trial version. The trial version only lasts for 1 month. Follow on-screen instructions, and you should have downloaded the file 'eatprooop.zip'.

2. Product Version

If you felt Teknewell C# OOP Framework tool is a useful and can help you adapt to OOP Mindset, and decided to acquire, then goto Teknewell C# OOP Framework Tool to purchase a license.


D. How to set up and use


1. Unzip the file

Once downloaded, unzip to the file to your desired location in disk. You can right-click the file 'oopf.exe' and then click on 'Pin to Taskbar'. You can click the icon on Taskbar in continuous use.

2. Run for the first time

After you click the icon on Taskbar, the Framework Manager will run and prompt user to enter the license key. You can find the key in your email. You should also save a copy of the email for future reference. By this time you are all set and ready to set up your models for projects.

3. Upgrade Version

Supposing you have setup the model fiels, go to the page 'Run' and click on the button 'Upgrade', the version will be upgraded.

4. Rollback Version

Supposing you have run the button 'Upgrade', and a new version was upgraded, but you decided not to move to the new version, you can rollback to the previous version. Doing that, you can click on the button 'Rollback' at the bottom-right corner on the page 'Run'. In order to run smouthly, the last version number in the staging directory must equal the version number chosen in the project. All these configuration steps can be performed manually.


E. The model


1. The model file

Under the directory 'model', user creates model files prefixed with 'model' like model-*.xlsx. In this file you can specify the location of input files. There are few commands available. See following table of commands. Note user can edit Excel file in Microsoft Office Excel, LibreOffice Calc or a Google Spreadsheet.

2. The input sheet files

Under the directory specified by command 'scan' in model file, you can supply Input sheet files prefixed with 'eat' like eat-*.xlsx. The commands are described in following chapter.


F. The commands


1. Summary of The commands

There are 2 commands. One is named 'OopPackage', the other 'OopClasses'. The first is singular, the other plural. There is a field for both commands, it is called Prefix, and they have to match for both. And at this time there is only one Prefix that is being processed for 1 model. The prefix is to identify 1 package of version in which a set of objects are closely related and serve in unison. The 2 commands are described in great detail below.
Term: Double cell definition (DCD) is that if a cell value is not empty, and it is a file name, then the content of the file is used. If it is not a file, then the cell value is used. If it is a file, it is assumed that the the file resides in directory defined in column I of command 'OopPackage'. In fact, all files are assumed residing in the directory.
Note: user can write any comments and memos beyond the rightest column described here in the 2 commands. The memo can help user to recall any design details to upgrade the furthering design. Note: the 2 commands and even same commands do not have to be on the same sheet of Excel Spreadsheet book. That means user can organize the commands into categories where he or she sees making business senses.

2. OopPackage

Column What Example
A Command Name OopPackage
B Prefix john
C Global Class Name AAGlobalStorageCenter
D Foundation Class Names Foundation1|Foundation2
E Not Used
F Not Used
G Project File (csproj)
H Project Folder Name projectAI
I Assistant File Folder Name john_feed_files
J Staging Folder Name john_Staging_Folder
K # of Versions to Keep 20
L Region Marker (long, short or none) long
figure 2520
  1. Column B 'Prefix' is used to prefix all file names and class names, which uniquely identify a package of version in unison.
  2. Column C 'Global Class Name' is used to specify the global class name. This class should also has been defined in command 'OopClasses' and should be without a base class. This class is the first class in package to be instanciated. All other classes instanciated will be registered within this class after it is registered in their deepest base class 'foundation' defined in column D.
  3. Column D 'Foundation Class Names' is used to specify the deepest base class names. User can specify multiple such classes. The names are separated by |. This is useful because a base class can be used simply to categorize a group classes and the base class can have zero number of members. Each of the classes should also has been defined in command 'OopClasses'. These classes in common hold a pointer to the global class in column C. These classes can be a class defined in this package or a class foreign like Window's class 'IDisposable'.
  4. Column G 'Project File (csproj)' is used to specify a project control file in extension '.csproj'. This file is used to have the previous package link names replaced by the new ones.
  5. Column H 'Project Folder Name' is used to specify the project folder where the previous version is read from and new upgraded version was written to. The version directory takes the format 'Auto_p_0000032.dir' where 'Auto' is the prefix, '0000032' is the version number, 'p' and 'dir' are a fixed marks.
  6. Column I 'Assistant File Folder Name' is used to specify a folder where files in collumn G,H,I,N and O of command 'OopClasses' are read from.
  7. Column J 'Staging Folder Name' is used to specify a folder where all past versions are held as the files were prepared, upgraded and transfered. Each upgrade directory takes the format 'Auto_s_0000032.dir'. This upgrade directory contains 2 directories. One is 'Auto_migrate.dir' and the other 'Auto_input.dir'. All names contains the prefix name. Here it is 'Auto' as example.
  8. Column K '# of Versions to Keep' is used to specify an integer number which is the max number of staging version directories and project version directories allowed. This means the older versions are deleted.
  9. Column L 'Region Marker (long, short or none)' is used to specify which region write-out format is desired. 3 choices are available, long, short or none.

3. OopClasses

Column What Example
0A Command Name OopClasses
1B Prefix john
2C Identity 100
3D Community Name UIPages
4E Class Name PriceFormBase
5F ToolTip Notes Used with PayClass
6G Old Different Class Name
7H Base Class Name PriceForm
8I Is Deep Base Foreign? PriceForm
9J Replacing Formula
10K Document Decree auto_commentsNotes.cs
11L Common Usings auto_common_usings.cs
12M Debug only? yes
13N Not Used JohnPricePackage
14O Class Modifier internal
15P Base Class Trailer , interface1
16Q Constructor priceForm.cs
17R Other Data and Code otherCode.cs
figure 2520
  1. Special Notes: for all links to files, please provide the file's full path and name to the link as well as the title in cell. please provide the file's full path and name to the link as well as the title.
  2. Column C 'Identity' is used to mark an object file on the #region lines. It is useful to use this ID number to write to Log to mark this object.
  3. Column D 'Community Name' is used to categorize a set of class families that are working for 1 functional purpose. Each family consists of classes bound by inheritance. The community name is part of the file name after prefix. If the community name is not provided, the default 'Cfn' is used. To change a community name, append the new community name at end of the existing one along with a pipe char leading it. For example, the previous community name is 'key' and the new is 'lock', then enter 'key|lock'. To change to a new community name at an empty cell, make sure to type in the old community name from its ancestor, then the new name. The cell emptiness does not mean it does not have a community name. To get the previous community name, user have to refer to the previous class hierarchical map or its previous file name. You can start a new community within a large community. The derived classes don't need one, and leave them blank. They will be joining the community by inheritance. The benefit of having a community name as part of the file name is that they can be identified as a group through file names and transfered or handled as a set in batch.
  4. Column E 'Class Name' is used to name the new object.
  5. Column F 'ToolTip Note' is used to show a tooltip note at a cell next to the class name cell in the chart. This is important when user needs quick note of how a class is meant to be used.
  6. Column G 'Old Different Class Name' is used to upgrade from a different object in case user want to change the file name and object name. It is a one time operation. It is assumed the Prefix is added as file name too. Once this upgrade is completed, user should remove the old name for next upgrades.
  7. Column H 'Base Class Name' is used to name the base object. In c#, the inheritance is from singular object. We recommend to write it right after colon ':' and other interfaces to follow.
  8. Column I 'Is Deep Base Foreign?' is used to indicate the base class is from a foreign package. All derived classes should also say so. If yes, the cell for 'Base Class Name' should be empty and the foreign base class name should be in cell 'Base Class Trailer', for example like, ' : ForeignClass'. All constructors should be supplied through cell 'Constructor'.
  9. Column J 'Replacing Formula' is a Double cell definition (DCD), and used to replace strings in upgrade process. The formula has 2 level of separators. The old string and new string are separated by '|1|' and the pairs are further separated by '|0|'. For example, OldString1|1|NewString1|0|OldString2|1|NewString2|0|OldString3|1|NewString3
  10. Column K 'Document Decree' is a DCD, and used for manager to issue decree of how the documents and notes should be written into source code.
  11. Column L 'Common Usings' is used to include the commonly used 'using' statements of assemblies. Additional 'using' statement can be put in in region 'Usings'.
  12. Column M 'Debug only?' is used to indicate an object is for Debuging mode only. Its value is either 'true' or 'yes' for positive.
  13. Column N 'Not Used' was used for NameSpace. Now the NameSpace is 'OopNameSpace' + Prefix. Each package can only has one NameSpace.
  14. Column O 'Class Modifier' is used to include class modifiers like 'public' or 'internal' before clause 'class'.
  15. Column P 'Base Class Trailer' is used to include additonal clauses like interface after the base class or just the class itself.
  16. Column Q 'Constructor' is used to replace the default constructor syntax. If you wish having no Constructor, simply write in cell 'none'.
  17. Column R 'Other Data and Code' is used to include additional data and code in Auto-generated region.


G. Other commands


1. OopDll

Fields:
ColumnWhatExample
ACommandNameOopDll
BDllFileNamecodeSnippet.dll
CNameSpaceCodeSnippet
DClassNameClass1
EMethodNamewriteCodeSnippet
FTaskNameCodeSpippet
GAccountNameBaChecking
HData01fieldName1
IData02value1
  1. Column A 'CommandName' is used to specify the command.
  2. Column B 'DllFileName' is used to specify the dll file name with extension.
  3. Column C 'NameSpace' is used to specify the NameSpace name in the dll project.
  4. Column D 'ClassName' is used to specify the class name within the NameSpace.
  5. Column E 'MethodName' is used to specify the method name to which the main program EatUi.exe will calll. Copy the method prototype from below.
  6. Column F 'TaskName' is used to specify the task name.
  7. Column G 'AccountName' is used to specify the account name. User can place more than 1 account names here , the names are separated by a char '|'. If they are multiple account names, the multiple method prototype is used instead of the single one. Refer to below for the second prototype.
  8. Column H 'Data01' is used to specify additional data. they can be a field name, a field value or other data user prefers.
  9. Column I 'Data02' is used to specify another data and no limit is set for how many to follow.
Sample: 'OopDll':
auto

Description:
Please copy the method prototype to build a dll project. The returned array will be presented in a sheet named as 'AccountName-TaskName'. The array contains rows of columns. The columns are separated by a Tab char. The first column will be shown at column A.

DLL Method Prototype:
auto

2. OopDll

Description:
The second sample with generic CakeCut function.

Fields:
ColumnWhatExample
ACommandNameOopDll
BDllFileNamecodeSnippet.dll
CNameSpaceCodeSnippet
DClassNameClass1
EMethodNamewriteCodeSnippet
FTaskNameCodeSpippet
GAccountNameBaChecking
HFieldNamesfieldName1|fieldName2
IRow filterfieldName|value1
  1. Column A 'CommandName' is used to specify the command.
  2. Column B 'DllFileName' is used to specify the dll file name with extension.
  3. Column C 'NameSpace' is used to specify the NameSpace name in the dll project.
  4. Column D 'ClassName' is used to specify the class name within the NameSpace.
  5. Column E 'MethodName' is used to specify the method name to which the main program EatUi.exe will calll. Copy the method prototype from below.
  6. Column F 'TaskName' is used to specify the task name.
  7. Column G 'AccountName' is used to specify the account name. User can place more than 1 account names here , the names are separated by a char '|'. If they are multiple account names, the multiple method prototype is used instead of the single one. Refer to below for the second prototype.
  8. Column H 'FieldNames' is used to specify filed names separated by char '|'.
  9. Column I 'Row filter' is used to specify the pair of field name and value, which qualifies a row with the same value on the field.
Sample: 'OopDll':
auto



H. Create first code version


1. Main of Create first code version

In first run, there is no upgrade available. Other than that there is no other difference. The first version number is 1. A first staging directory is created in 'Auto_s_0000001.dir' and a first version package project directory 'Auto_p_0000001.dir' is created in the project folder. There is only one step user can take to run. Once the 'oopf.exe' is up, it will show the Run page. User will choose the right model, then click 'Create Report'. The result data will show in the list on the same page.

2. Include the first version package

After a successful first run, user need to go to the Visual Studio Project, click an icon called 'Show all files' on top of Solution Explorer. The new project folder 'Auto_p_0000001.dir' will show. user can right-click and select 'Include in Project', then the package will participate in the project.

3. General c# file code lines

In each object file, the text lines are typical c# source code lines for a class. Following top component lines are in the file. Those lines are called a region. All regions are folderable.
  1. Top Manager decree region
  2. FileDefinition region
  3. Common Using statement region
  4. Additional Using statement region
  5. NameSpace region
  6. Bottom Manager decree region
In NameSpace region, there are 2 regions:
  1. Extra Supporting class region
  2. Class region
In Class region, there are 8 regions:
  1. Constructor region
  2. Destructor region
  3. Auto-generated region
  4. Data region
  5. Property region
  6. Method region
  7. Virtual region
  8. Override region

4. 10 User Regions

In the regions listed above, following 10 regions are for user to write in. Note that the class is spelled as clxss. This is because the tool looks for the word 'class' to identify a class. In order to avoid confusion, the word is changed as such.
  1. FileDefinition region
  2. Additional Using statement region
  3. Extra Supporting class region
  4. Constructor region
  5. Destructor region
  6. Data region
  7. Property region
  8. Method region
  9. Virtual region
  10. Override region


I. Upgrade code version


1. Main of Upgrade code version

When there is a new decree, a revision of class hierarchy, or versionwide dessemination, a developer should make an upgrade to a new version.

2. Include the new version package

After a successful run, the tool will update the project file (csproj) specified in column G of command 'OopPackage' with the new project directory name automatically, provided that the new package version number is right above the previous package number by 1. After the project file automatical update, and user flips over the Visual Studio, it will prompt user whether to make the change or ignore. If not update in any means or updated but there were new object classes added, user have to update manually. User can do the same described in previous chapter to exclude the previous package and to include the new package. Note: the manual inclusion process will add the new object classes in whole, while the auto-process will not.

3. Algorithm of the Upgrade

Following steps are involved in each upgrade. They are all automatical except when there is an error, user need to fix the error and run again.
  1. get the new version number
  2. create the shell (or skin) for the new version. This includes all new decree, new auto-generated codes, new using statements, revision of class line and constructor line, etc.
  3. migrade all user code from user code regions.
  4. transfer the new version to the project folder.
  5. exclude the previous version in Visual Studio project
  6. include the new version into Visual Studio project
  7. build the project
  8. if build is a success, then done.
  9. if build is a failure, then cancel the upgrade by deleting the new version directory 'Auto_s_0000001.dir' in staging area, then make changes to fix the error and go back to step 1, run again.

4. Cancel the Last Upgrade

By deleting the new version directory 'Auto_s_0000001.dir' in staging area, the user could start over again. In the next run, the project new version directory 'Auto_p_0000033.dir' is renamed to a name contains the word 'removed', user could delete them in the future when peaceful in terms of risk of data loss.

5. Safety of Upgrade

The upgrade is completely safe. user can switch back to previous version without any issue.


J. Object Hierarchical Chart


1. Main of Object Hierarchical Chart

The core value of this tool is the presentation of object hierarchy in Excel Spreadsheet. That is where a developer or an architect to design a healthy relational object images. Once an idea is formed, It is very convenient for the developer to write out the commands of 'OopClasses'. Most of the work involves CopyPaste on existing approved classes built before. Most classes represent same pattern with zero or few variations.

2. Hierarchy Detail

The hierarchical chart is a set of nodes on a tree structure. In our chart on the left is the base class node, right, the derived class. Each node contains 6 column fields. They are listed as following:
  1. Field 1: the base class ID number
  2. Field 2: its own class ID number
  3. Field 3: the class name
  4. Field 4: not used
  5. Field 5: tree branch level number. the most outer leaf number starts at 1001.
  6. Field 6: not used
So the multiple derived classes shares the same base ID number, plus they are on the right, and their left base class node cells are not repeating and hence empty. This presents an easy, forthcoming chart to recognize the class deriving relationships.

3. A Convenient Feature

The field 3 shows the cell as a hyperlink to the class file in the upgrade version. User clicks the link and it will open the file for view and edit.


K. The OOP Mindset


1. Main of The OOP Mindset

We believe this tool will help developers greatly. It fundamentally changes how developers code a project and store their legacy code. In conventional procedural programming, a developer most of time just drop the code and data into a source file at hand or nearby, in a set of limited, well categorized files best scenario. There is no planning or tool of planning, no object relational design, and no reentry images or blueprints upon which one can refreshs mind or an discuss can take place among colleagues. Also there is no easy way to desseminate a decree or common features versionwide, for example, an ID number for each classes. It is always the best practice to start thinking from top which is the object hierarchy to bottom which is the data and functional code. When object classes are separated by files, it is less possible to mistake typing at a wrong place, and the objects are well protected when files are not opened unnecessarily. This tool facilitated a mechanism for a developer to follow and discipline himself in his profession of software engineering.


L. Summary of Benefits


1. Main of Summary of Benefits

This comes to the end of the user manual document. Following is the list of benefits.
  1. The tool allows user to design Object Hierarchy in OOP Mindset easily.
  2. The tool provides a chart or a blueprint to allow user to refresh or review and discuss Object Hierarchy for oneself or among colleagues.
  3. The tool provides an input Excel Spreadsheet to make quick easy revisions on Object Hierarchy.
  4. The tool provides an universal separated object file format to fit into IDE safe and light.
  5. The tool provides a machanism to desseminate company decree versionwide or specific design components among objects related.
  6. The tool is safe in upgrade of version, creates no inpact of harm on previous verions. Rewinding to previous version is easy.
  7. The tool paves a way for a developer to adjust to the OOP mindset and discipline in write-out of object conponents.
  8. All in all, the object hierarchy is like the enterprise's estate where all buildings, factoris, warehouses are well planed and built, and ready for admin offices, task teams, and furnitures to move in.


M. Back up


1. Purpose

All files reside on the same disk drive. If the disk drive is no longer functioning, all financial data files are lost. The solution is to backup the files to another USB or network drive.

2. Backup a Must

Purchase a portable USB drive for backup purpose. Plug the drive to a USB port. Backup after you have made changes to the system, usually at the end of day. Once the backup is finished, then proceed to shut down the PC.

3. How to

In Eat Manager, go to page Backup, click the bottom buttons to back up either to a drive or to a directory.

4. Method

This backup command only backs up the files that have the file dates newer than the ones on destination drive, avoiding waste of time on copying unnecessarily the files that have the same contents as that of the destination ones.


N. History of Changes


1.

Date Description
09/17/2022Started to implement the project.
12/25/2022Finished the project.
01/20/2023Deploy as a separate project.
02/15/2023Finished testing.
03/04/2023Created User Manual.
03/07/2023Upgraded User Manual Creation program to include the integration of shared document sections.
03/09/2023Finished the Teknewell C# OOP Framework User Manual.
04/23/2023Added multiple base classes.
04/29/2023Added a sharable class hierarchical report file to the project directory. The report contains the relative HyperLinks to files for team share.
figure 8001