The Topobase Insiders

Logging Events

Two years ago I wrote about the event log of Topobase. We introduced this new feature with Topobase 2008. For every Topobase crash which happens we add an entry in the log file: /log/ApplicationLog.xml. You find further details in the original blog post.

But the log is not only for crashes, we can also use it to log warnings, information messages or debug information. If you need to trace down a problem on customer side the answer could be in this file.

I'll try to explain how you can also log your events into the log file. Because like every other built-in Topobase functionality you can also access this one from your own plug-in!

First of all you have to add the log4net.dll as a reference to the solution. You find this assembly in the bin directory of the Topobase Client or Administrator. After you have done that you can get the log instance from the LogManager:

  using log4net;

  ILog log = LogManager.GetLogger(GetType());

The log instance now provides different logging methods. You can either log fatal events, errors, warnings, information events or debug events. Here is an example how to log an information message (with the formatting option applied):

  log.InfoFormat("Date of today is: {0}", DateTime.Now);

That's it!

You should be aware that the user defines what should be logged and what not. Depending on the log level this message will now be written into the log file. In this case (an INFO event) the user has to set the log level as high as either ALL, DEBUG or INFO. If the log level is set to ERROR for instance, this message is not written to the log file. That's why you can (and should because of performance) check if the event will be written at all:

  if (log.IsInfoEnabled)
  { 
    log.InfoFormat("Date of today is: {0}", DateTime.Now);
  }

If you need more information about the log4net API you find it in the log4net SDK reference: http://logging.apache.org/log4net/release/sdk/index.html

Working with progress bars

This is the third post regarding the Feature History Administrator plug-in. In the previous two posts you could learn how to create a new DocumentAdminPage from scratch and then how to extend it with some logic. And as I have already mentioned, I was not happy how it has been implemented :-)

One important thing for a good user experience is when a process takes more than a few seconds the application has to inform the user about the progress. See also here for some background information about that. Showing the progress of a function has several benefits:

• the user sees that the software is still working (!),
• it shows where the process roughly is and
• it can also give a hint when the process will be finished.

So let's add a progress form to the Analyze() method. The class we can use is the StatusForm and it is located in the Topobase.Data.Util namespace. (There is also a ConsoleStatusDisplay which can be used when you have is a console application). The StatusForm can either act as an infinite progress bar, if you have no idea how long the process takes, or a 0% to 100% progress bar.

The StatusForm consumes a background job, so let's first create one:

 BackgroundJob<IList<FeatureClass>> job =
       controller.Analyze;
 StatusForm<IList<FeatureClass>> form = 
       new StatusForm<IList<FeatureClass>>(job);

The Analyze() method has to look like this: the first parameter is the StatusDisplay (to update the progress bar) followed by list of objects:

 public void Analyze(IStatusDisplay statusDisplay, 
       params IList<FeatureClass>[] parameters)

The StatusForm and its background job can be cancelable. In our plug-in we would like to let the user be able to cancel the process, so let's set the right property:

 form.CancelButtonEnabled = true;

We have to let the background job know which feature classes it has to analyze. Since it can't access the other properties from this class (cross-thread) we have to pass such information to the background job. Therefore we need to define it accordingly when we instantiate the StatusForm. In our example we need a list of Feature classes (StatusForm<IList<FeatureClass>>).

 // pass the list of selected feature classes
 // to the background job.
 form.SetParameters(this.SelectedFeatureClasses);

 // show the progress form,
 // this method starts the background job
 form.ShowDialog(this);

After calling the ShowDialog method the background job is started in a new thread. The GUI thread is now paused until the background job has finished.

If you take a look at the updated sample you will notice that I moved the Analyze() method to a new class called Controller. This is not necessary for the StatusForm, but I thought it would make sense to extract the logic from the UI and also improve the overall readability. Like the previous DocumentAdminPage samples this one is also written in C# and compatible with the official Topobase 2010 version.

