From the very beginning, we have always tried to provide ample documentation for EntitySpaces. Since all of the team members are developers, we can certainly empathize with using a product that lacks in this area. As the product grew, and more documents were added, it became harder and harder to centralize all of the various resources for easy searching. We, previously, had documentation on our main site, in our forums, and in blog posts.

Today, we are proud to announce the new EntitySpaces Developer Documentation Site. This site will house all EntitySpaces documentation in an effort to provide one centralized, searchable location. We have started consolidating all of our existing documentation there. If you find any content that is out of date, missing, or needs expansion, please create a post in our Developer Documentation forum and we will get the site updated.

We hope you find this new resource useful. As always, any feedback is greatly appreciated.

- The EntitySpaces Team

This post is a continuation of  EntitySpaces 2009 - Running under Visual Studio (Part 1)

Special Note: If you are investigating EntitySpaces this article gets a little technical. However, you will not have to write user controls or do anything other than browse to a template within Visual Studio and execute the desired template. This article is for some of our more advanced EntitySpaces users. Not only are we making EntitySpaces very easy to use but also very easy to extend. Everything you see in this blog post is running under Visual Studio.

The Template Header

In this post we'll take a look at both the Template Browser and the template user interface mechanism. The Template Browser lists the templates in a tree based on each template's Namespace located in the template header (shown left). You can see from the TemplateInfo tag in the template header that there is both a Namespace and a UniqueID attribute. The UniqueID will be discussed later when we dig into the user interface. Now, however, let's take a look at the Template Browser. The Template Browser is shown below (while running under Visual Studio). 

The Template Browser

You can select any template and click the green arrow to execute a template which will display the template's user interface, if any.

The Template User Interface

Look at the image below to get an idea of what happens when we click on the green arrow to execute the template. Notice the tabs on the image above are gone. Also notice in the open solution in our EntitySpaces.TemplateUI project there are three user controls. Basic, Advanced, and ProxyStub. These correspond to the three tabs you see on the screen below. We (and you) can write your user interface in pure Windows.Forms user controls and have full IntelliSense. You also have direct binding capabilities to our metadata. Now only that, but you can extend our templates with your own user interface by adding an additional tab. Again, this is only for necessary for those that want to extend EntitySpaces.

What you are looking at above is the template user interface which slides over and across the normal tabs. The template user interface is shown until you press Ok to execute the template or Cancel it. Once the template is executed the normal tabs such as Projects, Templates, and so on become visible again. It's pretty cool to see it in action. When the user presses Ok you simply stuff the users UI choices into the esMeta object's (metadata object) input Hashtable during the OnExecute method. So, how can you extend the user interface without modifying our templates and not be worried about a new release wiping out your changes? Easy. Let's look at how the UI works at a low level.

A Template User Interface Tab

Below is all that is necessary to add a tab to our existing templates, or add them for your own custom template. Notice we implement the ITemplateUI class. This means we need to implement the Init, OnExecute, and OnCancel methods. In the Init method, you tie your user control to a template via the TempalteInfo.TempalteId property, making sure to match it to the template's UniqueID in the template header (shown at the beginning of this post).

The above image is the code for the "Basic" tab that you see on the template user interface above. This is housed in it's own assembly and stored in a particular folder that the plug-in scans. Take a look at the Init() method which returns an esTemplateInfo object. Here we are indicating that when the template with the UniqueID of "2216AB4F-BDB4-47de-8412-8560C1F2F420" is executed we want this user control on a tab called "Basic Information". If you look at the OnExecute() method this is where we will store the users choices. (Later we will access them in our custom template). Recall that in ES2009 you will be able to add templates into our template stack to extend and customize EntitySpaces. The good thing is our templates will use use the same mechanism for our user interface. So, all three the tabs you see in the template user interface above are represented by an individual user control. The second parameter to Init() above is really the DTE2 ApplicationObject which will allow your user interface to have full access the visual studio solution just like our plug-in does. We pass it in as type "object" so that you are not forced to bind with the Visual Studio Plug-in assemblies unless you really want to.

Binding to the Metadata in your User Control

Notice how use the esMeta object passed into our ITemplateUI.Init() method to populate our user interface controls. Since this is all just normal Windows.Forms programming you can bind directly to our metadata collections and it could not be any easier.

