The Kinetic Framework

New Post: Dealing with Many-to-Many Relationships

RossCode — Mon, 01 Sep 2008 13:31:18 GMT

Jazza,

You are correct - we put nothing in specifically for Many-To-Many relationships at this point. If you set the two fields in your lookup table as the primary key for that table (or add another key), you can get to the many to many relationship through that table.

For example, if you have these three tables: Employees, Clients and a table managing which employees have talked to which clients (EmployeeClientContacts), from the Employee object, you can go employee.EmployeeClientContacts to get the list - then each one of those has a .Customer property that contains the customer.

It's not as seemless as a true many-to-many relationship, but it also allows you to manage any meta data in the link table, so that's what we stuck with for now.

New Post: Dealing with Many-to-Many Relationships

Jazza — Mon, 01 Sep 2008 09:28:58 GMT

Hi, how does the framework deal with many-to-many relationships? I am using the framework against a database where I have two tables, each with their own primary key, but joined by a lookup table which has no primary key of its own. In a previous discussion on this subject, you said that you hoped a solution would be in place for version 2.0, but I have version 3.0 and it does not appear to be fixed.

Source code checked in, #21198

markjjordan — Wed, 30 Jul 2008 13:37:51 GMT

Validation error was getting instantiated for nvarchar(max) property, comparing against -1 for the length of the field.

Source code checked in, #21185

markjjordan — Wed, 30 Jul 2008 12:32:08 GMT

Now handling varbinary(max) correctly when generating T-SQL in entity generated classes.

Source code checked in, #20700

RossCode — Thu, 24 Jul 2008 04:27:13 GMT

Add new templates

Source code checked in, #20699

RossCode — Thu, 24 Jul 2008 04:26:20 GMT

Added IDataHelper and IDataFactory interfaces. Updated SqlHelper class to implement IDataHelper interface. Added ServiceLocator to handle updated factory dependencies.

Source code checked in, #20126

RossCode — Thu, 17 Jul 2008 17:46:21 GMT

Update for naming change to Kinetic Framework.

Released: Kinetic Framework 3.0 (Apr 03, 2008)

Thu, 17 Jul 2008 02:09:09 GMT

Kinetic Framework 3.0 includes the following new features:

Validation Support: We added validation of properties to determine if fields are required and that strings are less than the max length. This is extendable through overrides and events, so you can add your own validations pretty easily.
Logging Support: This was one of those things we struggled with. We didn't want to add a dependency in the framework to a particular logging framework, so instead of adding logging support directly, we added the hooks so you could log what you wanted to log. Most of what we could come up with had to do with logging SQL queries, so we made the SqlHelper a partial class and added a base class, so you could add the logging by overriding OnExecuting and OnExecuted.
Database-based Paging and sorting: We've added a bunch of overloads to GetEntity() methods to allow you to page at the database level.

We also fixed a few bugs that were brought to our attention. Documentation is a bit lite right now, but we're working on it!

UPDATED RELEASE: Kinetic Framework 3.0 (Apr 03, 2008)

Thu, 17 Jul 2008 02:09:09 GMT

Kinetic Framework 3.0 includes the following new features:

Validation Support: We added validation of properties to determine if fields are required and that strings are less than the max length. This is extendable through overrides and events, so you can add your own validations pretty easily.
Logging Support: This was one of those things we struggled with. We didn't want to add a dependency in the framework to a particular logging framework, so instead of adding logging support directly, we added the hooks so you could log what you wanted to log. Most of what we could come up with had to do with logging SQL queries, so we made the SqlHelper a partial class and added a base class, so you could add the logging by overriding OnExecuting and OnExecuted.
Database-based Paging and sorting: We've added a bunch of overloads to GetEntity() methods to allow you to page at the database level.

We also fixed a few bugs that were brought to our attention. Documentation is a bit lite right now, but we're working on it!

Updated Wiki: RoadMap