Download project (16.1K)

Feel free to contact me for any questions or comments about this sample.

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Street View

As a small demonstration of Topobase integration with external programs, we'll show a workflow plugin that uses Google Street View. This is the feature of Google Maps that lets you view the streetscape of roads that have been captured by cameras mounted on Google Street View cars.

The plugin allows the user to select a feature and see the street-level panoramic photo from the closest point that was 'driven' by the Google cars, if any. Not all cities are covered and not all roads will have Street View photos, but if the area you are interested in is covered, this ability could be a compelling sales tool or interesting demonstration.

The sequence of steps followed by the plugin is first to get a feature from the user, either from the PickFirst set or by asking the user directly. The coordinates of the feature (or first vertex of the feature) are then transformed to the WGS 84 lat/long system that Google Maps uses. The latitude and longitude are formed into a URL query for Google Maps that requests information about the nearest panoramic point like so:

"http://maps.google.com/cbk?output=xml&ll=" + lat + "," + lon

The XML result is parsed to extract the pertinent information (there is other interesting information we ignore). If no panoramic point is nearby, the fallback operation is to just show a plain Google Map.

Once the panoramic point is found, a much longer URL is created to query Google Maps and get a Street View. The format of this URL is described in detail at the Mapki Wiki, and includes such information as the panoramic point id, the latitude and longitude of both the pano point and the observer location, plus camera pitch and yaw - which unfortunately no longer work since Google Maps now uses a Flash player which doesn't support these parameters.

This URL is then provided to a browser embedded in a dockable AutoCAD palette, and this is then made visible in AutoCAD. Of course you could fetch the URL in an external browser as well. The operation is demonstrated in this movie:

This demo is available as a ZIP file which you can download using the link below. You will need accurately georeferenced data which is covered by Google Street View. To build this project, define the environment variable TopobaseClientDirectory to point to the Topobase Client directory and execute the solution file:

C:>set TopobaseClientDirectory=C:\Program Files\Autodesk Topobase Client 2010
C:>StreetView.sln

Build the solution. Next create a workflow called StreetView in Topobase Administrator containing the script:

Sub Run
  Me.RunMethod("StreetView.dll", "StreetView.StreetViewWorkflow", "Navigate")
End Sub

Run Topobase client and either execute StreetView from the Workflow explorer or execute it using TBEXECUTE. Select your feature and you should see the browser pane displayed.

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Download StreetView

The age of your features

Some weeks ago I showed you how to develop a DocumentAdminPage. This time I would like to take the same example and extend it a little bit.

The new plug-in does a pretty simple job. It goes through the TB_UFID table and analyzes when a feature has been modified the last time. The result of this analysis will be shown in the list view at the bottom. The plug-in also lets you decide if you want to analyze all or just some of the feature classes in the document.

Compared to the first version of the sample I have added a list of feature classes, an "Analyze" button and a list containing the results in the UI.

  

The main logic is implemented in the Analyze() method (called from btnAnalyze_Click()).

 /// <summary>
 /// Analyzes the TB_UFID table for the selected feature classes.
 /// </summary>
 /// <returns>The number of features grouped by <see cref="Age"/>. </returns>
 private HashMap<Age, int> Analyze(IEnumerable<FeatureClass> featureClasses)
 {
  // create the result hashmap
  HashMap<Age, int> results = new HashMap<Age, int>();
  ...
 }

The method itself is pretty simple. It executes the following SQL statement:

  select touch_ts from TB_UFID where f_class_id = {0}

for each feature class and then it categorizes the features by age (older than...).

You have now two choices, try to develop it by yourself (~200 lines of code) or download the project file from here: 

Topobase.Insiders.FeatureHistory.zip (10.9K)

Of course this sample plug-in is not yet finished! Still a lot of important stuff is missing. For instance the Analyze method is working in the GUI thread which prevents the user from interacting with the Administrator. There is also no progress of the Analyze method visible to the user. The user just has to wait until the method finished. We'll see if we can fix that for the next week :-)

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Extending the 1-Click Maintenance

