Project Parameters - General Observations

[GaryOrrMBI]

Ok Guys n gals, let's talk about Project Parameters (yet again).

This is not a question, but instead just a few findings that may, hopefully, get the developers to take another look at how they handle Project Parameters via the API.

I have spent days reading through these groups (wasted a really nice weekend even) going back to discussions started in 2013 that keep getting additional comments added to them because the source problem has yet to be resolved, regardless of cases being submitted for this aspect or that.

My "wish list" item would be to simply clean up the mess so we can actually work with what is suppossed to be the most powerful aspect of Revit.

Attached is a code snippet that I have put together (2020, 2021) that actually walks us through the problems working with Project Parameters (written in VB)...

Dump it into a macro, build it and run it if desired.

Inserting it into a code block here makes it unreadable due to wrapping but I'll do it anyway:

'
Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports RVT = Autodesk.Revit
Imports RUI = Autodesk.Revit.UI
Imports RDB = Autodesk.Revit.DB
Imports RES = Autodesk.Revit.DB.ExtensibleStorage

'copy all but the first line into the attributes section preceding the Visual Studio Class
<RDB.Macros.AddInId("FB02757D-D54F-4832-AD8D-AF59AE8DFEE9")> _
<RVT.Attributes.Transaction(RVT.Attributes.TransactionMode.Manual)> _
<RVT.Attributes.Regeneration(RVT.Attributes.RegenerationOption.Manual)> _
<RVT.Attributes.Journaling(RVT.Attributes.JournalingMode.NoCommandData)> _
Partial Public Class ThisApplication

    Private Sub Module_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
	
    End Sub
	
    Private Sub Module_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Shutdown
	
    End Sub
    
    
	'This is a generic stand in for the Execute Function required in a Visual Studio application
	Public Sub ExecFunc()
		'create these as needed in Visual Studio Execute Method to pass along to the Sub and/or Function calls
		'Dim thisAppplication As RVT.ApplicationServices.Application = commandData.Application.Application
		'Dim thisUIApplication As RUI.UIApplication = commandData.Application
		'Dim thisUIDocument As RUI.UIDocument = commandData.Application.ActiveUIDocument
		'Dim thisDocument As RDB.Document = commandData.Application.ActiveUIDocument.Document
		'Dim thisDocumentView As RDB.View = commandData.View
		
		'create them in a macro with:
		Dim thisUIApplication As RUI.UIApplication = ActiveUIDocument.Application
		Dim thisApplication As RVT.ApplicationServices.Application = ActiveUIDocument.Application.Application
		Dim thisUIDocument As RUI.UIDocument = ActiveUIDocument
		Dim thisDocument As RDB.Document = ActiveUIDocument.Document
		Dim thisDocumentView As RDB.View = ActiveUIDocument.Document.ActiveView
		
		GetDocParameters(thisDocument, thisUIDocument)
	End Sub


	Private Sub GetDocParameters(thisDoc As RDB.Document, thisUIDoc As RUI.UIDocument)
		
		'start a log file:
		Dim logFile As System.IO.FileInfo = New System.IO.FileInfo(My.Computer.FileSystem.CombinePath(Me.AddinFolder, "Global Parameters.txt"))
		Dim writer As System.IO.StreamWriter = logFile.CreateText()
		writer.WriteLine("Document: " & thisDoc.Title)
		
		writer.WriteLine(vbCr & "*** Start Global Patameters ***" & vbCr)
		
		'global Parameters can only be Local (non shared) parameters... WHY???
		Dim globalParams As IList(Of RDB.ElementId) = RDB.GlobalParametersManager.GetGlobalParametersOrdered(thisDoc)
		For Each paramID As RDB.ElementId In globalParams
			Dim paraElem As RDB.GlobalParameter = DirectCast(thisDoc.GetElement(paramID), RDB.GlobalParameter)
			writer.WriteLine("Global Par Return:  " & paraElem.GetType().ToString)
			Dim paraDef As RDB.InternalDefinition = paraElem.GetDefinition
			writer.WriteLine("Internal Def Return:  " & paraDef.GetType().ToString)
			writer.WriteLine("Parameter Definition ID: " & paraDef.Id.ToString & " - Name: " & paraDef.Name)
			writer.WriteLine("Value Format Type: " & paraDef.ParameterType & "  :  " & paraDef.ParameterType.ToString)
			writer.WriteLine("Group: " & paraDef.ParameterGroup & " : " & paraDef.ParameterGroup.ToString & " : " & RDB.LabelUtils.GetLabelFor(paraDef.ParameterGroup))
			If paraElem.IsDrivenByFormula = True Then
				writer.WriteLine("Is Formula Driven: " & paraElem.IsDrivenByFormula.ToString & "  :  Formula: " & paraElem.GetFormula)
			Else
				writer.WriteLine("Is Formula Driven: " & paraElem.IsDrivenByFormula.ToString)
			End If
			
			'Why is the Value Storage type not part of the definition since that's where it is defined?
			writer.WriteLine("Value Type Return: " & paraElem.GetValue().ToString)
			
			Select Case paraElem.GetValue().GetType()
			    Case GetType(RDB.IntegerParameterValue)
					Dim paraVal As RDB.IntegerParameterValue = DirectCast(paraElem.GetValue(), RDB.IntegerParameterValue)
					writer.WriteLine("Actual Value Type: Integer:  " & paraVal.Value)
			    Case GetType(RDB.DoubleParameterValue)
					Dim paraVal As RDB.DoubleParameterValue = DirectCast(paraElem.GetValue(), RDB.DoubleParameterValue)
					writer.WriteLine("Actual Value Type: Double:  " & paraVal.Value)
			    Case GetType(RDB.ElementIdParameterValue)
					Dim paraVal As RDB.ElementIdParameterValue = DirectCast(paraElem.GetValue(), RDB.ElementIdParameterValue)
					writer.WriteLine("Actual Value Type: Element ID:  " & paraVal.Value.ToString)
			    Case GetType(RDB.StringParameterValue)
					Dim paraVal As RDB.StringParameterValue = DirectCast(paraElem.GetValue(), RDB.StringParameterValue)
					writer.WriteLine("Actual Value Type: String:  " & paraVal.Value)
			End Select
			writer.WriteLine()
		Next
		
		writer.WriteLine(vbCr & "*** Start Project Parameters ***" & vbCr)
		
		Dim paraBind As RDB.BindingMap = thisDoc.ParameterBindings
		Dim paraIter As RDB.DefinitionBindingMapIterator = paraBind.ForwardIterator()
		paraIter.Reset()
		While paraIter.MoveNext = True
			Dim thisDef As RDB.Definition = paraIter.[key]
			'they all return as InternalDefinition, even those that are actually External definitions and are declared as base defs
			writer.WriteLine("Base Definition Return:  " & thisDef.GetType().ToString)
			'Trying to cast it to an external definition always fails, 
			'regardless of how it was defined because it's already an Internal Def and the two are not compatible
			Dim extDef As RDB.ExternalDefinition = TryCast(paraIter.[key], RDB.ExternalDefinition)
			If extDef IsNot Nothing Then
				writer.WriteLine("Shared Parameter:  " & extDef.Name)
			Else
				'so we cast it specifically to Internal Definition from base definition to get it's ID
				Dim intDef As RDB.InternalDefinition = TryCast(paraIter.[key], RDB.InternalDefinition)
				writer.WriteLine("Parameter Definition ID:  " & intDef.Id.ToString & " - Name: "  & intDef.Name)
				'which allows us to map the definition to an element as if it's in use....  or is it???
				Dim sharedParam As RDB.SharedParameterElement = TryCast(thisDoc.GetElement(intdef.Id), RDB.SharedParameterElement)
				If sharedParam IsNot Nothing Then
					'but the shared parameter element still returns as an Internal Definition...
					writer.WriteLine("Shared Param Return:  " & sharedParam.GetType().ToString)
					'but the shared parameter Element seems to be derived from Base Element, not from Parameter Element 
					'so it doesn't contain appropriate methods and properties for a parameter element...
					writer.WriteLine("Shared Parameter:  " & sharedParam.Name & "  :  GUID: " & sharedParam.GuidValue.ToString)
					'one would think that we could finally cast it to an external definition using the GetDefinition method:
					'Dim extDef As RDB.ExternalDefinition = sharedParam.GetDefinition
					
					'but no... that returns an Internal Def again.
					
					'so the crux of the entire issue is the lack of implementation of ExternalDefinition within a project file...
					'compounded by not being able to get typical parameter element returns on a SharedParameterElement...
					'compounded even further by the fact that the only type of parameter that you can create is an external definition...
					'compounded even further by the fact that you can only retrieve Internal Definitions regardless of actual parameter type...
					
					'and why the heck do the definition objects not contain the storage type since that's where they're defined???
				Else
					writer.WriteLine("Parameter Type:  " & thisDef.GetType().ToString)
					writer.WriteLine("Document Parameter: " & intDef.Name & " : " & intDef.Id.ToString)
				End If
			End If
			
			'but yet, we have to go back to the base definition object to get the category 
			'since this property isn't inherited by either Internal or External definitions, 
			'yet this should be on an Element because this can actually be changed (even when importing shared)
			'of course, you can get the Parameter Type from the base definition, 
			'but you can't get the Storage type even though the definition defines it???
			writer.WriteLine("Value Format Type: " & thisDef.ParameterType & "  :  " & thisDef.ParameterType.ToString)
			writer.WriteLine("Group: " & thisDef.ParameterGroup & " : " & thisDef.ParameterGroup.ToString & "  :  " & RDB.LabelUtils.GetLabelFor(thisDef.ParameterGroup))
			'then we can determine if it's type bound or instance bound by trying to cast the type binding to one or the other...
			Dim typeBound As RDB.TypeBinding = TryCast(paraIter.Current, RDB.TypeBinding)
			If typeBound IsNot Nothing Then
				writer.WriteLine(" - Type Bound Parameter - ")
				Dim Cats As RDB.CategorySet = typeBound.Categories
				For Each cat As RDB.Category In Cats
					writer.WriteLine("Bound To:  " & cat.Name)
				Next
			Else
				Dim instBound As RDB.InstanceBinding = TryCast(paraIter.Current, RDB.InstanceBinding)
				If instBound IsNot Nothing Then
					writer.WriteLine(" - Instance Bound Parameter - ")
					Dim Cats As RDB.CategorySet = instBound.Categories
					For Each cat As RDB.Category In Cats
						writer.WriteLine("Bound To:  " & cat.Name)
					Next
				End If
			End If
			writer.WriteLine()
		End While
		
		'finalize the log file
		writer.Flush()
		writer.Close()
		System.Diagnostics.Process.Start("notepad.exe", logFile.FullName)
		
	End Sub

