About the Speaker

Transcript About the Speaker

Autodesk Vault Programming: Now with Events

Doug Redmond Software Engineer, Autodesk Inc.

About the Speaker

Doug Redmond has been a software engineer for Autodesk for almost 12 years. In that time, he has worked on three separate product lines: Streamline, Vault and Productstream Professional. He has worked on Vault for over 7 years, developing features and overseeing the APIs. Doug has put together every version of the Vault SDK and written most of the sample applications.

Class Summary

This class is for programmers that want to take advantage of the event features in the Vault 2012 API. This will be a deep dive into the different types of events, how they work, how they can be used, common pitfalls, known limitations and best practices.

Events is one of the more complex programming topics and this class is designed for professional programmers. This class also assumes you are familiar with Vault and the Vault API.

See CP4534 – An Introduction to Autodesk Vault Programming Vault API basics.

Class Outline

    Explain the 4 types of events (55 min): Web Service Command Events Web Service Invoke Events Vault Explorer Command Events Lifecycle Event Jobs    Best Practices (25 min): Errors to Avoid Helpful Techniques Case Study Q & A (5 min) © 2011 Autodesk

Example

Vault

♥

Bluestreak

Overview

There are 4 types of events possible through the API:  Web Service Command Events  Web Service Invoke Events  Vault Explorer Command Events  Lifecycle Event Jobs Each type has it’s own set of rules, restrictions, advantages, and disadvantages. Make sure that you use the right tool for the job.

Web Service Command Events

The “ Web Service API” is the set of functions in the Vault API that let you communicate with the Vault Server. It’s the main component of Autodesk.Connectivity.WebServices.dll.

At the web service level, a command is just a grouping of similar functions. The purpose is to abstract the concept from the implementation.

For example: If you are interested in the AddFolder

command

, you don’t need to care which

function

Web Service Command Events

Web Service Command Events lets you hook into Vault logic without caring about the actually API function being called.

There are a limited set of commands and not every web service function will trigger an event. Only “major” operations will fire events.

Web Service Command Events

Here is a table of all the web service commands.

Command

Add Delete Reserve for Update Commit Update Change Lifecycle

Files

Yes Yes Yes Yes Yes

Folders

Yes Yes N/A N/A N/A

Items

Yes Yes Yes Yes Yes

Change Orders

Yes Yes Yes Yes Yes Additionally you can respond to File Download events and Item Promote events.

Web Service Command Events

 A web service function will not fire more than one event.

 For example, CheckoutFile(...) will only fire the Checkout event. It will not fire a Download event even though you can download through a checkout.

 The full list of function to event mapping is in the SDK documentation.

Web Service Command Events

The intent of Web Service Events is to allow you to hook to

every

computer with a single set of code.

Vault client on a given In reality, the feature allows you to hook to anything that uses Autodesk.Connectivity.WebServices.dll to communicate with the Vault server. Almost every Vault-aware Autodesk product uses this DLL. 3D Studio Max is the only one that does not. Third-party developers are encouraged to used Autodesk.Connectivity.WebServices.dll.

Since this mechanism is client-based, you need to deploy to all clients if you want full coverage.

Web Service Command Events

GetRestrictions Pre Web Service call Post GetRestrictions Event – All subscribers get a chance to block commands by adding restrictions to the event args.

Pre Event – All subscribers get a chance to execute code prior to the web service call. Subscribers cannot alter the data being passed to the server.

Web Service call Post Event – Request made to the server. Data returned from server.

– All subscribers get a chance to execute code after the web service call. Subscribers cannot alter the data being returned from the server. Post will still be invoked if the server returns an error.

Web Service Command Events

GetRestrictions Pre Web Service call Post 1.

App makes a call to one of the command functions.

GetRestrictions event goes out to all subscribers.

If there are no restrictions, the Pre event goes out to all subscribers.

Web Service function is called. Server returns a result.

Post event goes out to all subscribers.

App continues as normal.

Web Service Command Events