Some days ago I published the 1-Click Maintenance plug-in here. I promised that I will also provide the source code. Here we go: Download source code (171.2K)

 

If you are not a programmer you can stop reading. For all the others, you're welcome to take a look at the C# project and maybe even extend it...? Extending the plug-in is not that hard. And I know you already have some new database checks in your mind which you want to see in action.

So here is what you have to do in order to implement and run your own checks. Open the project in Visual Studio 2008 and locate the class SampleCheck:

class SampleCheck : DatabaseCheck, IFixable

The sample check gives you an idea what is necessary for a new database check. Just copy and paste this class or extend it. First you have to define the title and the description of the new database check. Then you have to implement the Analyze method, that's where the real logic is located:

public override void Analyze(IStatusDisplay statusDisplay)

Within the Analyze you probably find some issues, just add them to the Results list. If you need to show a message to the user don't show a message box, instead use the Messages property. One reason for that is that we don't want to interrupt the process and it also has to run in batch mode.

If your check can also fix the found issues you can implement the IFixable interface for your class. This should add a new method called Fix:

public void Fix(IStatusDisplay statusDisplay)

Within the Fix method make sure you iterate through the Results and fix one after the other. Keep in mind that the user might disable some results, so check the Active property of the result (result.Active). Also in this method you can log messages and errors in the Messages property.

After you have finished implementing your database check class you have to add it to the Controller. Locate the Controller.InitializeChecks() method and add a new instance of your class there.

That's it. If you need more detailed information take a look at the other database checks.

In order to compile and run the plug-in you have to set the correct reference path for the Topobase related assemblies (go to Project - Properties - Reference Paths) and the correct build path (Project - Properties - Build - Ouput path). 

Finally select the Topobase 2010 Administrator executable to start and debug the plug-in (Project - Properties - Debug - Start external program).

You are welcome to send me any feedback (or new database checks :-)

Thanks!

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

How to develop a new Topobase Administrator page

Since a few releases it's possible to not only extend the Topobase Client and Web applications with own plug-ins. Developers can now also extend the Topobase Administrator with new functionality. The easiest way to do that is to create a new DocumentAdminPage or an ApplicationAdminPage. The only difference between them is wether they relate to one document or not. All the AdminPages are listed in the tree on the left side of the Topobase Administrator. Of course , the DocumentAdminPages are not loaded and displayed until the user opens a workspace with at least one document.

I'll show you a step by step guide how to develop such a DocumentAdminPage.

After you have setup a new solution and project you can add a new class inherited from DocumentAdminPage:

 public partial class MyAdminPage : DocumentAdminPage

The DocumentAdminPage is in the namespace Topobase.Forms.Desktop:

 using Topobase.Forms.Desktop;

Within the constructor you have to set the name of your DocumentAdminPage:

 this.Text = "myAdminPage";

Please note that within the constructor you don't have access to the Document or the Connection instance.

If you would like to access an open Topobase connection you have to catch the event ActivatedFirstTime. Therefore open your DocumentAdminPage in the designer, in the properties window of the MyAdminPage switch to the Events and double click the ActivatedFirstTime event. Visual Studio now generates a new method where you can implement your initialization logic.

 private void MyAdminPage_ActivatedFirstTime(object sender, EventArgs e)
 {
 }

Like for every other plug-in you also need a TBP file to let Topobase know that there is a new plug-in available. Within the new TBP file add the following node:

  <DocumentAdminPage ClassName="MyAdminPage" />

That's it. You should now be able to compile the DLL and copy it together with the TBP to the Topobase Administrator bin directory and test it. If that doesn't work try to download the following sample project. I have developed it in C# against the released version of Topobase 2010 (7.00.41).

Download MyAdminPage.zip (7.2K)