End Class

the comments in the snippet explain the root causes of all of our problems when trying to manipulate, or even simply query, Project Parameters within a Project File.

But they come down to these:

'they all return as InternalDefinition, even those that are actually External definitions and are declared as base defs

'Trying to cast it to an external definition always fails,

'regardless of how it was defined because it's already an Internal Def and the two are not compatible

'so we cast it specifically to Internal Definition from base definition to get it's ID

'which allows us to map the definition to an element as if it's in use.... or does it???

'but the shared parameter element still returns as an Internal Definition...

'but the shared parameter Element seems to be derived from Base Element, not from Parameter Element

'so it doesn't contain appropriate methods and properties for a parameter element...

'one would think that we could finally cast it to an external definition using the GetDefinition method:

'but no... that returns an Internal Def again.

'so the crux of the entire issue is the lack of implementation of ExternalDefinition within a project file...
'compounded by not being able to get typical parameter element returns on a SharedParameterElement...
'compounded even further by the fact that the only type of parameter that you can create is an external definition...
'compounded even further by the fact that you can only retrieve Internal Definitions regardless of actual parameter type...

'and why the heck do the definition objects not contain the storage type since that's where they're defined???

'but yet, we have to go back to the base definition object to get the category
'since this property isn't inherited by either Internal or External definitions,
'yet this should be on an Element because this can actually be changed (even when importing shared)
'of course, you can get the Parameter Type from the base definition,
'but you can't get the Storage type even though the definition defines it???

