Advanced API: Storing Data in Models Using Attributes

Blog 5.30.2012 2 Comments

SolidWorks API attributes
An attribute is a container of user-defined data that a SolidWorks API programmer can store on a SolidWorks model or entity. Like custom properties, they are saved with the model. Attributes, however, have three notable advantages over custom properties:

  • A single attribute can contain an unlimited number of parameters of different types
  • Attributes can be associated with specific geometry (e.g., faces, edges, vertices) and therefore traversed
  • Attributes can be visible to the end user OR hidden

Programming attributes involves three interfaces: IAttributeDef, IAttribute, and IParameter. Here are the basic steps for creating an attribute.

  1. Define the attribute using ISldWorks::DefineAttribute, which returns the IAttributeDef object. One argument is required—a unique definition name.
  2. Add any number of parameters to the definition using IAttributeDef::AddParameter.
  3. Register the definition using IAttributeDef::Register.
  4. Create an instance of the definition on the model or on a model entity using IAttributeDef::CreateInstance5, which returns an IAttribute object. If the attribute is being created on the model, use Nothing for the second argument, otherwise specify the entity (e.g., an IFace2 or IEdge object).
  5. Optionally, get the parameters for that attribute using IAttribute::GetParameter.
  6. Optionally, get or set the parameter value using IParameter::GetDoubleValue / SetDoubleValue2 (if the parameter is of type double) or IParameter::GetStringValue / SetStringValue2 (if the parameter is of type string).

If you wanted to add an attribute called “MyAtt” containing a double value of 0.1 to a selected face, your code would look like this:

Dim swApp As SldWorks.SldWorks
Dim swModel As SldWorks.ModelDoc2
Dim swSelMgr As SldWorks.SelectionMgr
Dim swFace As SldWorks.Face2
Dim swAttDef As SldWorks.AttributeDef
Dim swAtt As SldWorks.Attribute
Dim swParam As SldWorks.Parameter
Sub main()
    Set swApp = Application.SldWorks
    Set swModel = swApp.ActiveDoc
    Set swSelMgr = swModel.SelectionManager
    Set swFace = swSelMgr.GetSelectedObject6(1, -1)
    Set swAttDef = swApp.DefineAttribute("template")
    swAttDef.AddParameter "area", swParamTypeDouble, 0.1, 0
    swAttDef.Register
    Set swAtt = swAttDef.CreateInstance5(swModel, swFace, "MyAtt", 0, swAllConfiguration)
    Set swParam = swAtt.GetParameter("area")
    swParam.SetDoubleValue2 swFace.GetArea, swAllConfiguration, Empty
End Sub

While this may seem a little complicated, keep in mind the tremendous versatility available to us. If we want, we could keep using our attribute definition over and over as we create multiple instances on different faces. Multiple instances of the same attribute definition can be created on the same entity, however each instance must have its own name.

Reading the values from existing attributes can be done many different ways. Since an attribute instance is a feature, it can be traversed using normal feature traversal techniques, accessed directly using FeatureByName (available in IPartDoc, IAssemblyDoc, and IDrawingDoc), or, if it is selected in the FeatureManager tree, it can be accessed using ISelectionManager::GetSelectedObject6. Once the IFeature object is obtained, use IFeature::GetSpecificFeature2 to get the actual IAttribute object.

If the attribute is associated with a particular piece of geometry, the aforementioned techniques might not be helpful. Instead, while you traverse your geometry, you can use IEntity::FindAttribute to determine if an attribute of a particular name is present. In this case, be sure to call IAttribute::GetEntityState to make sure that the instance is valid.

In our Macro Library we have to two great examples that demonstrate how to add, find, and read attributes:
Add and read attributes on document (Free)
Add or find attributes on all faces (Premium)

Finally, some words of caution/advice when using attributes:

  • It is not recommended that you use attributes solely for located entities that, for example, need to be mated. There are far better techniques for locating topology / geometry. Use attributes only store data within the model.
  • Attributes can be named anything a programmer desires. However, since other third party applications can use attributes, it is recommended that add-in programmers name their attributes with a unique three character prefix. Send attribute prefix requests to apisupport@solidworks.com.
  • Use double parameters instead of integer parameters, because there is no way to get or set the latter. (See the API Help article IAttributeDef::AddParameter.) Also note that only double parameters can have a default value set. For string values, use Empty in the third argument of IAttributeDef::AddParameter and set the value later using IParameter::SetStringValue2.
  • Once an attribute definition is registered, it cannot be modified. For example, you cannot add, remove, or change the names of parameters. Check the return value of IAttributeDef::Register to see if registry is failing. You may have already registered a definition with that name.
  • The only time attributes can be added to a model while a PropertyManager page is open is in the AfterClose event, since adding an attribute is adding a feature, and adding a feature while a PMP is active is not allowed (or at least will typically not work).
  • If you are running into errors like Run-time error 91 but aren’t sure why, try restarting SolidWorks to give yourself a clean slate in terms of memory.

That concludes our look at attributes. Thanks for reading!

Want to keep up with new CADSharp.com content? Sign up for our newsletter.


2 Comments

  1. t_koopstra

    Hi,

    I’ve got a part with an attribute from an other party. Is it possible to check which parameters are in this attribute? For the .getparameter option you need the name of the parameter, and I don’t know the name of the parameter(s) included.

    I would expect some option like .getallparameters and to use this in a loop and print those values in the debug.print. But I can’t figure out how to do this.

    Thanks in advance,

    Timo

    • Hi, you are correct that it is not possible to get attribute parameters without knowing the name in advance. Whether this is intentional I do know. I would recommend emailing SolidWorks API support about this.

Questions and Comments

You must be logged in to post a comment.