It's All Just Ones and Zeros

Project Thunderdome 2014

Update: Thunderdome 2015 has been released.

Wow.  I can’t believe I’m on the 4th release of Thunderdome.  They grow up so fast.  If you are not familiar with the app, Project Thunderdome lets you deploy various Vault settings to all your Vault users.  Settings include, shortcuts, saved searches, grid settings, DECO UI, and even Vault plug-ins.

This time around I just ported the app to 2014 and didn’t add any new features.  So have a look at the Thunderdome 2013 to get a feel of the full feature set.  Looking over the 2013 comments, some people mentioned that the Grid State only applied to the main grid.  I tested things out in 2014 and Grid State seems to also apply to the default tabs, such as History. 

---

Requirements:
Vault Workgroup/Professional 2014

Click here to download application
Click here to download source

Click here for the 2013 version

As with all the samples on this site, the legal disclaimer applies.

Updating a Plug-in to Vault 2014

Things changed just enough to be annoying when updating your plug-in to Vault 2014.  So I thought I would make a quick video on how to update your app.  This is actually me updating DECO 2013 to 2014, which makes for a good real-world example. 

 

Here is a quick summary of my steps, which can be done in any order:

• Updated my file and assembly version numbers (optional)
• Updated my references to use the Vault 2014 SDK DLLs.
• Added reference to Autodesk.DataManagement.Client.Framework.dll
• Added reference to Autodesk.DataManagement.Client.Framework.Vault.dll
• Deployed to %ProgramData%\Autodesk\Vault 2014\Extensions
• Changed the class implementation from IExtension to IExplorerExtension.
• Updated code to use Connection object instead of creating a WebServiceManager from the VaultContext.
• Fixed any compile errors from web service API changes.
• Removed any code that held a reference to a WebServiceManager.
• Updated .vcet.config file.
• Updated the ApiVersion assembly attribute.

DevExpress DLLs

The Vault 2014 SDK contains a bunch of DLLs from a third-party vendor, DevExpress.  Autodesk and DevExpress entered into an agreement for usage and distribution of these DLLs in the Vault SDK.  Here is my understanding of that agreement.  Keep in mind that I do not represent the Autodesk legal department.

Background

The Vault 2014 API contains re-usable UI components, which make use of DevExpress controls.  Therefore those controls needed to be included in the Vault SDK.

The Agreement

The DevExpress DLLs in the Vault SDK (these are the ones in the bin folder that start with “DevExpress”) are free for you (the user of the Vault SDK) to use and re-distribute within the context of the Vault SDK. 

However, if you use the DevExpress controls directly, then you need to get a developer license from DevExpress.  Things like cost, and usage are between you and DevExpress.  Autodesk has no involvement.

If you try to make direct use of DevExpress controls without a license, you should see a pop-up in Visual Studio indicating unlicensed usage.

DevExpress website:  http://www.devexpress.com/

Examples

If you paste a VaultBrowserControl in your dialog, that’s free, even though VaultBrowserControl makes use of DevExpress controls internally.

If you paste a DevExpress.XtraGrid control in your dialog, you need a DevExpress developer license.

DLL Redistribution

The Vault Client installs all the needed DevExpress controls into the GAC.  So if your app requires the Vault Client, then you don’t need to re-distribute the DevExpress DLLs.  It’s only in cases where the user may not have the Vault Client that you need to worry about re-distributing the DLLs. 

Although the DLLs can go in the GAC, I recommend putting the DevExpress DLLs in the running folder.

Special Thanks

Thanks goes out to the people at DevExpress.  Not only did they let us include their DLLs in he Vault SDK, but they also make good controls.  Since the very first Vault release, the Vault client has been using DevExpress controls to great satisfaction.

How to Acquire Files

Downloading and checking-out is so last year.  The fashionable Vault API developer acquires their files.  It has more style and class.  Also, DocumentService.DownloadFile and DocumentService.CheckoutFile are no more in the 2014 API.  So that kind of forces the issue.  Connection.FileManager.AcquireFiles is the replacement.  I’ll go over the architectural reason for the change in a later article.

---

Benefits of AcquireFiles

Yes, it’s a pain to have to update your code, but let me go over the benefits before you get too distraught. 