RossCode — Thu, 17 Jul 2008 02:06:51 GMT

Kinetic Framework Road Map

Version 3.0

Add Validation Support
Add Logging Support
Add database based paging and sorting
timestamp field support
Add DeleteAll and SetAllDeleted() methods to EntityList
Enhance FindEntity() and FindEntities() to work more like EntityComparer does (support searching on multiple properties)
Fix naming conflicts with composite foreign keys
Add ability to refresh entity from database

Version 4.0

LINQ support
WCF support
Caching
Nullable type support
Deep loading of entities
Add Copy constructors
Add custom queries based on indexes in database

Updated Wiki: Upgrading

RossCode — Thu, 17 Jul 2008 02:03:40 GMT

Upgrading The Kinetic Framework

Upgrading from 1.x to 2.0
The Kinetic Framework version 1.0 was only released internally at NuSoft Solutions (now RCM Technologies), so this information is primarily pertinent to projects used within RCM Technologies.

Updated Wiki: WhatTheNuSoftFrameworkGivesYou

RossCode — Thu, 17 Jul 2008 02:01:34 GMT

What Is Generated By The Kinetic Framework?

You just generated your business framework. Great. Now you're ready to go!

But what exactly did you get?

In your root folder, you should have a solution file, named after your Namespace you used while generating. You'll also have another folder named after your DomainNamespace you used when generating. If you selected StoredProcedures for your SQLType, then you'll also have a Database folder.

In that Database folder, you'll find a database project, with the standard folders it starts with, but under the Create Scripts folder, you have a Stored Procedures folder, which has all of your scripts in it. They are all in separate files, and you'll need to run these against the database before you get too far.

In the other folder (Domain, Business, Core, or whatever you called it) is the core of the framework. The files in here are your business entities. Each one has a <entity>.cs file and a Generated.<entity>.cs file. When you open the project, the Generated.<entity>.cs file will be a sub-item of the <entity>.cs file, so it's there, but hidden.

In the Framework folder, you'll find the standard files for the Kinetic Framework:

1. EntityBase - every entity inherits from EntityBase. This provides a default set of methods and properties, default implementations for some methods, and a definition of a standard interface our entities will have. This is also responsible for loading and initializing entities from database readers.
2. EntityList - this provides us with a custom generic collection we can use for lists of our entities. It handles loading and saving of child collections for an entity.
3. EntityListReadOnly - this gives us a way to have a read-only collection that will not get saved when we update our entities.
4. DatabaseColumnAttribute - we use this attribute in our entities to flag a column as coming from the database. You can use this in your own custom objects to have them loaded automatically by the framework.
5. EntityEventArgs and EntityCancelEventArgs - our entities have a few events that you can handle, and we pass along custom event arguments. We typically have an "ing" and a "ed" event - Saving and Saved, Inserting and Inserted, etc. The "ing" event will use the EntityCancelEventArgs, which allows the handler to cancel the pending event. So by saying e.Cancel = true; in the Saving event, we can prevent a Save from happening.
6. SqlHelper - this is a fairly standard SQL Helper class that allows us to access SQL Server. It relies on a ConnectionString being in the ConnectionStrings section of your config file, and it should be called "ConnString" - yes, it's limited, and it's on our list of updates to make.
7. ISearchable and ISavable: Two interfaces that are used to specifiy that our list is searchable and that our entities are savable.
8. MinToEmptyTypeConverter: An attribute to make a friendly display of min values.

I'll go into more details on the framework files at another time. For now, that's good enough to get you going.

Back to the domain folder. The <entity>.cs file will be where you'll add your custom code. The Generated.<entity>.cs file is designed to be left alone, so it can be regenerated if you need to. This isn't a hard and fast rule, but be aware that the file will get overwritten if you regenerate.

