Smart 3D .

Net API

LAB
–
Writing Commands

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 1

LAB - Overview

• In this LAB we will learn

– Writing Custom commands in VB.Net
• Creating Project, manage its settings
• Adding required references,
• Importing required namespaces,
• Inheriting from one of the base command classes,
• Providing override implementation – command functionality
– Deploying Custom Commands
– Running Custom Commands
– Debugging Custom Commands
– Study Command Characteristics
• Modal/Non-Modal/Non-Modal & Suspendable commands

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 2
 Create a VB.Net Class Library Project
• Use Visual Studio
– VS2010 with .NET Framework v4.0 (from Smart 3D v2014).
– VS2013 with .NET Framework v4.5 (from Smart 3D v2016).
– Choose a .Net language
VB.Net / C#
• VB.Net is preferred. Most samples are in VB.Net. Our examples will be VB.Net.

• Project Type
– Use a Windows “Class Library” project template
– Can create the new command in
• an existing Class Library project you already have with other commands you have
developed.
Choose File
Open Project
• a new Class Library Project
Choose File
New Project

As this is our first Lab Command we choose New Project.

When we save the project/solution, we uncheck the “Create Directory for solution”
option. This is only useful for cases where we have multiple projects in one
solution. Our situation is that we have a SINGLE project in our solution.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 3

Create a VB.Net Class Library Project

• Choose File > New Project

• Use Visual Basic >
Windows from Project
Types
• Pick Class Library template
• Specify Name of Project
• Hit OK.
• Project gets created.
• …

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 4
 Create a VB.Net Class Library Project

• It creates a Class1.vb
which has an empty class
named Class1.
• Rename the Name of the
class from Class1 to a
name of your choice and
also rename the
filename accordingly.

• Lets say we change it to

“SampleModalCmd”, for
the sample Modal
command we will be
writing here.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 5

1. Right Click “References”

popup menu
Attach Required References
2. Click
“Add Reference”

5. Browse to
Folder location

3. Click
“Browse” Tab

4. Click
“Browse” Button

1. Select CommonClient.DLL and CommonMiddle.DLL, which are required for writing a basic command.
2. Also add the following reference for Smart3D V2016.
“Smart3D\Core\Container\Bin\SxS\Intergraph\Intergraph.CommonToolkit.Client.dll“
3. You can choose other assemblies as needed for the functionality of the command.
4. Then Select “OK” Reference Manager dialog.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 6
 References : Copy Local setting

• Typically, Visual Studio adds references with

“Copy Local : True” setting, i.e. it is copied
locally for the project’s use.

• Change it as “Copy Local : False” in the

Properties tab of the assembly reference.
You could do this by multi-selecting all added
assemblies at once.

• Otherwise, when you install updates of the

Smart 3D product(s), your projects may
continue using old copies of the references
copied at the time of adding the reference.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 7

Import Required Namespaces

• Add the required “Imports” statements at the top of the file to enable
you use the types in that namespace without using the full name of the
class when needed.

• This lets you just use

Dim oSelectSet as SelectSet

instead of
Dim oSelectSet as Ingr.SP3D.Common.Client.Services.SelectSet

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 8
 Inherit from a Base command class

• To be runnable inside Smart

3D, Commands must inherit
from one of the command
base class types
– Modal / Graphic / Step

• We then provide the

override implementation
for the properties/methods,
i.e. the command
characteristics and
functionality.

– Modal, Suspendable,
EnableUIFlags
– OnStart( ), OnStop ( )
– OnSuspend( ), OnResume( )
(for suspendable commands)
Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 9

Override Required Implementation

Public Overrides Sub OnStart(instanceId As Integer, argument As Object)

Dim oSelectSet As SelectSet = ClientServiceProvider.SelectSet
If (oSelectSet.SelectedObjects.Count = 0) Then
MsgBox("No Objects Selected")
Else
Dim strSelectedObjectNames As String = ""
For Each oObj As BusinessObject In oSelectSet.SelectedObjects
strSelectedObjectNames += vbCrLf + oObj.ToString
Next Guess what,
MsgBox(strSelectedObjectNames,, "Selected object Names") we are done !!!
End If
End Sub ??? YES