I plan to provide more How-To posts in the next couple of weeks to show you step by step how to develop a nice AdminPage.

Suppress the graphic regenerations

Here is another performance trick for the Topobase developers.

Let’s imagine the following use case: you have some code which modifies several features, one after the other. No matter if you insert or update them. When you execute this code within Topobase Client, you will recognize that the map is automatically regenerated. This is very handy, because you don’t have to care about the graphic refresh, Topobase does that for you.

The only problem might be that the graphic regenerates itself too often, namely after each modification of a feature.

The question is, how can we suppress the regeneration for a certain time?

It’s straight forward and easy to implement, you only need one line of code.

The following example will lead into several regenerates in the graphic:

 

foreach (Feature feature in featureList)

{

feature.Attributes[dateCreated].Value = DateTime.Now;

fc.UpdateFeature(ref feature);

}

 

The following, improved example suppresses the regeneration until all the features have been updated:

 

using (MapDrawBurst mapBurst = this.Document.Map.InitiateDrawBurst())

{

      // the operations inside this using-block won't result

// in regenerating the map.

foreach (Feature feature in featureList)

{

feature.Attributes[dateCreated].Value = DateTime.Now;

fc.UpdateFeature(ref feature);

}

} // the map will be regenerated here (in the Dispose() method)

 

That’s it!

Entities, Selection Sets and Features.

Many people have asked how they can turn an AutoCAD entity or selection set into a set of Topobase features. This comes up because within AutoCAD, Topobase features for a class are presented to the user as layer which has a single corresponding FDO bulk feature in the AutoCAD drawing. Manipulating this entity for selection and highlighting is challenging.

However, given that you have access to the Topobase context as described in Accessing Documents from AutoCAD Commands you can convert a selection set into FeatureList using a combination of the Map Platform API and Topobase API.

The crucial step is the conversion from a set of AutoCAD entities to an MgSelectionBase object using the AcMapFeatureEntityService:

selection = AcMapFeatureEntityService.GetFeatures (ObjectIdCollection);

Another common use-case is to be able to programmatically ask the user to select a Topobase feature on the screen. This works fine using Document.Map.GetFeatures() from within a workflow, but when executed from an AutoCAD command it will generate an error that There is an active command in Topobase! Abort first the pending command and try again. This is because Topobase checks and finds that an AutoCAD command is running - but this is the one calling GetFeatures!

One way around this is to select your own features at a user chosen point with a spatial query over appropriate feature classes using FeatureClass.GetFeatures (true, Spatial_Mask.Struct, Geometry).

Both of these use-cases are demonstrated in a sample program, which you can download as a ZIP file of a complete project using the link below.

To build this project, define the environment variable TopobaseClientDirectory to point to the Topobase Client directory and execute the solution file:

C:>set TopobaseClientDirectory=C:\Program Files\Autodesk Topobase Client 2009

C:>FeatureSelector.sln

Build the solution and then run Topobase client and from the AutoCAD prompt execute either SelectFeatures or PickFeatures:

Command: SelectFeatures
Command: PickFeatures

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Download FeatureSelector.zip

Changing Dialog Properties

A very powerful feature of Topobase is the use of attribute forms.

A significant amount of functionality exists in Topobase Administrator to format these forms in various ways, such as using different components, splitting attributes between tabs, specifying labels and so on.

But there's limited functionality to adjust the colors or fonts for all forms. You can use a static Picture Control and use this as a Background picture behind the other Controls, but this involves editing each attribute form separately.

For desktop operation you can access and set the underlying Windows form properties for all forms by using a DialogPlugIn as the following code illustrates.

/// 

/// Sample DialogPlugIn to change the background colour.
/// 
public class FormattingDialogPlugIn : Topobase.Forms.DialogPlugIn
{
    private readonly Color COLOUR = System.Drawing.Color.AliceBlue;

