It's All Just Ones and Zeros

2 API-Related Hotfixes

Recently there have been some hotfixes released to address Vault 2012 API issues.

API Log In Hotfix
This gives you a new Autodesk.Connectivity.WebServicesTools.dll which contains a WebServiceManager that doesn't log out at incorrect times.  I still recommend using the bugfix credential classes because, if there are multiple extensions, some of them may contain the old DLL.  There is no way know which version of WebServicesTools gets loaded at runtime.

Because the SDK is distributed as an installer, the hotfix updates that installer.  You need to re-install your SDK to get the updated DLL.

---

API Working Folder Hotfix
IExplorerUtil had an issue with the GetWorkingFolder function which caused it to return the incorrect path.  That issue had a ripple effect causing GetLocalFileStatus and DownloadFile(File, Folder) to also be incorrect.  This hotfix corrects the problem, so all 3 functions should work properly now.

The fix is in one of the Vault Explorer DLLs.  The SDK itself does not get updated.  If you are using IExplorerUtil, you do not need to change anything, nor do you need to re-compile code.

Issues with the Vault 2012 API

There are a couple of issues that have already been found with the latest SDK.  I want to make sure everyone knows about them upfront.

UserIdTicketCredentials and WebServiceCredentials

 Please avoid using UserIdTicketCredentials and WebServiceCredentials in Autodesk.Connectivity.WebServicesTools.dll.  We found an issue where they log out of Vault incorrectly in certain cases.

If you don't know what these classes are, it's because they are new in Vault 2012.  The classes are used to provide login information to the new WebServiceManager class.

Workaround:  The links below contain fixed versions of the classes.  Basically the logout capability has been disabled so there is no danger for accidental logout.  To use, just add the .cs or .vb  to your project and use the UserIdTicketCredentials_bugfix or WebServiceCredentials_bugfix classes in place of the normal classes.

Click here for the C# fix
Click here for the VB.NET fix

 

 

Menu resets still needed for custom commands

I had this fixed.  I swear.  Unfortunately, something happened between my fix and the final release.  So when you deploy new Vault Explorer commands, you will need to reset the menus before you can see it in the menu bar.

The good news is that toolbars don't need a reset and menus are much more stable than they were in Vault 2011.  You should no longer see cases where the entire menu bar gets jumbled because a custom command was deployed or removed.

Workaround:  Do a menu reset after deploying a custom command.  The reset command can be found manually by right clicking on the menu bar and running the Customize command.  Programmatically, a reset can be done by deleting the menu.xml file in %AppData%\Autodesk\[Vault Product]\Objects\Menu.xml.
It's the same as the Vault 2011 workaround.

Setting your project to .NET 3.5

Update: For Vault 2013, we moved over to .NET 4.  See this post for more details.  The rest of this article refers to Vault 2012.

We don't support .NET 4.0 extensions for Vault Explorer or Job Processor.  The problem is that Vault Explorer and Job Processor are 3.5 applications.  And a 3.5 application cannot load a 4.0 DLL.  In these cases, you will usually see an error message like, "Could not load file or assembly 'Foo' or one of its dependencies. The system cannot find the file specified."

To fix, you need to switch your compile settings to .NET 3.5 or earlier. 

To change the settings is a VS 2010 C# project, go to the Application tab in your project settings and change the Target Framework.

 

To change the settings is a VS 2010 VB.NET project, go to the Compile tab in your project settings and click the Advanced Compile Options button.  In the dialog that pops-up, change the Target framework.

 

File Transfer as Binary Data

Introduction
Communication with the Vault server takes the form of SOAP commands over HTTP.  As you may know, SOAP is XML data, and XML is text.  Does that mean the program you wrote uploads and downloads files as text data?

By default, the answer is yes, your program converts files to text when transferring files.  This can be a big performance problem if your program has to upload thousands of files.  The conversion to base64 eats up CPU cycles and increases the transfer size by about 30%.

Setting up your project
If you want to transfer your files in binary mode, there are several steps you need to go through:

1. Download and install Microsoft Web Service Extensions (WSE) 3.0.  You can find it on the Microsoft site.  (I'd post a direct link, but they keep changing it).
2. If you are using Visual Studio 2005, select the "Integrate with Visual Studio" option during the install.
3. In your project, create a reference to Microsoft.Web.Services3.
4. If you are using Vault 2012 or higher, skip to step 8. 
5. Generate your web services.
6. If you are using Visual Studio 2008 there are some extra steps:
   1. In the Solution Explorer, activate the Show All Files option.
   2. Expand the web reference and locate the Reference.cs (or Reference.vb) file and open it.
   3. Change the base class of the Service object from "System.Web.Services.Protocols.SoapHttpClientProtocol" to "Microsoft.Web.Services3.WebServicesClientProtocol"
   4. (optional) Add Wse to the end of the class name and constructor.
   5. Repeat as needed for the other web services.  However most people just fix up the Document Service.
7. In your code, use the web service classes with "Wse" at the end.
8. Create an app.config XML file if your project does not already have one.
9. Merge in the following XML:
   <configuration>   
     <configSections>       
       <section name="microsoft.web.services3"         type="Microsoft.Web.Services3.Configuration.WebServicesConfiguration, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />    
     </configSections>   
     <microsoft.web.services3>        
       <messaging>           
         <maxMessageLength value="51200" />       
         <mtom clientMode="On" />
       </messaging>       
     </microsoft.web.services3>
   </configuration>
10. When you build your project, app.config gets renamed to [EXE name].config.  Make sure you deploy this with your application.
11. You are done.

Testing
Gee, that's a lot of steps.  If any of them are not done property, the system will automatically revert to text transfer of your files.  So how do test things to make sure that files are being transferred as binary data?

UPDATE:  There is a tool called Fiddler which provides a better way to test than the technique below.  See this article for instructions on how to test using Fiddler.

Here is the approach I use.  It's not very good.  If you find a better way, please let me, and everybody else, know in the comments section.
The basic principle is to have IIS log the bytes transferred and see if that matches the size of a file that you upload or download with your application.

1. Open up your IIS manager on your Vault server machine. 
   Note: I'm using IIS 5. Things may be different depending on your version.
2. Select the web site running Vault.
3. Right click and select Properties.
4. Go to the Web Site tab.
5. Check the Enable Logging box.
   
6. Click on the Properties button.
7. Go to the Extended Properties tab.
8. Check the Extended Properties box.
9. Check the Bytes Sent and Bytes Received boxes.
   
10. Click OK on the dialogs.
11. Find a file that is at least 10 MB large.
12. Upload the file to Vault using your application.  Or add it to Vault and download it using your application.
13. Go to the IIS log and open it.  (ex.  C:\WINDOWS\system32\Logfiles\W3SVC1\ex100316.log)
14. You should see an entry to DocumentService.asmx that has a large number of bytes transferred.  For example:
    20:28:02 127.0.0.1 POST /AutodeskDM/Services/DocumentService.asmx 200 2675 14074058
15. If that large number is about the size of the uploaded file, then things work.  Otherwise something is not working right and you will need to double check your application. 
    In my case, 14,074,058 is close to the size of the file I uploaded (14,068,867).  The IIS log will always be slightly higher due to HTTP and SOAP headers.

If you want to deliberately break things to test the negative case, you can do this easily without even needing to re-compile.  Just edit your .config file and set the <mtom> clientMode setting to "Off".  Upload or download the file again and check the file size in the IIS log.  It should be significantly bigger.  For example, my test showed 18,763,057 as the transfer size, which is 33% larger than the file.

Errors and Restrictions

Update:  A better version of the below code has been provied in another article.  The new code gets both the error code and any restriction codes.

---

Errors

You are probably reading the error code incorrectly.  I'm guessing that you are getting it from the Message text of an Exception that gets thrown when you make an API call.  Although the Message usually contains the code, it's not the "correct" place to get it. 

The correct thing to do is catch the SoapException, then check the Details property, which is a bunch of XML data.  The Vault error code can be found between the <sl:errorcode> tags. Also, some errors will be accompanied by extra information in the form of a string array, found between the <sl:param> tags. Each parameter will have its own tag and "pid", which is an index value starting at 1. Most errors will not have extra parameters.  See the Error Codes page in the API documentation for more information.

If you don't get a SoapException, it means that the error is not coming from the Vault server.  Something else is causing the error, such as a network error.

---

Restrictions

Restrictions can be thought of as extended error information.  In the case of an Exception from the Vault server, there is one and only one error code.  Restrictions, however, can have multiple codes.  This is useful for complex operations where multiple things can fail at once, and you want to display everything to the user in a single dialog.

If the error code is 1092, 1387, or 1633, then you need to examine the restriction information to find out what the problem is.  For all other errors, there is no restriction information.

Just like with errors, you need to examine the Details XML in the Soap Exception.  The Restriction Codes page in the API documentation has more information.

---

Sample Code

Here is the correct way to read the error code.

C#:

public static string GetErrorCodeString(Exception e) {     SoapException se = e as SoapException;     if (se != null)     {         try         {             return se.Detail["sl:sldetail"]["sl:errorcode"].InnerText.Trim();         }         catch         { }     }     return null; }

 

VB:

Public Shared Function GetErrorCodeString(ByVal e As Exception) As String     If (TypeOf e Is SoapException) Then         Dim se As SoapException = e         Try             Return se.Detail("sl:sldetail")("sl:errorcode").InnerText.Trim()         Catch         End Try     End If     Return Nothing End Function