Those are my findings, Am I wrong? Am I missing something?

[RPTHOMAS108]

This came up the other day related to getting the tooltip description. I suppose since they were created the terms are now often misunderstood i.e. in terms of what the developers of the API originally meant vs how developers now actually understand them. However the the reality is quite simple:

The only things counted as ExternalDefinitions are the things you create in a shared parameter file. An ExternalDefinition is not inserted into a Revit document an ExternalDefinition is used to create an InternalDefinition in a Revit document (that has always been my understanding). There are some InternalDefinitions that are built in (those have BuiltInParameter <> ElementID.InvalidElementId). There are some which can't be created by the API (non-shared project parameters).

This was to mirror UI functionality.  Could you imagine it would be so easy to create a shared parameter with only a GUID, Name, and ParameterType.

ParameterElement and SharedParameterElement can be used to distinguish between those that are non-shared project parameters, those that are shared and those that are built-in. They all still have InternalDefinitions. Before they were introduced you would have had to look at an actual parameter on an element or a FamilyParameter in a family to distinguish (to see .IsShared & .Definition.BuiltInParameter). Made working with DMUs harder because you had to find an example of an Element with the parameter you wanted to monitor.

[GaryOrrMBI]

I am not finding the .IsShared property on either the base Definition object or the .InternalDefinition object when retrieved from the BindingMap of a Project File.