We hope you like what you are seeing.

From mobile devices to large scale enterprise solutions in need of serious transaction support, EntitySpaces can meet your needs. Whether you’re writing an ASP.NET application with medium trust requirements, a Mono application, or a Windows.Forms application, the EntitySpaces architecture is there for you. EntitySpaces is provider independent, which means that you can run the same binary code against any of the supported databases. EntitySpaces is available in both C# and VB.NET. EntitySpaces uses no reflection, no XML files, and sports a tiny foot print of less than 200k. Pound for pound, EntitySpaces is one tough, dependable .NET architecture.

The EntitySpaces Team
--

EntitySpaces LLC
Persistence Layer and Business Objects for Microsoft .NET
http://www.entityspaces.net

EntitySpaces 2009 (see roadmap) will plug right into Visual Studio and it will use its own internal code generator. This means that Visual Studio users will never have to leave Visual Studio to work on or generate their EntitySpaces architecture. The image below shows how EntitySpaces 2009 looks embedded within Visual Studio. While it is likely to change a little before our first beta this should provide you with a feel for ES2009. The nice thing is that ES2009 is a dockable window just like any other window within Visual Studio, you can even generate your EntitySpaces classes directly into your solution and the folders/files will be created automatically for you. We are also making our VistaDB and SQL CE providers version independent so you will no longer have to deal version issues during code generation.

The EntitySpaces 2009 Tabs

• Projects Tab - Projects allow you to record templates so that you can play them back at any time. Thus, you can regenerate with all of the settings you used when you recorded the session originally.
• Templates Tab - The template browser lists all of the templates available to you, you can launch them from this tab.
• Metadata Tab - The metadata tab allows you to examine all of the database metadata that EntitySpaces provides to your templates during code generation. Also the user meta data can be edited through this tab which allows you to alias columns, indicate Oracle sequences, and other things.
• Settings Tab - The settings tab is where you add connections to various databases, indicate paths such as where your user meta data is located, the location of your output folder, and all kinds of EntitySpaces configuration settings.
• Mappings Tab - This tab lists the mappings between database column types to .NET types.

If you are not a Visual Studio user no need to worry. We will provide a stand alone windows forms application that will look and work almost exactly the same (see below).

The image above is the same binary code that runs under Visual Studio. We are developing both the Visual Studio compatible version and the Stand Alone version at the same time. Expect another blog post by the end of October which provide you with more insight into ES2009 including many more screen shots. Our goal is to have our first beta out by the end of 2008.

From mobile devices to large scale enterprise solutions in need of serious transaction support, EntitySpaces can meet your needs. Whether you’re writing an ASP.NET application with medium trust requirements, a Mono application, or a Windows.Forms application, the EntitySpaces architecture is there for you. EntitySpaces is provider independent, which means that you can run the same binary code against any of the supported databases. EntitySpaces is available in both C# and VB.NET. EntitySpaces uses no reflection, no XML files, and sports a tiny foot print of less than 200k. Pound for pound, EntitySpaces is one tough, dependable .NET architecture.

The EntitySpaces Team
--

EntitySpaces LLC
Persistence Layer and Business Objects for Microsoft .NET
http://www.entityspaces.net

This should be our final ES2008 Release as we expect to have an ES2009 beta out by the end of the year. Here are the changes.

1) The byte[] properties (for image and binary data types) were not being marked as dirty when set and thus weren't being saved.

2) esEntity.MarkAsDeleted() now throws an exception if you call it and there is no data.

From mobile devices to large scale enterprise solutions in need of serious transaction support, EntitySpaces can meet your needs. Whether you’re writing an ASP.NET application with medium trust requirements, a Mono application, or a Windows.Forms application, the EntitySpaces architecture is there for you. EntitySpaces is provider independent, which means that you can run the same binary code against any of the supported databases. EntitySpaces is available in both C# and VB.NET. EntitySpaces uses no reflection, no XML files, and sports a tiny foot print of less than 200k. Pound for pound, EntitySpaces is one tough, dependable .NET architecture.

The EntitySpaces Team
--

EntitySpaces LLC
Persistence Layer and Business Objects for Microsoft .NET
http://www.entityspaces.net