• Downloads files to the working folder by default.
• Automatically handles large files.
• Automatically repairs broken references for known CAD file types.
• Can download entire assemblies in one call.
• Multi-thread download.  It’s about 2x quicker when downloading an assembly.
• Get/checkout dialog available.
• Automatically sets file attributes, such as read-only and create date.

The only disadvantage that I have come across is that you can’t read a file directly into memory.  You always acquire to a location on disk.  The workaround is to acquire to a temp location, read the file to memory, then delete the temp file.

---

Here is some sample code.

// C# using VDF = Autodesk.DataManagement.Client.Framework;   public void DownlodFiles(ICollection<VDF.Vault.Currency.Entities.FileIteration> fileIters) {     // download individual files to a temp location     VDF.Vault.Settings.AcquireFilesSettings settings =         new VDF.Vault.Settings.AcquireFilesSettings(m_conn);     settings.LocalPath = new VDF.Currency.FolderPathAbsolute(@"c:\temp");     foreach (VDF.Vault.Currency.Entities.FileIteration fileIter in fileIters)     {         settings.AddFileToAcquire(fileIter,             VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download);     }       VDF.Vault.Results.AcquireFilesResults results = m_conn.FileManager.AcquireFiles(settings); }   public void DownloadAssembly(VDF.Vault.Currency.Entities.FileIteration topLevelAssembly) {     // download the latest version of the assembly to working folders     VDF.Vault.Settings.AcquireFilesSettings settings =         new VDF.Vault.Settings.AcquireFilesSettings(m_conn);     settings.OptionsRelationshipGathering.FileRelationshipSettings.IncludeChildren = true;     settings.OptionsRelationshipGathering.FileRelationshipSettings.RecurseChildren = true;     settings.OptionsRelationshipGathering.FileRelationshipSettings.VersionGatheringOption =         VDF.Vault.Currency.VersionGatheringOption.Latest;     settings.AddFileToAcquire(topLevelAssembly,         VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download);       VDF.Vault.Results.AcquireFilesResults results =         m_conn.FileManager.AcquireFiles(settings); }   public void DownloadDialog(VDF.Vault.Currency.Entities.FileIteration fileIter,     IntPtr parentWindowHandle) {     // pop up the Get/Checkout dialog     VDF.Vault.Forms.Settings.InteractiveAcquireFileSettings settings =         new VDF.Vault.Forms.Settings.InteractiveAcquireFileSettings(             m_conn, parentWindowHandle, "Download files");     settings.AddEntityToAcquire(fileIter);       VDF.Vault.Forms.Library.AcquireFiles(settings); }

' VB Imports VDF = Autodesk.DataManagement.Client.Framework   Public Sub DownlodFiles(fileIters As ICollection(Of VDF.Vault.Currency.Entities.FileIteration))        ' download individual files to a temp location        Dim settings As New VDF.Vault.Settings.AcquireFilesSettings(m_conn)        settings.LocalPath = New VDF.Currency.FolderPathAbsolute("c:\temp")        For Each fileIter As VDF.Vault.Currency.Entities.FileIteration In fileIters               settings.AddFileToAcquire(fileIter, _ _                VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download)        Next          Dim results As VDF.Vault.Results.AcquireFilesResults = _            m_conn.FileManager.AcquireFiles(settings) End Sub   Public Sub DownloadAssembly(topLevelAssembly As VDF.Vault.Currency.Entities.FileIteration)        ' download the latest version of the assembly to working folders        Dim settings As New VDF.Vault.Settings.AcquireFilesSettings(m_conn)     settings.OptionsRelationshipGathering.FileRelationshipSettings.IncludeChildren = True     settings.OptionsRelationshipGathering.FileRelationshipSettings.RecurseChildren = True     settings.OptionsRelationshipGathering.FileRelationshipSettings.VersionGatheringOption = _            VDF.Vault.Currency.VersionGatheringOption.Latest        settings.AddFileToAcquire(topLevelAssembly, _            VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download)          Dim results As VDF.Vault.Results.AcquireFilesResults = _            m_conn.FileManager.AcquireFiles(settings) End Sub   Public Sub DownloadDialog(fileIter As VDF.Vault.Currency.Entities.FileIteration, _     parentWindowHandle As IntPtr)        ' pop up the Get/Checkout dialog        Dim settings As New VDF.Vault.Forms.Settings.InteractiveAcquireFileSettings( _            m_conn, parentWindowHandle, "Download files")        settings.AddEntityToAcquire(fileIter)          VDF.Vault.Forms.Library.AcquireFiles(settings) End Sub