Dump the snippet into a macro and, still in the editor, go down to where I iterate through the BindingMap and check the available properties for thisDef and intDef.

As to mimicking the UI, well the UI clearly shows a difference between non shared parameters and Shared parameters, so it would seem, to me at least, that there would be an easy method to differentiate between the two via the API if that was the intent...

[RPTHOMAS108]

No I was wrong isShared is on Parameter but you can go all the way back to 2011 pdf guide to see ExternalDefinitions are only for 'External' DefinitionFiles and things haven't changed much in that respect since then.

Shall we also just summarise the various types of parameters that exist (excluding global parameters):

A) Built-in

B) Bound to categories in project via InstanceBindings or TypeBindings (see Document.ParameterBindings)

         Shared from SP file or Non-Shared (defined in project)

C) Loaded with family

         Shared from SP file or Non-Shared (defined in family)

This gives us strategy for how we identify them and what properties of each we can find i.e. which related class objects we need to use. Some items such as tooltip are unreachable however.

[GaryOrrMBI]

I have also run into a few conflicts when looking up a BuiltInParameter...

I run a piece of code that gets the parameters for objects and determines their source. But, when running it on a door (of any family and type) it returned some unexpected results for the expected BuiltInParameter. In this example the "Width Parameter" was returned as the BuiltInParameter "CASEWORK_WIDTH"... 

There were plenty of other such occurrences so I parsed the BuiltInParameter Enumeration and found duplicate entries such as these:

using this:

        writer.WriteLine(vbCr & "*** Built In Parameters ***" & vbCr)
        For Each item As RDB.BuiltInParameter In System.Enum.GetValues(GetType(RDB.BuiltInParameter))
            Dim itemStr As String = item.ToString
            Dim displayStr As String = System.Enum.GetName(GetType(RDB.BuiltInParameter), item)
            If itemStr = displayStr Then
                writer.WriteLine(item & "  Name:  " & itemStr)
            Else
                writer.WriteLine(item & "  Name:  " & itemStr & vbCr & vbTab & "** Display Name: " & displayStr)
            End If
        Next

so then I did this: 

writer.WriteLine(vbCr & "*** Built In Parameters ***" & vbCr)
For Each itemStr As String In System.Enum.GetNames(GetType(RDB.BuiltInParameter))
Dim actualStr As String = System.Enum.Parse(GetType(RDB.BuiltInParameter), itemStr).ToString
If actualStr = itemStr Then
writer.WriteLine("Display Name: " & itemStr)
Else
writer.WriteLine("Display Name: " & itemStr & vbCr & vbTab & "** Actual Name: " & actualStr)
End If
Next