There were a few bugs found in our 0915 release and we felt the need to put out a new release to address them. We recommend that everyone on the 0915 release upgrade to our 0922 release. If you regenerated your classes on the 0915 release there is no need to regenerate your classes again on the 0922 release. We will post a 0922 Trial version very soon. You will know when the new Trial version is available by looking under the download button on our home page.

Here are the issues that were addressed.

1. There was a bug when binding to a grid and adding a new row through the grid interface, this has been fixed.
2. There was a bug in certain complex hierarchical save scenarios, this has also been fixed.
   

We have a slew of improvements and requests that we are  going to pour into ES2009. We have already converted our entire suite of C# templates to run under our new code generator so things are moving forward very nicely on ES2009.

From mobile devices to large scale enterprise solutions in need of serious transaction support, EntitySpaces can meet your needs. Whether you’re writing an ASP.NET application with medium trust requirements, a Mono application, or a Windows.Forms application, the EntitySpaces architecture is there for you. EntitySpaces is provider independent, which means that you can run the same binary code against any of the supported databases. EntitySpaces is available in both C# and VB.NET. EntitySpaces uses no reflection, no XML files, and sports a tiny foot print of less than 200k. Pound for pound, EntitySpaces is one tough, dependable .NET architecture.

The EntitySpaces Team
--

EntitySpaces LLC
Persistence Layer and Business Objects for Microsoft .NET
http://www.entityspaces.net

EntitySpaces has teamed up with Justin Greenwood (shown left) of MyGeneration Software to create a brand new code generation engine for EntitySpaces 2009. Because of Justin's code generation expertise we contacted Justin and asked him to create a very simple, lightweight code generation engine whose only job is to execute templates. (There is no user interface support by design.) The code generation engine makes the EntitySpaces MetdataEngine available as an intrinsic object available to all templates through the "esMeta" property. We already have a working version of the code generation engine and thought we would share our progress with you.

We have created a test form that invokes the code generation engine for testing. Here is the button click event that kicks the whole thing off.

using EntitySpaces.MetadataEngine;
using EntitySpaces.CodeGenerator;

namespace Test
{
    public partial class Form1 : Form
    {
        private void btnGenerate_Click(object sender, EventArgs e)
        {
            EntitySpaces.MetadataEngine.Root esMeta = new EntitySpaces.MetadataEngine.Root();
            esMeta.Connect("SQL", this.txtConnectionString.Text); // I'm Connection to Northwind
            esMeta.LanguageMappingFileName = @"esLanguages.xml";
            esMeta.UserMetaDataFileName = @"esUserData.xml";
            esMeta.esPlugInSettingsFileName = @"esSettings.xml";
            esMeta.Language = "C#";

            Template template = new Template();
            template.Execute(esMeta, "Master.est");
        }
    }
}

Master Template

Here is what the "Master.est" template looks like. In the code above the connection string was set to the Microsoft SQL Northwind database and we have hard-coded the "Employees" table in the master template shown below.

Sub Template

Notice in the code above we execute a sub template named "Sub.est" and append it's output to our currently running template. We also show how you can have separate "pure code blocks" via the <script> tag. Below is the Sub.est template which is passed the "esMeta" object from the Master template and then runs through all of the columns in the Orders table.

The Output

The output from the execution of the master template looks like this:

    EmployeeID
    LastName
    FirstName
    Title
    TitleOfCourtesy
    BirthDate
    HireDate
    Address
    City
    Region
    PostalCode
    Country
    HomePhone
    Extension
    Photo
    Notes
    ReportsTo
    PhotoPath

<START|-|Wow, very cool|-|END>

--> Sub.est

    OrderID
    CustomerID
    EmployeeID
    OrderDate
    RequiredDate
    ShippedDate
    ShipVia
    Freight
    ShipName
    ShipAddress
    ShipCity
    ShipRegion
    ShipPostalCode
    ShipCountry

Summary

At this point we have everything in place to provide a Beta version of EntitySpaces 2009 in a very short time frame. By having this all in house our code generation will be extremely easy for EntitySpaces 2009 and will not rely on third party tools. This also allows for our new code snippet model where a template is nothing more than a collection of code snippets which can be tweaked and replaced by our customers.

Take a look at this mock master template.