Finally a Good Splash Screen

I’ve been waiting for this for almost 9 years, and it’s finally here.  Vault has a good splash screen!

Don’t get me wrong.  The old splash screens were not bad, they just didn’t fit well with the product.  Commonly the Vault screens would be very CAD related.

The above image would look perfect on AutoCAD or Inventor, but it just doesn’t fit Vault.  It’s not a bad image, but it doesn’t describe what the product is about.

---

Some of the early releases of Vault used “guys standing around a table” imagery.

This is better, but it doesn’t quite hit the mark.  Notice the lack of computers or anything hi-tech.  Some of the images even featured people staring at blueprints.  Although there is a collaboration aspect to Vault, it’s not really meant to simulate face-to-face meetings like what is being shown.

---

Vault is really about connecting and organizing CAD data, which brings us to the Vault 2014 splash screen.

Ahh, look at it.  A thing of beauty.  It has a nice hi-tech vibe to it and is pleasing to the eye.  So what do the interconnected balls represent?  The vault client and server components?  CAD files?  People?  Data management systems?  The answer is all of the above.  Vault does all of those things, and those things are a fitting description of Vault. 

Vault is a hard product to describe, so it doesn’t surprise me that it took so long to get it right.  I’m just glad it happened.  As a programmer, I usually don’t care about things like branding, but it looks like some real effort was put in to understand the products.  I’m not just talking about Vault either.  All the new Autodesk product releases are accompanied by amazing imagery.

Getting to Know the VDF

The VDF will feel a lot different than the rest of the Vault API.  It’s almost as if it was built by a completely different team.  The reason is because it was built by a completely different team.  There are other reasons too.  Working with UI components is different than working with server calls.  Also, the VDF is able to follow a more object oriented approach than the web service layer.

But I'm getting ahead of myself.  This post is about getting to know the VDF.  No talk of commitment or marriage or anything.  It's just a nice casual tour of the major components.

---

The DLLs

There are 4 DLLs that make up the VDF.  They are the ones that start with Autodesk.DataManagement.

Autodesk.DataManagement.Client.Framework.dll - This contains components that are not Vault-specific and do not contain UI.  Features include logging and error parsing.

Autodesk.DataManagement.Client.Framework.Forms.dll - This contains UI components that are not Vault-specific.  Features include an error dialog and progress dialog.

Autodesk.DataManagement.Client.Framework.Vault.dll - This contains Vault utilities but no UI.  Features include Connection management, download/upload workflows, working folder information, and Entity objects.

Autodesk.DataManagement.Client.Framework.Vault.Forms.dll - This contains Vault UI.  Features include the login dialog, browse control, and checkout dialog.

---

Entry Points

Each DLL has a Library object which contains a set of static methods.  The methods themselves are dependent on the feature set of the DLL.  The other major entry point is the Connection object, which has a set of managers.  Each manager contains methods for invoking high level workflows.  There is some overlap between VDF managers and web service managers.  For example, you can add a category through Connection.CategoryManager.AddCategory or Connection.WebServiceManager.CategoryService.AddCategory.

---

Currency and Services

The VDF has its own set of currency objects.  These are basic objects used only for structured data.  Objects that perform actions are referred to as services (aka. managers).  VDF currency is similar to the Web Service currency, but there is usually more information in the VDF currency.  For example, the VDF’s FileIteration object has object references to the parent Folder and Category object reference.  The web service equivalent, File, has only ID references to parent Folder and Category.

You will frequently have to convert between the VDF and web service currency.  You can construct a VDF object from a web service object.  You can also cast down from VDF to web service object.  So it’s not too bad, but you still have to keep track of the different sets of currency.

---

Settings and Results

The VDF supports many complex workflows, which may have multiple configuration options.  Instead of having functions with 20+ inputs, the VDF uses a settings object instead.  If you want the default behavior, you can just new up a settings object and pass it in to the workflow or UI.  Alter the settings object if you want non-default behavior.

The results of a workflow can be just as complex as the inputs, which is where the results object comes in.  If something goes wrong, don’t assume you will get an exception.  In many cases, you need to check the results object to see if there were failures or not.  Also, when UI is involved, you can’t assume that the user did what they were supposed to do.