and found this:

...

[GaryOrrMBI]

---

@RPTHOMAS108 wrote:

No I was wrong isShared is on Parameter but you can go all the way back to 2011 to see ExternalDefinitions are only for 'External' DefinitionFiles and things haven't changed much in that respect since then.

Shall we also just summarise the various types of parameters that exist (excluding global parameters):

A) Built-in

B) Bound to categories in project via InstanceBindings or TypeBindings (see Document.ParameterBindings)

         Shared from SP file or Non-Shared (defined in project)

C) Loaded with family

         Shared from SP file or Non-Shared (defined in family)

---

I don't know that I would agree with that... I think that I would reverse the inners and outers and separate them a bit further:

1) yes, built In Parameters.

2) Parameters within the Project File that originated as a Shared Parameter -  bound to either Types or Instances

3) Parameters within the Project File that are Non-Shared (they exist only here) - bound to either Types or Instances

4) Family Parameters (can either be Shared which get added to the Project Parameters or Non Shared which do not get added to the Project Parameters)

I make points 2 and 3 based upon the UI and user perception when adding or modifying a Project Parameter:

[RPTHOMAS108]

Yes the BuiltInParameters enum has a lot of cases where different name is used for same integer object. However usually they refer to the same function / type of information e.g. the classic example of:

ALL_MODEL_MARK = -1001203

DOOR_NUMBER = -1001203

I don't think it would be possible to have two of the same on single element. Therefore usually not an issue to only care that the integer is correct. Is there a case where that causes an issue for you?

I think I see Parameters as either being bound to categories in the project or coming from families. You can have the same shared parameter bound to a category in project and also at the same time specifically added to a family (title block value pass through works this way).  Likewise to have visibility filters based on parameters you also often need to add same shared parameter item to project as already exists in family (or just in project). Not seen in project for that purpose otherwise, needs a category uniformity for that visibility filtering function.

[GaryOrrMBI]

No, the duplicates haven't caused me an issue as of yet. I'm simply exploring all aspects of Parameters before trying to build a function that I have in mind. At first I thought I was messing something up somewhere when I retrieved the BuiltInParameter "Width" from a door (and several other elements as well) so I started to explore a bit and found this.

Everyone always says "use the BuiltInParameter or the GUID or the Element ID when retrieving Parameters, not the name because there could be multiple returns"... But, if I'm trying to, say, match a couple of items up based on a parameter that I know the name of but not which one of the few thousand BuiltInParameters it was defined from, or even if it is a BuiltInParameter... so first I experimented with returning parameters from various objects to find methods of determining the source of the definition, which led me to that particular find.

As to the perception of association...

I always look at what a thing is, then try to discover what I can do with it in addition to what has already been done with it, thus my order 😉

I think it's especially important to manage some kind of separation, especially since you can only create new Shared Parameters for Project Parameters, not non-shared (which is an issue in and of itself, yes, I know the work around, create one in a shared parameters file, then bring it in but, I don't believe that someone should have to do that for a parameter that does not require tagging).

it seems that expanding ParameterElement and SharedParameterElement to encompass all of the methods and properties that are available from a parameter attached to an element would simplify a lot of things as well.

There wouldn't be nearly as many hoops to jump through if an ExternalDefinition stayed an ExternalDefinition once it is incorporated into a family or document to help differentiate between them by the ability to cast them to one or the other (instead of adding them to a family or an instance of something so you can then get the parameter back from that family or instance to get what you need from it).

Truth is, if you're coming at it from an entity perspective there are all kinds of ways to get there, parameter.ID can differentiate between builtin or user defined by it being a negative value or a positive value, in conjunction with .IsShared and GUID to split out the shared parameters... but, again, that requires attaching the parameter to something so you can then pull it back off so you can get the information about the definition because it isn't part of the definition, yet it IS the definition...

lost and confused...

[RPTHOMAS108]

It is as far as I know completely impossible to create a non-shared project parameter with the API or with any non-ui work around, with a definitions file it would be shared still.

