Persistent ID, sketch segment ID in the SOLIDWORKS API (part 4)

A persistent ID never changes. It is persistent.

So if a user changes the name of a feature, you can still get it by its ID. This makes IDs great for finding back objects.

But the SOLIDWORKS API has a lot of different IDs, which can be confusing for developers.

In this post, I will list all of them.

In this post, you’ll find

1. Inaccessible ID: models
2. Single integer IDs
   1. Components
   2. Configurations
   3. Features
   4. Sheets
   5. Edges
   6. Lights
   7. Layers
3. Double integer IDs
   1. Sketch segments
   2. Sketch hatching
4. String IDs
   1. Dimension names
5. Persistent Reference IDs for selectable objects
   1. Getting the Persistent ID from an object
   2. Tip: create your own Persistent ID object
   3. Getting an object by its persistent ID
   4. Selecting an object by its Persistent ID
6. Tracking IDs
   1. Objects that can have a Tracking ID
   2. How to assign a Tracking ID
7. An overview of all identifiers in the API
8. All blog posts in this series

A list of all identifiers in the API

This table is a complete overview of all identifiers we talk about here. I grouped them and added links to examples.

1. Inaccessible ID: models

I’ll start with the top-level model and work my way down to sketches, edges and dimensions.

The good news is that models have a unique identifier. The bad news is that we cannot access this ID through the API. I asked API Support and they confirmed this for me. Only the SOLIDWORKS developers can use this identifier.

Alternative: get a model by its path or title

Because there is no persistent ID for a model, you need to use either the file path (if the model is saved) or the title (if the model is not saved yet). SOLIDWORKS makes sure the model title is unique, but you can mess this up via the API if you really want to.

2. Single integer IDs

These object types have a single integer as their unique identifier, which is not the same as a Persistent Reference ID. It is persistent over multiple SOLIDWORKS sessions, though.

2.1. Component ID

In an assembly, we call every part or subassembly a component. In the API, we use the IComponent2 interface and you can get its unique ID via the GetID method.

Just be careful that the ID is unique only on one particular assembly level. A subassembly can use the same number for one of its components. That makes this component ID annoying to work with, in my opinion. Luckily, components also have a Persistent Reference ID.

2.2. Configuration ID

Every configuration has its own unique ID that you can get via the GetID Method. It is persistent and non-assignable.

2.3. Feature ID

Every feature also has its own unique integer that you can get via the GetID Method. It is similar to the Component ID.

2.4. Sheet ID

Since sheets are very similar to features and components, every sheet has its own unique ID, a single integer, which you can get via the GetID Method.

2.5. Edge ID

Every edge in an imported body has an ID, but unlike all other objects with an integer ID, edges actually have a GetID and a SetID method. That means you can change it.

The second difference is that this value is not saved in the model, so it is not persistent across sessions.

Edges can also have a Tracking ID, which I’ll discuss later.

2.6. Light ID

The single integer that identifies a Light in a model works identically to the objects mentioned above. For ILight, GetID is actually the only member.

2.7 Layer ID

A Layer in a drawing also has one integer. Get it via ILayer.GetID.

3. Double integer IDs

3.1 Sketch Segment ID

Sketches don’t have a unique identifier (their features do), but each sketch segment within that sketch does have an ID.