Lets see next page why we don’t have to do any more overrides.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 10
 Override Required Implementation
• We don’t have any specific OnStop( ) implementation as there is
nothing specific we want to do at the moment when the command
is stopped.
– Typically, one would want to implement cleanup code in the OnStop( ).
– The BaseModalCommand class implementation of OnStop( ) is good enough
for our case and we don’t need to provide an OnStop( )

• Also, since ours is a Modal command, there is no need to

implement the Suspendable Property as well as the OnSuspend( )
and OnResume( ) methods, because the system never needs them
for Modal commands. They can be implemented for Suspendable
commands.
• Observe that we only “override” the required implementation,
unlike in COM, we had to provide entire implementation. Thus, a
big reduction in number of lines of code compared to COM.
• At this time, our command is ready to run or debug.
Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 11

Deploying & Running Commands

• Save the Custom Command Assembly DLL to a location on the disk.
• Invoke menu item Tools > Custom Commands
• Add command to list of custom commands if not already done. (more details discussed next).
Like {FullPath}AssemblyName,NameSpace.Class – You will need
– the Assembly (DLL) Name with full path but without extension,
– the NameSpace of Command Class –
if you have not explicitly created your class in a different
namespace, it goes to project’s Root NameSpace
(see it in Application Tab of Project Properties).
– the ClassName
• Select the command and then click Run. (details later in this session)
• Other means to invoke commands exist – modifying XML files which control UI of the app. (eg
CommonApp\Environment\Xml\Include\MenuTools.xml)
• <Menuitem caption=“MyCmd" action="StartAssemblyCmdNormal" arg1="{FullPath}AssemblyName,NameSpace.Class "/>

• Note 1: FullPath is optional if you are deploying into SymbolShare\CustomCommands, or a

directory included in Environment Variable named S3DCustomAssemblyPaths. Can specify
relative path with respective to those standard lookup directories.
• Note 2: network deployment needs configuration (code access security policy using
Caspol.exe) to enable .Net runtime load assemblies from such location – see appendix.
Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 12
 Add/Run Command in SP3D/ SM3D
Within SP3D / SM3D, choose Tools >
1 Custom Commands
Click Add to add your new command.
2 9
Provide Command ProgID as specified. 8
(AssemblyName,NameSpace.ClassName)
For our example the ProgID will be
3 S3DnetAutomationLabs,
S3DnetAutomationLabs.SampleModalCmd 2
7
Note: Prefix full Path of the DLL folder
3
for progID.
4
Provide Command name, as
SampleModalCmd in our example. 4
Choose appropriate command Priority
5 - Normal / High. We choose Normal
for our example.
Provide Command Argument as
6
required. We leave it blank for our 5
example.
7 Click OK to add it. It then appears on
the Custom Commands dialog. 6 Steps 1–7
Add
Steps 8–9
Run
To Run it, select it from Custom
8 Commands dialog and press Run. 9

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 13

Moving/Copying/Opening Projects across machines

• .NET is not like COM in many respects.
• When you open a Project in a new machine, if the 3D installation folder in the
new machine is not the same as that of the machine where the project was
originally saved, you will encounter broken references.
• This is due to the fact that the references added to the project from the
original machine are not found at those folder locations in the new machine.
• Whereas, in COM, the system goes by the registry to auto correct the DLL file
references.
• To solve this situation, You will have to open and fix the project files in the new
machine to use the corrected paths.
• Using Standard installation paths for the developers in your automation team
is a good idea to avoid this problem.
• Resolution of .Net API DLLs is not an issue for custom commands. For
Standalone EXEs, you need to follow certain guidelines (explained later).
• Installation : Your Setup Installer must only include your custom DLLs. Do not
include (i.e. re-deliver) ANY of the Smart 3D delivered API DLLs because the
Smart 3D Product delivery (ServicePack/HotFixes) is responsible for those.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 14
 Debugging the Command

Approach #1:
Attach to an already running SP3D / SM3D process.

Approach #2:
Specify Executable to start which invokes the
Command class.