Regarding the objects these often are extensions/mirrors/wrappers (call them what you will) to native versions so not 100% conceived with API developers in mind in terms of which ones contain which properties. Helps to also look at the history to understand the differences:

In the project we only had Bindings and Definitions to start with and Family Parameters in the Family.

You can count the Bindings now and see there is probably a mismatch in count between those and Shared/ParameterElements . SharedParameterElements and ParameterElements were added as helpers but they don't really add anything you couldn't before already work out with a long way around. You could always remove bindings as you can now delete these new objects but what remains remains in this project or potentially elsewhere. How does a project know if another one contains that SP or not. This was the reason for those kind of immutable things. Once it is out there it is out there. 

There is only one use for Element.LookupParameter and that is for when it is a non-shared project or family parameter and also isn't built-in (then it only has name as a key). When I'm storing a key for a parameter I'll often create an enum to store where it came from but in a way you don't need this if you have an order of priority i.e.:

1) Integer.TryParse (Is it BIP)

     1a) Enum.IsDefined with BuiltInParameter (if false can't use numbers for names so something is wrong here).

2) GUID.TryParse, unless some odd person making parameters uses GUID strings for names. You can't start a param name with a number so if they are doing this they will fail at some point.

3) Name

Regarding the ExternalDefinition I can see the convenience of that and the mystery of the tooltip description is that it must exist somewhere even though not fully exposed via API. Tooltip was a later addition so probably exists elsewhere on newly created object internally. This is more about how different parts of the same thing get stored in Revit perhaps in different places and then how those are recombined and exposed via API.  Things generally work on a shallow object record basis only. With deeper interrogation information gathering having performance cost. So I expect they have to weigh up that in terms of what a user commonly needs. Does everyone that looks at a definition need to know it's origin?

There is a history to these things also it is over a decade old and started out elsewhere. There has been various conversations about rationalising parameters etc. over the years I don't see it happening. They don't want to risk breaking the egg to make an omelette when no end user is asking for an omelette.

There is this saying in the construction industry it seems: 'We are where we are' closely related to 'It is what it is'

[GaryOrrMBI]

I remember one other saying from my construction days: "My goal is to work myself out of a job"... IE, when I have done my part, my part will be done...

I really do understand many of your points. I also know that many respect your knowledge (myself included) and your insights are greatly appreciated. But I'm one of those that always feel the need to make improvements how and where I can, thus the reason for this post as it is now the only method that I have to reach the developers at Autodesk (I haven't been an ADN member for years now as my career path took a sidetrack for a while and, to be honest, I never really intended to get back into this but, Stuff happens right?)

So... my hope would be that the developers (in order of priority from my perspective):

1) Rewrite ParameterElement and SharedParameterElement to be upstream wrappers of Parameter, complete with all of the appropriate Methods and Properties of each (as opposed to it's current form of being a wrapper on Element as there are only one or two properties and methods that actually apply to a parameter which are the couple of properties added by the wrapper).

2) Integrate External Definition within the document environment (and family as well, I haven't explored that much yet but one of your comments indicates that those are stored as Internal as well). This would provide simple methods of finding the source without jumping through a lot of hoops. Or modify the Internal Definition to be more like the Definition object that is returned from an actual Parameter. Either way, the result would be a much more straightforward path.

These two things (well 3 if you separate the Parameter wrappers into two points, but I see them as going hand in hand) would solve the recurring posts on this subject that all result in jumping through a lot of hoops to do what should be a simple thing.

They would make it a relatively simple thing to go into your Project, discover that you have two Parameters (or even three or more for that matter) with the same name but different definitions and/or storage types or whatever other problem the duplicates might be causing, decide which one (by finding the source and type of parameter and whatever other criteria you may have) you want to keep and start the process of gathering data and transferring it to the appropriate Parameter, then go through and remove the ones that you don't want confusing the end users.

Those Shared Parameters that come in from Families but were perhaps defined from a different Shared Param file, maybe by different companies, but coincidentally have the same name could be tracked down and resolved, so, I guess what I'm saying is that we have been asking for that omelet for years now in one way or another 🙂

-G