Sketch segment IDs are unique because they consist of two integers (in VBA) or longs (in C#), for example: 12-42.

But that combination of numbers is not unique within the sketch, a different element type (line, arc, etc) can use the same numbers. So you also need to combine it with the element type and the sketch name. That means you better wrap the whole thing and create a SketchSegmentID class. Here’s mine:

The API documentation does not say that the Sketch Segment ID is persistent, so I assume it is not.

3.2. Sketch hatching

A similar two-integer ID is also available for a SketchHatch, but weirdly enough, the list of sketch segment types does not include hatching.

4. String IDs

Nearly every object in SOLIDWORKS (that does not have an integer or a persistent reference ID) is identified by its name and most objects have a Name property with a getter and a setter. You can use these names for short-term actions, but don’t trust them to stay the same across SOLIDWORKS sessions because users can change these names.

4.1. Dimension names

Dimensions IDs are weird. They don’t have a number, only a name. But there are three different levels:

1. Name property
2. GetNameForSelection method
3. FullName property

If you print these, you get the following:

The user can choose the Name property. If you want to be able to select a dimension using SelectByID2, you need to use the return value of GetNameForSelection.

I don’t know when you would need the full name, maybe when you work within an assembly?

5. Persistent Reference IDs for selectable objects

Every selectable object in the SOLIDWORKS API has a Persistent Reference ID and this ID is a great way to get or set the selected objects. I use it all the time.

Each ID value is unique within a model and it generally stays the same, even across SOLIDWORKS sessions. There is a remark in the docs, though, that it can change with rebuilds, but I don’t remember that actually being a problem for my software.

5.1. Getting the Persistent ID from an object

Once you obtained a selected object with SelectionManager.GetSelectedObject6, you can get its persistent reference ID by calling ModelDocExtensions.GetPersistReference3. This method returns an object that you need to cast to a byte array (in C#, at least). You could use integers, but the values never exceed 255. An example:

176-054-000-000-003-000-000-000-255-254-255-000-000-000-000-000-255-255-001-011

Persistent ID length

This identifier is a byte array, but the array length is not the same for all object types. The most common lengths are 16 and 20 bytes, but I just found a face that used 491 bytes. In my products, I only check if the array is at least 16 bytes long, nothing else.

If you need to know the length in advance, you can call GetPersistReferenceCount3 first. Be sure to read the performance warning there, though.

5.2. Tip: create your own Persistent ID object

My advice is to never pass around persistent IDs as byte arrays, always create your own wrapper objects because the whole thing is a single object. I do the same for file paths, I don’t just pass around strings because that string can be:

• A complete path
• A file name with a file extension
• A filename without an extension

When you create a specific object for that goal (or even derived objects, like a drawing path), your list of arguments becomes clearer and you can have all error checks for paths in one place.

5.3. Getting an object by its persistent ID

When writing macros or add-ins, you will often need to store a persistent ID for later use. You can get back the object it belongs to by calling GetObjectByPersistReference3 and casting it to the correct type.

5.4. Selecting an object by its persistent ID

Once you have obtained the object by its persistent ID, you can select it again. There are two ways for this:

1. If the object has a Select method (like IFeature or IEntity), call that.
2. If not, call SelectByID2 as pass the object name and type as arguments. You can leave the position at zero. If you don’t need to set a mark, pass -1.

6. Tracking IDs

You can use Tracking IDs when you work with geometry and want to track entities across modeling operations. It only works in file types that create geometry, so parts and assemblies. Even though drawings are secretly assemblies.

An edge will not have the same persistent ID after you split the body it belongs to, but the tracking ID will stay the same. The lifetime of these IDs is also different because they are not persistent. They get reassigned after a rebuild, so you should only use them to build up geometry. This is probably the reason why I have never used them yet.

Tracking IDs are only built to be used by developers, so normal SOLIDWORKS users will never see these.

6.1. Objects that can have a Tracking ID

All the building blocks of geometry can have a tracking ID:

1. Bodies
2. Faces
3. Edges
4. Vertices
5. Loops

6.2. How to assign a Tracking ID

Assigning IDs is actually pretty straightforward:

1. Register your macro or application by calling RegisterTrackingDefinition on startup. This method returns a cookie in the form of an integer, which in my test was zero.
2. Call SetTrackingID on a body, face, edge, vertex or loop.

If you now perform an operation, like splitting a body, an edge that is split into two edges will have the same tracking ID in each body.

7. An overview of all identifiers in the API

I created a nice overview of all identifiers and other IDs in the SOLIDWORKS API.

The list includes every type that has a single-integer identifier, as well as double-integer IDs for sketch segments and persistent reference IDs. I have also included links to the API Docs and links to examples.

All blog posts in this series

1. The SOLIDWORKS Object Model + API explained
2. SOLIDWORKS API: the basics - SldWorks, ModelDoc2
3. How to work with Features 
4. Persistent ID and sketch segment ID and more
5. All identifiers in the SOLIDWORKS API
6. About return values
7. Entities and GetCorresponding
8. How to work with selections
9. How to use custom properties
10. Understanding math, MathVector and MathTransform
11. Toolbars, menus and the Command Manager
12. How to create task panes and Property Manager Pages
13. How to create your own SOLIDWORKS add-in
14. Creating add-ins with SolidDNA: the basics