The Generated.<entity>.cs file has most of the guts of your business entities in it. It has all of the properties for each database column. It has Properties for foreign key relationships - an Order will have a Customer property for the customer who owns the order. It will also have collections for entites that have foreign keys to it - an Order will have a collection of OrderDetails. There are static methods to create each object, as well as member methods to create objects - if you have an Order object called order, you can call order.CreateOrderDetail(); to get a new OrderDetail object that is related to the Order. It has a public Save() method that knows what children objects need to be saved - if you have a customer entity, change the name, add an order with two order lines, and call customer.Save() it will update the customer, insert the Order and insert all of the OrderDetail rows. There's more, which I'll cover later in more details.

Lastly, you'll get a project file that includes all of the above files.

Open the solution, build, and you're ready to add your UI to the solution!

Updated Wiki: SolutionItems

RossCode — Thu, 17 Jul 2008 01:59:41 GMT

Use Solution Items To Manage Kinetic Framework Code Changes

We recommend adding the zip file of the changeset or release you downloaded and used to generate your code framework to your Visual Studio project as a solution item. When you regenerate your framework you should use the stored solution item copy of the framework instead of downloading the latest change set of the framework.

Updated Wiki: ExtendingTheNuSoftFramework

RossCode — Thu, 17 Jul 2008 01:58:44 GMT

Extending The Kinetic Framework

Ok. So you've been using the Kinetic framework (or you haven't, but are thinking about it). One thing keeps nagging you, though.

What if I want to do something that's not in the framework by default?

Good question! The framework is built to be very flexible and allow you to do just that! If you're talking about extending Entities, there's two major ways:

1. Add functionality to an existing entity
2. Make a new entity based on an existing entity

Sticking with the Northwind database as a reference, let's say you want to change a few things when working with a Customer object. First, we'll look at adding functionality to an existing entity. A customer has orders, and an order has order lines, and order lines have products they are associated with. But a customer has no direct association with a product. What if we want to see a list of all products that a customer has purchased? Ideally, if we have a Customer entiity called customer, it would be nice to have that stored in a customer.Products property. But it's not there.

This is where adding functionality to an existing class comes in handy. We can add any functionality we want in the Customer.cs class file. We add the Product collection, and, following the pattern of lazy loading, we get this:

private EntityListReadOnly<Product> _products = null;
public EntityListReadOnly<Product> Products
{
   get
   {
      If(_products == null)
     {
        _products = Product.GetProductsByCustomer(this);
     }
     return _products;
   }
}

We don't have a setter because we can't directly change this collection - it's just a roll up of data available other ways in the system.

All set then, right? Well, not quite. We did the easy part. We have a collection, and we lazy load it. But where do we lazy load it from? The Product entity, but right now, it doesn't have a method for that. So, we need to add one:

public static EntityList<Product> GetProductsByCustomer(Customer customer)
{
  string commandText = "ProductGetByCustomer";
  List<SqlParameter> parameters = new List<SqlParameter>();
  parameters.add(new SqlParameter("@CustomerId", customer.CustomerId));
  return GetList<Product>(customer, commandText, parameters);
}

Obviously you need to create the stored procedure for getting products by customer, or if you decide to use dynamic SQL, then you can just write the SQL right here. In that version, it'd look something like this:

public static EntityList<Product> GetProductsByCustomer(Customer customer)
{
  string commandText = @"
  SELECT DISTINCTProducts.*
  FROM Products
  INNER JOIN OrderDetails 
  ON OrderDetails.ProductId = Products.ProductId
  INNER JOIN Orders 
  ON Orders.OrderId = OrderDetails.OrderId
  WHERE Orders.CustomerId = @CustomerId;";
 
  List<SqlParameter> parameters = new List<SqlParameter>();
  parameters.add(new SqlParameter("@CustomerId", customer.CustomerId));
  return GetList<Product>(commandText, parameters);
}

Now, when you call customer.Products, you'll get a collection of all products that the customer has ordered. That's it!

The second way to extent the framework is to inherit from an object. So let's do that. Let's create a summary customer object that shows how many orders each customer has. We could get that info another way - customer.Orders.Count, but that would require loading every order just to get the count - not efficient at all, especially if you want to display a list of customers.