(details next)

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 15

Debugging the Command

Approach #1: Attach to an
already running SP3D /
SM3D process.

Inside Visual Studio,

choose Debug

Attach
To Process,
Select the S3DHost.exe
process and press Attach.
(Taskhost.exe before
v2011). Also Click
“Select” and check
“Managed (V4.6, v4.5, v4.0)”

Inside Smart 3D, invoke

your command from
Tools > Custom
Commands as described
earlier.
Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 16
 Debugging the Command…
Approach #2: Start a new SP3D /
SM3D process from within the
debugger. (Note: you need to
add the full Core\Runtime and
GeometryTopology\Runtime
paths to your Path Environment
Variable first. (see
HKLM\Software\[Wow6432Node\]Micr
osoft\Windows\CurrentVersion\App
Paths\S3DHost.exe)

Inside Visual Studio, Project >

Project Properties

Choose the following settings and

save.

Now select Debug>Run menu

item in Visual Studio.
TIP : You can also specify the session file name in the
Invoke your command from Tools
Command line arguments field, with which the
> Custom Commands as application will start in that session file directly
described earlier. instead of the normal open session file dialog.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 17

Further improvements to Command

• Next, we enhance the command to specify some EnableUIFlags. We want
our command to be enabled to run only when there is an
ActiveConnection and NonEmptySelectSet. We do this by providing
Override implementation of the EnableUIFlags property

Public Overrides ReadOnly Property EnableUIFlags As Integer

Get
Return EnableUIFlagSettings.ActiveConnection +
EnableUIFlagSettings.NonEmptySelectSet
End Get
End Property

• With this changes, system doesn’t start our command when the
command’s EnableUIFlags property (i.e. its prerequisite expectations)
does not conform to the system state at the time of invocation of the
command.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 18
 Final code – SampleModalCmd.
Imports Ingr.SP3D.Common.Client Public Overrides Sub OnStart(ByVal commandID As Integer, ByVal argument As Object)
Imports Ingr.SP3D.Common.Client.Services MyBase.OnStart(commandID, argument)
Imports Ingr.SP3D.Common.Middle 1 3
Imports Ingr.SP3D.Common.Middle.Services
Dim oSelectSet As SelectSet = ClientServiceProvider.SelectSet

Public Class SampleModalCmd If (oSelectSet.SelectedObjects.Count = 0) Then

2
Inherits BaseModalCommand MsgBox("No Objects Selected")
Else
Public Overrides ReadOnly Property EnableUIFlags() As
Integer Dim strSelectedObjectNames As String = ""
Get For Each oObj As BusinessObject In oSelectSet.SelectedObjects
Return EnableUIFlagSettings.ActiveConnection + _ strSelectedObjectNames += vbCrLf & oObj.ToString
EnableUIFlagSettings.NonEmptySelectSet
Next
End Get 4 MsgBox(strSelectedObjectNames, , "Selected Object Names")
End Property
End If
End Sub
End Class

Inheriting from BaseModalCommand defaults the Modal property to True. Overriding

Modal Property is only needed if you want to create a Basic Non-modal Command.

Public Overrides ReadOnly Property Modal As Boolean We extend this lab little
Get to study how non-Modal,
Return False
End Get
Suspendable commands
End Property work.

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 19

Further study : Command Characteristics

Next, we study a little about Modal & Suspendable command behavior.
• If we made our Command Non-Modal, then what happens after OnStart()
method completes i.e. after the message box is shown ???
– Which command is running at this moment ?
– Which command was running at this moment, when our command was Modal ?
– what happens if we invoke and end the view zoom command ? Which command is running
now ?

• Additionally, what new behavior do you see if we make our command

Suspendable as well ???
– With our command made non-Modal and Suspendable – what happens if we invoke and end
the view zoom command ? Which command is running now ?

• It would be little more clear if we override the OnSuspend, OnResume and

OnStop methods to indicate in status bar message and / or message box to
indicate they have got invoked …

• This is left as an exercise to the class students …

Smart 3D .Net API Training – © 2018. Hexagon PPM. All Rights Reserved.
LAB – Writing Commands - 20