How it works:  DLL is written with a class that implements IWebServiceExtension interface.

 DLL is deployed to the required location %ProgramData%\Autodesk\Vault 2012\Extensions\[Your Extension Name]  At runtime, apps using Autodesk.Connectivity.WebServices.dll will load the extension.

 Vault framework creates a new object for the IWebServiceExtension implementation class.

 Vault framework calls OnLoad() on the new object.

Web Service Command Events – Example Code

{ public class EventHandlers : IWebServiceExtension } { public void OnLoad() DocumentService.AddFolderEvents.GetRestrictions += new EventHandler < AddFolderCommandEventArgs >(AddFolderEvents_GetRestrictions); DocumentService.DeleteFolderEvents.GetRestrictions += new EventHandler < DeleteFolderCommandEventArgs >(DeleteFolderEvents_GetRestrictions); } { void AddFolderEvents_GetRestrictions(object sender, AddFolderCommandEventArgs e) // do stuff } } { void DeleteFolderEvents_GetRestrictions(object sender, DeleteFolderCommandEventArgs e) // do stuff © 2011 Autodesk

Web Service Command Events

Objects from your extension DLL get loaded into all Vault enabled applications on the computer.

Web Service Command Events

This mechanism can still be used without implementing IWebServiceExtension and creating a specific deployment.

If you hook to the events in your app or plug-in, your handler will only receive events from within the current .Net app domain.

Web Service Command Events

Here is a table illustrating the two types of event scope.

Customized to a specific app UI Enforcement of rules Low level business logic High level business logic

Handle events from all Vault clients on the computer No

You should be able to work in any hosting app.

The handler should assume that the hosting app supports it.

Handle events only from the running app Yes

You know the hosting app, so you can tailor your handler.

Yes

Assuming that hosting app supports it.

Yes

It can act as a gatekeeper for your Vault data.

You can only enforce rules for a single app.

Yes

It operates well at low levels, in the absence of context.

You can only provide business logic for a single app.

It has no knowledge of context.

Yes

You can provide context of the current app command.

Web Service Command Events

In practice, the “single app” scope is usually the type you want to go with.

Exhaust that possibility first before moving to the “all apps” scope.

Web Service Command Events

End of Web Service Command Events section. Please clear your mind.

Web Service Invoke Events

 All web service calls go through a function called Invoke .

 Pre and post events were added around the Invoke command.

 As a result, you have a single choke point for all your web service calls.

 In the event handlers, you have complete control over data going in and out.

 You can only hook to objects that you create.

Web Service Invoke Events

Pre Web Service call Post Pre Event – Your code gets a chance to execute code prior to the web service call. Data can be altered.

Web Service call – Request made to the server. Data returned from server.

Post Event – Your code gets a chance to execute code after the web service call. Data can be altered. Post will still be invoked if the server returns an error.

Web Service Invoke Events

Historical Background: In previous releases, each client would generate their own code for the service classes. This gave developers a lot of freedom to manage the behavior of their services.

With the creation of Autodesk.Connectivity.WebServices.dll the classes are provided. This means less freedom but greater ease-of-use.

Invoke events provides some of the features that were previously available when developers had control over the service code.

Web Service Invoke Events

Built-in feature: Automatic re-sign in The problem: The Vault server logs you out after 30 minutes of inactivity. When this happens error, 300 is thrown on the next API call.

The solution: An post event handler that checks for error 300. When that happens, the hander attempts to re-authenticate and re-run the original command. The result of the second try is passed back to the caller.

If everything goes well, the caller has no idea that a re-sign-in happened.

Web Service Invoke Events – Example Code

public void RunCommand( string serverName) { using ( WebServiceManager serviceManager = new WebServiceManager (login)) { serviceManager.DocumentService.PostInvokeEvents += new EventHandler < WebServiceInvokeEventArgs >(DocumentService_PostInvokeEvents); // do stuff } } void DocumentService_PostInvokeEvents( object sender, WebServiceInvokeEventArgs { e) string output = e.MethodName + Environment .NewLine; if (e.Exception != null) output += e.ToString(); System.IO.

Web Service Invoke Events

End of Web Service Invoke Events section. Please clear your mind again.

Vault Explorer Command Events

  Your extension to Vault Explorer can receive notification whenever a command is run.

In Vault Explorer, a “command” is usually a menu click or toolbar click.

 You can receive a pre and a post.

 The only information you are given is the internal name of the command.

 Custom commands will also trigger these events, including any commands defined in your extension.

 This feature doesn’t have much use on its own, but is very useful in conjunction with other event types.

Vault Explorer Command Events

Pre Vault Explorer command Post Pre Event – All subscribers get a chance to execute code prior to the command. Data cannot be altered.

Vault Explorer Command – Vault Explorer runs the command. May involve UI.

Post Event – All subscribers get a change to execute code after the command completes. Data cannot be altered. Post will still be invoked if the command is cancelled or encounters errors.

Web Service Invoke Events – Example Code

public void OnStartup( IApplication { application) application.CommandBegin += new EventHandler < CommandBeginEventArgs >(application_CommandBegin); application.CommandEnd += new EventHandler < CommandEndEventArgs >(application_CommandEnd); } void application_CommandBegin( object { MessageBox.Show( "Pre event: " sender, CommandBeginEventArgs + e.CommandId); } e) void application_CommandEnd( object { sender, CommandEndEventArgs MessageBox.Show( "Post event: " + e.CommandId); } e) © 2011 Autodesk

Vault Explorer Command Events

Web Service Invoke Events

End of Vault Explorer Command Events section. Please clear your mind one last time.

Lifecycle Event Jobs

 The server can be configured to create jobs whenever an entity changes lifecycle state.

 Entity = file, item or change order.

 The job can be viewed as a post event.

 Each entity that is changed triggers one job.

 Since the job queue is involved, the events are not processed immediately.

 You can define which lifecycle transitions trigger which jobs through the API or through the Lifecycle Event Editor in the SDK.

Lifecycle Event Jobs

Putting it All Together

Hook Points In-line behavior Scope Triggered on Client or Server Read/write Guaranteed delivery Post event on error “Big picture” awareness “Task” awareness

Web Service Command Events

GetRestrictions, Pre, Post Part of execution thread All Vault apps on a computer. -- or - Single Vault app.

Client

Web Service Invoke Events

Pre, Post Part of execution thread Service objects in your project.

Client Read only No Yes Low High

Read/write

No Yes Low High

Vault Explorer Command Events

Pre, Post Part of execution thread Vault Explorer.

Lifecycle Event Jobs

Post

Outside execution thread

A Vault.

Client Read only No Yes

High

Low

Server

Read only

Yes No

Putting it All Together

Vault Explorer Command Pre Web Service Command GetRestrictions Web Service Command Pre Web Service Invoke Pre Function called on server Server function completes User clicks a command Job Queued Job Handled Job Processor Timeline Web Service Invoke Post Web Service Command Post Vault Explorer Command Post Vault Explorer Timeline User gets control back Vault Server Timeline © 2011 Autodesk

Odd Behaviors

 Remember that the parent app has no idea what your event call is doing.

Side effects may include:  Incorrect status icons  Application errors  Application crashes  The parent app may be passing in “stupid” data.

 For example, Vault Explorer passes in the full local path for the filename during AddFile(...)  Post events are usually better since you can check the error status. In Pre, events you can’t assume good data.

Best Practices

 In a post event, always check that the operation succeeded.

  Don’t crash the hosting app.

Don’t let exceptions bubble up out of your event handler.

 Play by the rules of the hosting app.

 Don’t cause a noticeable degradation of performance.

 If a Download operation takes 5 seconds and your event handler takes .5 seconds, you have increased things by 10%.

 If a Checkout operation takes .5 seconds and your event handler takes .5 seconds, you have increased things by 100%.

Useful Techniques

 Multi-threading – Sometimes actions are better performed in a worker thread.

 Perform things at a later time – You don’t have to do the action within the handler. Sometimes it’s better to record what you want to do for later.  Job Server  Wait until the UI command is completed  Use multiple event types – Don’t feel you have to use a single event type for everything. In many cases, different event types complement each other.

 Handle bulk operations – Sending out an email during AddFile() is a bad idea since 100 files added = 100 emails sent.

Case Study - Vault

♥

Bluestreak

All of these techniques are used in the Bluestreak integration.

 Multi-threading – Data is sent to Bluestreak in a worker thread.

 Perform things at a later time – Data is sent to Bluestreak only after the Vault Explorer command is complete.

 Use multiple event types – Web Service Command Events and Vault Explorer Command Events are both used.

 Handle bulk operations shows the count.

Case Study - Vault

♥

Bluestreak

Basic workflow: 1.

Vault Explorer starts up: Set up empty Lists. Set up event hooks. 2.

Web Service Command is completes – LC State Change Post Event: Add entries to the Lists, recording what changed.

Vault Explorer command completes – Post Event: Check our lists. If they are not empty we send the data to worker thread.

Clear the lists.

Worker Thread: Send data to Bluestreak activity stream.

Case Study - Vault

♥

Bluestreak

Vault Explorer startup: public void OnStartup( IApplication { application) m_coChanges = new List < UpdateChangeOrderLifeCycleStateCommandEventArgs >(); m_itemChanges = new List < UpdateItemLifeCycleStateCommandEventArgs >(); m_fileChanges = new List < UpdateFileLifeCycleStateCommandEventArgs >(); application.CommandEnd += new EventHandler < CommandEndEventArgs >(application_CommandEnd); } DocumentServiceExtensions.UpdateFileLifecycleStateEvents.Post += new EventHandler < UpdateFileLifeCycleStateCommandEventArgs >(UpdateFileLifecycleStateEvents_Post); ItemService.UpdateItemLifecycleStateEvents.Post += new EventHandler < UpdateItemLifeCycleStateCommandEventArgs >(UpdateItemLifecycleStateEvents_Post); ChangeOrderService.UpdateChangeOrderLifecycleStateEvents.Post += new EventHandler < UpdateChangeOrderLifeCycleStateCommandEventArgs >(UpdateChangeOrderLifecycleStateEvents_Post); © 2011 Autodesk

Case Study - Vault

♥

Bluestreak

Web Service Command - post event: void UpdateFileLifecycleStateEvents_Post( object { if (e.Status != EventStatus.

SUCCESS) return; try { } } catch { } sender, UpdateFileLifeCycleStateCommandEventArgs // log the event if there is at least one file moved to released for (int i = 0; i < e.FileMasterIds.Length; i++) { if (m_cache.IsReleasedFileLfCycId(m_mgr, e.ToStateIds[i])) { m_fileChanges.Add(e); break; } } e) © 2011 Autodesk

Case Study - Vault

♥

Bluestreak

Vault Explorer Command - post event: void application_CommandEnd( object { try { sender, CommandEndEventArgs e) if ((m_fileChanges.Count + m_itemChanges.Count + m_coChanges.Count) == 0) return; UserIdTicketCredentials_bugfix cred = new UserIdTicketCredentials_bugfix ( m_cred.ServerName, m_cred.VaultName, m_mgr.SecurityService.SecurityHeader.UserId, m_mgr.SecurityService.SecurityHeader.Ticket); ThreadPool .QueueUserWorkItem(PostCommandEndActivitiesWorker, new object[] { m_fileChanges.ShallowCopy(), m_itemChanges.ShallowCopy(), m_coChanges.ShallowCopy(), cred }); } catch { } m_fileChanges.Clear(); m_itemChanges.Clear(); m_coChanges.Clear(); } © 2011 Autodesk

Case Study - Vault

♥

Bluestreak

Nice features:  Slowness in Bluestreak does not affect Vault Explorer performance.

 Entries in activity stream correspond to a single Vault command.

 We don’t care which Vault Explorer command is run.

 Upload command is done with custom command. No events used.

Vault

♥

Bluestreak

Questions

Reminder – Fill out the surveys

CP4547 - Autodesk Vault Programming: Now with Events

Autodesk, AutoCAD* [*if/when mentioned in the pertinent material, followed by an alphabetical list of all other trademarks mentioned in the material] are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names, or trademarks belong to their respective holders. Autodesk reserves the right to alter product and services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graph ical errors that may appear in this document. © 2011 Autodesk, Inc. All rights reserved. © 2011 Autodesk

About the Speaker

Transcript About the Speaker

Autodesk Vault Programming: Now with Events