    public override void OnOpened (object sender, System.EventArgs args)
    {
        Form form;
        Control active;
        TabControl tabs;

        base.OnOpened (sender, args);
        if (Application.IsDesktop)
        {
            form = Dialog.Desktop.DockInForm;
            form.BackColor = COLOUR;
            foreach (Control control in form.Controls)
                control.BackColor = COLOUR;
            active = form.ActiveControl;
            active.BackColor = COLOUR;
            tabs = active as TabControl;
            foreach (TabPage page in tabs.TabPages)
                page.BackColor = COLOUR;
            form.PerformLayout ();
        }
    }
}

This code runs when the form is opened. It checks that the application environment is 'desktop', and then adjusts the background color for the form. This will adjust all forms, but you could be more selective by checking for a specific feature class or classes using the Dialog.FeatureClass property.

If you use this technique to adjust fonts, be aware that the position of the labels will not change, so you should choose the same font size to avoid a formating issues.

A link to download a ZIP file of a complete project using this code can be found below. A pre-built binary is included. To install these binaries, copy the FormattingDialogPlugIn.dll and FormattingDialogPlugIn.tbp files to the Topobase Client bin directory and the Topobase Administrator bin directory.

To build this project, define the environment variable TopobaseClientDirectory to point to the Topobase Client directory and execute the solution file:

C:>set TopobaseClientDirectory=C:\Program Files\Autodesk Topobase Client 2009
C:>FormattingDialogPlugIn.sln

Download FormattingDialogPlugIn

Topobase API - Defensive programming within Topobase

Does your code work with job enabled Topobase documents?
Or with read-only feature classes? Have you ever tested?

If you can’t answer all the three questions with yes, then this post is for you.

Here is a simple function which does only update a single feature.

public bool UpdateFeature(FeatureClass fc, Feature feature)
{
     return fc.UpdateFeature(ref feature);
}

First test, what happens if somebody calls this method with a feature class which is still null/nothing?
Of course it crashes with a null reference exception. Best practice is to test the parameters if they are null/nothing:

if (null == fc) throw new ArgumentNullException("fc");
if (null == feature) throw new ArgumentNullException("feature");

Second test, what happens if the customer has set the feature class to read only? For instance if the feature class is based on a read only database view. It crashes again, this time with a FeatureClassIsReadOnly exception. To prevent such a crash, just add a check:

public bool UpdateFeature(FeatureClass fc, Feature feature)
{
     if (fc.ReadOnly)
     {
          return false;
     }

     return fc.UpdateFeature(ref feature);
}

Third test, your document is now job enabled. What happens if the current feature class is not in the current job template? Or if the current job is already in pending or live state?
 It crashes. If the user forgot to select a job before calling your function we throw a RootJobIsReadOnly exception. If the job is already in pending state we throw a FeatureClassNotModifiableInJob exception.

A new check is necessary (ModifiableInSelectedJob):

public bool UpdateFeature(FeatureClass fc, Feature feature)
{
     if (fc.ReadOnly || !fc.ModifiableInSelectedJob)
     {
          return false;
     }

     return fc.UpdateFeature(ref feature);
}

All these checks can be done before updating the feature in the database. So it should be pretty straight forward to add them to your code. The fourth and the last check in my example can’t (yet) be implemented before calling UpdateFeature(). We have to do a try/catch block around UpdateFeature, because we throw an exception if the feature is located outside the current job perimeter.

I would say, unless I forgot something very important, with the following code you would be on the safe side:

public bool UpdateFeature(FeatureClass fc, Feature feature)
{
     if (null == fc) throw new ArgumentNullException("fc");
     if (null == feature) throw new ArgumentNullException("feature");

     if (fc.ReadOnly || !fc.ModifiableInSelectedJob)
     {
          return false;
     }

     try
     {
          return fc.UpdateFeature(ref feature);
     }
     catch (FeatureOutsideJobPerimeterException ex)
     {
          // TODO: custom error handling
          return false;
     }
}