So what can we do? We want the customer info, plus some more data, so we start with the customer entity as our base, and add a property for the number of orders

public class CustomerSummary : Customer
{
  protected CustomerSummary() { }
 
  private int _numberOfOrders;
  {"[DatabaseColumn()]"}
  public int NumberOfOrders
  {
    get { return _numberOfOrders; }
    protected set { _numberOfOrders = value; }
  }
}

Let's back up and explain a few things. We have a protected CustomerSummary constructor for two reasons: First, it follows the framework's pattern of using Factory methods to get and/or create entities. Second, a CustomerSummary object isn't what you'd be using to create a new customer - it's meant for displaying data. The DatabaseColumn() attribute is added to the NumberOfOrders property to tell the framework to expect this value to be retrieved when we run stored procedures or queries to get CustomerSummary objects. Now, like I said before, the CustomerSummary is read-only, so why do we have a setter for NumberOfOrders? Because that's the setter that the framework will use to populate the number of orders. We make it protected so only the framework can get access to it.

Next we need a method to get CustomerSummary objects:

public EntityList<CustomerSummary> GetCustomerSummaries()
{
  string commandText = "CustomerSummaryGet";
  list<SqlParameter> parameters = new List<SqlParameter>();
  return GetList<CustomerSummary>(commandText, parameters);
}

To better reflect what's happening, let's take a look at the Dynamic SQL version:

public EntityList<CustomerSummary> GetCustomerSummaries()
{
  string commandText = @"
  SELECT 
  Customers.*,
  COUNT(Orders.OrderID) AS 'NumberOfOrders'
  FROM Customers
  INNER JOIN Orders
  ON Customers.CustomerID = [Orders.[CustomerID]
  GROUP BY
  Customers.*
  ";
 
  list<SqlParameter> parameters = new List<SqlParameter>();
  return GetList<CustomerSummary>(commandText, parameters);
}

First, no, I'm not positive that the group by clause works - basically, it's a listing of all of the fields in the Customer table (starting with CustomerID, since it's unique) because having a count() in your query requires that you group by all of the other fields in the query.

Anyway, does that look familiar? It should. It's very similar to what we had to add to the Product class to get a list of products by customer - the query is different, but the rest of the calls are the same. The call to GetList() is slightly different because it specifies we're getting a list of CustomerSummary entities instead of Product entities, but that's it. The pattern for getting a list of objects is the same whether you are working in a framework generated object or you inherit from one.

Updated Wiki: AdvancedTopics

RossCode — Thu, 17 Jul 2008 01:53:30 GMT

Advanced Topics

Understanding these concepts will help you get the most out of the Kinetic Framework.

Key Concepts

Extending The Kinetic Framework
Using Solution Items To Manage Change
Changing Class Names That Are Generated
The Kinetic Framework and Active Generation
What Is Generated By The Kinetic Framework?

RCM Users
Upgrading From 1.x To 2.*

Updated Wiki: CodeExamples

RossCode — Thu, 17 Jul 2008 01:50:53 GMT

Step 3: Write Code

Now your framework is generated and you are ready to write your custom code. Add the a reference to your generated framework to your UI project. Then add a using statement to your namespace within your ASPX code behind and you are ready to go. Here is some sample code for working with an entity generated by the Kinetic Framework.. Let's say you generated some code from the Adventure Works sample database.

Get a collection contacts

EntityList<Contact> contacts = AdventureWorks.Business.Contact.GetContacts();

Get one contact

Contact contact = AdventureWorks.Business.Contact.GetContact(1);

Create a new contact

Contact contact = AdventureWorks.Business.Contact.CreateContact();
contact.FirstName = "my first";
contact.LastName = "user";
contact.Save();

Update a contact

Contact contact = AdventureWorks.Business.Contact.GetContact(1);
contact.FirstName = "my first";
contact.LastName = "user";
contact.Save();

Note: All saves are recursive so if you update or add child objects they will also be updated / added when you save the parent object.

Delete a contact

Contact contact = AdventureWorks.Business.Contact.GetContact(1);
contact.Delete();

Those are the basics. Review the advanced topics area to get more insights into how to get the most out of the Kinetic Framework.

Updated Wiki: ChangeClassNames

RossCode — Thu, 17 Jul 2008 01:49:52 GMT

How are class names deteremined in the Kinetic Framework?

We try to support databases that use plural names for tables as well as databases that use singular names for tables. Our default model is to create classes with singular names and collections of classes with plural names. We use the built-in string utilities in CodeSmith to convert from plural names to singular names and singular names to plural names. We understand this isn't perfect, and offer other a way to override class naming. There are two Extended Properties you can add to a table to affect how naming works:

NSFx_EntityName: This will be the class name for the entity.
NSFx_EntityPluralName: This will be used for any collections of this type of entity.

Learn more about SQL extended properties

Updated Wiki: ActiveGeneration

RossCode — Thu, 17 Jul 2008 01:47:24 GMT

Understanding Active Generation

The Kinetic Framework is meant to be a combination of passive and active code generation. Passive generation is a "one time" generation - a keystroke saver. Active generation means you can regenerate your code at any time. Certain files created by the framework are passive - one time generated files. Most of the "guts" of the generated code is actively generated - they are overwritten whenever you regenerate - and that's a good thing! Imagine the scenario below:

You've been working on your project for a couple of months, and think to yourself, "What if I added coupon codes to the order so customers could get a discount?" Your response: "Sure, I can do that!"

But what you're really thinking is: "Now I have to add a CouponId to the Orders table, and add a Coupons table to the database. Then what am I going to do about my generated code? I've put modifications all over the place, and I don't want to lose them!"

One solution is to regenerate in another folder and merge your changes by hand. But that's error prone, and relies on you remembering all objects that might be touched by your change.

With the Kinetic Framework and the passive/active generation combo, there's another option. Regenerate over the top of what you already have. The framework is designed to respect your changes and ensure you don't lose changes you've made. Some files will get overwritten, but if you follow a few guidelines about where you make modifications, then you should be OK. Before the guidelines, though, here's what gets overwritten when you regenerate:

Any generated.<entity>.cs files: These are generated files, and aren't meant to be modified, so the framework will regenerate these every time. In the change above, this is what would add the CouponId property to your Order object, as well as give you a reference to the Coupon object. The .cs file will not be overwritten if it exists, but if it does not exist, then it will be created. So, in the above example, a Coupon.cs and Generated.Coupon.cs file will be generated.
Framework/.: All files created by the Kinetic Framework and placed in the Framework folder will be overwritten. It's all generic code in there, so it gets overwritten whenever you generate.
Stored Procedures: If you're using stored procedures for your data access, then all of the stored procedures will be overwritten. You'll still have to run them against your database, but the files will be updated. This is important since all of the Order stored procedures would be out of date if you added the CouponId field.

Now, here's what isn't listed here: any solution or project files and your custom entity classes. Those don't get overwritten, so if you add a new entity, such as Coupon, you'll have to include that class in your projects manually - both the .cs file and .generated.cs file. Same thing with the stored procedures - they don’t get automatically included in the database project file. And if you add any custom code to your .cs files, that's also preserved.

End result: you can safely regenerate your entities without fear of losing code if you follow a few guidelines: Don't modify files in the Framework folder and add your custom code to the .cs entity file, leaving the generated.<entity>.cs entity files alone.

Updated Wiki: GettingStarted

RossCode — Thu, 17 Jul 2008 01:45:57 GMT

Kinetic Framework Documentation

Step 1: Generate The Framework

There are two major requirements before you can start using the Kinetic Framework. First, you need Codesmith 4.1 or later. It does not require the full version of CodeSmith Professional - you can generate with the $99 basic version. It also requires that your database be completed. We assume you start from a database model and work your way up, and that's exactly how this framework is intended to be used. Once your database is in place, you can start generating code.

When you get the templates, you'll find a Main.cst file in the root. That's the file you want to use for your initial generation. When you open it, you'll see a few properties that you need to set:

SourceDatabase - this is the database you want to generate against. You'll probably have to create a new connection to the database, which basically involves building a connection string and giving it a name. We use certain features that require SQL Server 2005, however, it will work with SQL Server Express.
ExcludedTables - here you can exclude tables from having classes generated for them. If you have ASP.NET membership tables, you'll want to exclude those.
TablePrefixes - this is a comma delimited list of prefixes to strip off tables for class names. For example, if all of your tables start with tbl, then the entity generated from tblOrders will be Order.
Namespace - This is the root namespace for the whole application. We typically use <CompanyName>.<ProductName>.
DomainNamespace - This is the namespace to add to the root namespace for your Domain / Business objects. We default to Business, but we've also used Domain and Core in the past. The resulting namespace for your business objects will be <Namespace>.<DomainNamespace>.
SQLType - We support both Stored Procedures and Dynamic SQL. You can choose either one. If you choose Stored Procedures, we'll generate a database project with all of the stored procedures used by the default framework implementation.
OutputDirectory - The most important one! This is where you'll get your code when it's done.

Once you have that done, just click Generate, sit back, and relax. In a few seconds, your framework will be ready to go. A key concept to understand is that you can regenerate code as many times as you want. Read about Active Generation in order to get the most productivity out of this framework.

Step 2: Fix Any Code Generation Issues

Step 3: Write Code (including code samples)

Advanced Topics

Updated Wiki: WhyTheNuSoftFramework

RossCode — Thu, 17 Jul 2008 01:39:01 GMT

Why The Kinetic Framework?

Before the Kinetic Framework, just about every custom development project we got at RCM Technologies started with the tech lead developing some sort of framework that other team members can leverage when building the user interface. Getting that framework in place usually takes a while, and not much else can be done until at least a good chunk of it is in place. Not only that, but the framework is usually fairly routine once you make a few key decisions. It's the same type of code over and over again, which makes writing it by hand error-prone. Also, making the decisions about how to handle certain aspects takes time and usually has consequences that aren't always obvious when the decision is made.

The end result is that projects usually take a week or two to get off the ground before other developers can really jump in and get going. It's this time that the Kinetic Framework is intended to help with. It also helps you by making a few of those key decisions. Why is that a good thing? Because the decisions are based on past project experience and frameworks that Kinetic IG at RCM Technologies has used in the past. It's a best of breed among a few different frameworks, extracted out to be quick and easy to start using.

It's definitely not the only solution out there. If you've looked at .NetTiers (another CodeSmith template-based code generator framework) or some of the software factories being generated by Microsoft, you'll notice they all do pretty much the same type of thing.! While I think the Kinetic Framework is one of the best options, the point is, use something. In most cases, it's better than starting from scratch. I personally think both of the other solutions I listed are great and give you a lot of foundation - almost too much for smaller projects. And I think that the smaller niche is where the Kinetic Framework can fit in nicely.

If you do decide to use it, don't feel that it has to be used "as is". It's meant to be a set of templates that you can use to get a jumpstart on your project. If you don't like how something is implemented, you've got the full source so you can change it! Want a new feature in it for something you're doing? Add it! Want to remove something? Go for it.

If you do modify the templates or find an issue, we'd like to know about not only the change, but also why you made the change. If it's a bug, we want to fix it. But more importantly, if it's a new feature, we want to see how we can incorporate that into future releases of the Kinetic Framework, so everyone can benefit from your experiences!

The Kinetic Framework is being actively used at RCM Technologies, so we fully expect it to progress. We have a list of features we want to add, but we are definitely open to ideas from the community.