How to work with Features in the SOLIDWORKS API (part 3)
If you create macros or add-ins for SOLIDWORKS, you will have to deal with features and the feature tree.
But traversing the tree can be a pain. So I’m writing down everything I know.
This post is part of a series on the SOLIDWORKS API. You can find links to the other parts at the end of the post.
In this blog post, you’ll find
- Features – IFeature
- Traversing the feature tree
- How to use subfeatures
- The FeatureManager object / IFeatureManager interface
- Feature data objects / GetDefinition
- How to edit an existing feature
- How to change the selected faces and edges in a feature
- Disable the feature tree to make your macro or add-in faster
- All blog posts in this series
1. Features – IFeature
Features are the basic building blocks within SOLIDWORKS models. They are organized in the feature tree (the official name is FeatureManager Design Tree) on the left of the SOLIDWORKS window. Each feature
Features are represented by IFeature in the API. See the interface and members docs. The most important properties are the type name, the name (that can be changed by users), the definition and the relation with its parent(s) and child / children.
Every model has its unique feature types:
- Parts have features like extrudes, fillets and revolves.
- Assemblies have components, component patterns and assembly-level cuts.
- Drawings have sheets, views and tables.
2. Traversing the feature tree
You may often have to traverse these features from top to bottom to find the feature(s) you are looking for. You do this by getting the first feature from the model, then the next feature from the previous feature. In C#:
1 2 3 4 5 6 7 | var swModel = swApp.ActiveDoc; var swFeat = swModel.IFirstFeature(); while (swFeat != null) { var name = swFeat.Name; swFeat = swFeat.IGetNextFeature } |
There are two other ways to get all features:
- After four-plus years of SOLIDWORKS API programming, I learned that the method GetFeatures also exists. It does return the features in a random order, so there’s that.
- To traverse the tree exactly how you see it in the user interface, use GetFeatureTreeRootItem2 and the ITreeControlItem interface.
2.1. What is the difference between GetNextFeature and IGetNextFeature?
This took me a while to figure out. Apparently, when two otherwise identical methods are available, the method without I returns a generic object. You then have to cast that object to a Feature. The method with I returns the specific object, so you don’t have to cast it.
So in the case of features:
- GetNextFeature returns an object
- IGetNextFeature returns a Feature
Confusingly, there are not always two copies of the same method available. Often there is only one version (always without the I) and sometimes it returns a generic object and sometimes it returns the specific type.
According to Joyce at the documentation team, SOLIDWORKS is phasing out the methods that start with I. I just hope they will be phasing out the methods that return plain objects as well.
2.2. Specific feature vs feature data
SOLIDWORKS stores feature data in two groups of objects:
- Specific feature objects
- Call IFeature.GetSpecificFeature2 to get the specific feature object, like RefPlane. Check the docs to find out if your feature type returns something or null.
- You can cast some of these specific features back to a feature. Other objects have a GetFeature method for this.
- Feature data objects, see below
- Call IFeature.GetDefinition to get the definition object, like RefPlaneFeatureData.
- Check IFeature.GetTypeName2 to find out the type, then cast it to the correct type.
- You cannot cast these objects back to a feature.
I have not found the rationale behind these two different object types (and why some have one, the other or both), so you better read the documentation.
2.3. Tricky things when traversing features
- To get the first feature, you have to call the method FirstFeature in ModelDoc2. It sounds like a property, but it is a method. GetFirstFeature would have been a better name.
- To get the next feature, you do have to call GetFirstFeature, but on the previous feature and not on the model.
- You have to get the next feature or the loop will never stop running.
- When you get a feature that is null, you know you are at the end.
- There are a few methods that will get you a certain feature directly. For all others, you just have to traverse the tree.
- Subfeatures. ARGH. They annoy me to no end.
3. How to use subfeatures
Features can have subfeatures: a extrude feature always has an underlying sketch. The same sketch can be used to create multiple extrudes, so the subfeature may not be unique.
The most reliable way of working with subfeatures is to start at the top of the tree and work your way down. You could call GetFirstSubFeature on any random feature, but I have seen it return garbage.
This example is simple enough:
Traverse features and subfeatures example
3.1. Linked lists for features?
From what I understand, each model has two lists: a list of features and a list of subfeatures. They use pointers to point from one feature to the next, and to its first subfeature. So if you traverse the tree, you follow these pointers from beginning to end. But if you would access this raw list from top to bottom, the order makes no sense.
4. The FeatureManager object / IFeatureManager interface
If you want to add features to a model, you need the FeatureManager object. It belongs to a model, so you get it as a property first.
The methods to create features are not named consistently, some start with Create, some start with Feature (which I find a pretty useless prefix) and most have an Insert (or IInsert) prefix.
Getting creating new features with the API can be a very frustrating task. Take, for example, the FeatureCut method. It takes 27 parameters! And if you pass the wrong type of parameter once, SOLIDWORKS just returns null. No error message, no help, nothing. You’re on your own.
Luckily, you can create some features from a FeatureData object. We’ll discuss that next.
5. Feature data objects / GetDefinition
Every feature needs a bunch of properties and relations to edges or faces to store how that feature is made. SOLIDWORKS does this with Feature data objects.
There is no generic feature data type, but there are 151 interfaces (as of SW2022) that end in FeatureData. To know which interface you need:
- Call IFeature.GetTypeName2, which returns a string
- See if there is a matching interface in the docs of GetTypeName2
- Call IFeature.GetDefinition, which returns a generic object
- Cast the object value to the correct type
5.1. No more endless parameters: create new features from a FeatureData object
If you are lucky, you don’t need to call a method with 20+ parameters to create a new feature. You can now create a feature data object first, set its properties, then create a feature from that object.
To create a new instance of a specific feature data object, call FeatureManager.CreateDefinition, pass along the type and cast it to the correct object type:
1 | var featureData = (TabAndSlotFeatureData) swModel.FeatureManager.CreateDefinition((int) swFeatureNameID_e.swFmTabAndSlot); |
In the last few years, SOLIDWORKS has added more and more support for this feature. In 2017, it supported only two object types, which grew to eight in 2019 and as of SW2022, it supports 31 feature types. That’s progress.
The list of feature types includes patterns, sheet metal features and a bunch of sweep features.
6. How to edit an existing feature
To edit the properties of an existing feature:
- Get the Feature object.
- Get the feature data object via IFeature.GetDefinition and cast it to the correct type (see just above).
- Change one or more of the properties. in the feature data object.
- Call Feature.ModifyDefinition.
- It needs the definition, the main model and the specific component (for assemblies) as parameters.
- If you successfully modified the feature, the method returns true.
7. How to change the selected faces and edges in a feature
If the feature you want to change has selection boxes for geometry, you need to follow these steps:
- Get the Feature object.
- Get the feature data object via IFeature.GetDefinition.
- Call the AccessSelections method (example: ISketchPatternFeatureData.AccessSelections)
- Change one or more properties. Some properties have setters, for other there are methods.
- Call Feature.ModifyDefinition to make the changes permanent.
Call ReleaseSelectionAccess after you called AccessSelections, but didn’t change anything.
8. Disable the feature tree to make your macro or add-in faster
Every time you make a change via the API, SOLIDWORKS checks if that change is allowed. It may also try to do smart stuff, like adding sketch relations.
But if you are going to do hundreds of method calls, you may only need to run those checks once, not a hundred times.
Luckily, you can disable a dozen different SOLIDWORKS features via the API. You can read about seven methods in my blog post How to improve SOLIDWORKS macro speed 10x and about a few extra methods (that I found later) in my ebook Secrets to SOLIDWORKS Performance.
All blog posts in this series
- The SOLIDWORKS Object Model + API explained
- SOLIDWORKS API: the basics - SldWorks, ModelDoc2
- How to work with Features
- Persistent ID and sketch segment ID and more
- All identifiers in the SOLIDWORKS API
- About return values
- Entities and GetCorresponding
- How to work with selections
- How to use custom properties
- Understanding math, MathVector and MathTransform
- Toolbars, menus and the Command Manager
- How to create task panes and Property Manager Pages
- How to create your own SOLIDWORKS add-in
- Creating add-ins with SolidDNA: the basics