All the master does is execute a set of sub templates that make up, for example, the single esEntity object. Now imagine a very cool UI that allows you to manage, edit, and customize these snippets and replace or tweak our properties, INotify support, or just add other methods and properties to your entities. And the best thing is you will not need to be a code generation expert, not by a long shot. We are very excited about EntitySpaces 2009. This is only a part of what is coming in 2009. Domain modeling and much more are on tap.

For more on EntitySpaces 2009 take a look at our roadmap HERE.

From mobile devices to large scale enterprise solutions in need of serious transaction support, EntitySpaces can meet your needs. Whether you’re writing an ASP.NET application with medium trust requirements, a Mono application, or a Windows.Forms application, the EntitySpaces architecture is there for you. EntitySpaces is provider independent, which means that you can run the same binary code against any of the supported databases. EntitySpaces is available in both C# and VB.NET. EntitySpaces uses no reflection, no XML files, and sports a tiny foot print of less than 200k. Pound for pound, EntitySpaces is one tough, dependable .NET architecture.

The EntitySpaces Team
--

EntitySpaces LLC
Persistence Layer and Business Objects for Microsoft .NET
http://www.entityspaces.net

We are pleased to announce that the official EntitySpaces 2008 0915 release is now available for download. This will be the final EntitySpaces 2008 release. Work is already underway on EntitySpaces 2009 and we will make a blog post filling you in on the some of details very shortly.

New Features, Fixes, Enhancements

1. Major Performance Improvements which all users will realize. See this blog post.
2. The VistaDB provider now supports NEWID() and GUID() on inserts.
3. IsDirty logic improvements (see below).
   

   Employees emp = new Employees();
   if (emp.LoadByPrimaryKey(1))
   {
       // At this point LastName = "'Smith"

       emp.LastName = "Crazy"; // emp.es.IsDirty = true
       emp.LastName = "Smith"; // emp.es.IsDirty = false
   }
   

4. Added ExecuteReader and ExecuteScalar to the esDynamicQuery class. See this blog post. This can be very useful for retrieving large results sets for display purposes.
5. Fixed the exception handling in FillDataTable and FillDataSet.
6. Add Oracle FLOAT support.
7. Added GetConnectionName() to allow classes to be configured to use a predefined connection string. See this blog post.
8. Fixed the AcceptChanges/RejectChanges logic such that it always clears the ModifiedColumns.

We will be publishing a new Trial Version later on this evening for the 0915 release.

From mobile devices to large scale enterprise solutions in need of serious transaction support, EntitySpaces can meet your needs. Whether you’re writing an ASP.NET application with medium trust requirements, a Mono application, or a Windows.Forms application, the EntitySpaces architecture is there for you. EntitySpaces is provider independent, which means that you can run the same binary code against any of the supported databases. EntitySpaces is available in both C# and VB.NET. EntitySpaces uses no reflection, no XML files, and sports a tiny foot print of less than 200k. Pound for pound, EntitySpaces is one tough, dependable .NET architecture.

The EntitySpaces Team
--

EntitySpaces LLC
Persistence Layer and Business Objects for Microsoft .NET
http://www.entityspaces.net

We have pushed up what we hope is our final beta for our 2008.1.0912.0 maintenance release. We need you to help us test. If you are able to upgrade your ES2008 application to our final beta, we ask you to do so. We plan on publishing the RTM late Sunday night. You will need to regenerate your classes. There is no trial version of this beta release available. Please report in your findings in our forums, positive or negative.

Thank you

- The EntitySpaces Team

From mobile devices to large scale enterprise solutions in need of serious transaction support, EntitySpaces can meet your needs. Whether you’re writing an ASP.NET application with medium trust requirements, a Mono application, or a Windows.Forms application, the EntitySpaces architecture is there for you. EntitySpaces is provider independent, which means that you can run the same binary code against any of the supported databases. EntitySpaces is available in both C# and VB.NET. EntitySpaces uses no reflection, no XML files, and sports a tiny foot print of less than 200k. Pound for pound, EntitySpaces is one tough, dependable .NET architecture.

The EntitySpaces Team
--

EntitySpaces LLC
Persistence Layer and Business Objects for Microsoft .NET
http://www.entityspaces.net