{"id":1765,"date":"2024-01-18T10:30:00","date_gmt":"2024-01-18T00:30:00","guid":{"rendered":"https:\/\/digitalbbq.au\/?p=1765"},"modified":"2024-01-22T07:51:11","modified_gmt":"2024-01-21T21:51:11","slug":"purging-material-assets-using-the-revit-api-the-right-way","status":"publish","type":"post","link":"https:\/\/digitalbbq.au\/index.php\/2024\/01\/18\/purging-material-assets-using-the-revit-api-the-right-way\/","title":{"rendered":"Purging Material Assets Using the Revit API the Right Way"},"content":{"rendered":"\n

I was asked about a problematic Revit model with 57,000 purgeable material assets. “Just purge them”, you say, but the problem is that even using a shift+click to select the assets locked up the user’s Revit for around 30 minutes while Revit thought about its life choices.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

I had experience previously purging elements<\/a> using the performance advisor<\/a>, but that doesn’t purge materials. Harry Mattson has posted a great code snippet on boostyourbim<\/a> that shows how to purge materials using a method that checks for errors on deletion; if the code encounters an error, it rolls back the transaction. Harry points out that it takes a bit of time, as it is deleting and undeleting all the materials within the project. When I tested this code on the Snowden Towers demo project that comes with Revit 2024, it took about 15 minutes from start to finish. It doesn’t purge material assets though, so unfortunately, it doesn’t do what I’m after. <\/p>\n\n\n\n

Then I stumbled across a great post on LinkedIn by Emiliano Capasso<\/a> where he asked the question “How does the eTransmit tool do it?”<\/em> his solution is to reference eTransmitForRevitDB.dll<\/strong> <\/em>in his application and call the public method eTransmitUpgradeOMatic<\/strong><\/em> which he does like so:<\/p>\n\n\n

public<\/span> bool<\/span> Purge<\/span>(Application app, Document doc\r\n        {\r\n            eTransmitUpgradeOMatic eTransmitUpgradeOMatic = new eTransmitUpgradeOMatic(app<\/span>)<\/span>;\r\n            UpgradeFailureType result = eTransmitUpgradeOMatic.purgeUnused(doc);\r\n            if<\/span> (result == UpgradeFailureType.UpgradeSucceeded) return<\/span> true<\/span>;\r\n            else<\/span> return<\/span> false<\/span>;\r\n        })<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
The problem with Emiliano’s method is that you don’t have control over what is purged, just like when you tick the purge unused button in eTransmit, it simply purges everything.<\/p>\n\n\n\n
This led me to a quick implementation as a C# macro to help the user out in deleting their 57,000 unnamed material assets:<\/p>\n\n\n
public<\/span> void<\/span> ListAndPurgeUnusedMaterialAssets<\/span>(<\/span>)<\/span>\r\n{\r\n    UIDocument uidoc = this<\/span>.ActiveUIDocument;\r\n    Document doc = uidoc.Document;\r\n\r\n    \/\/ Get all unused elements in the document<\/span>\r\n    ISet<ElementId> unusedElementIds = doc.GetUnusedElements(new<\/span> HashSet<ElementId>());\r\n\r\n    List<string<\/span>> unusedAssetNames = new<\/span> List<string<\/span>>();\r\n    List<ElementId> unusedAssetIds = new<\/span> List<ElementId>();\r\n\r\n    \/\/ Process each unused element and filter for material assets and appearance assets<\/span>\r\n    foreach<\/span> (ElementId elementId in<\/span> unusedElementIds)\r\n    {\r\n        Element elem = doc.GetElement(elementId);\r\n        if<\/span> (elem != null<\/span>)\r\n        {\r\n            \/\/ Check if the element is an AppearanceAssetElement<\/span>\r\n            if<\/span> (elem is<\/span> AppearanceAssetElement)\r\n            {\r\n                unusedAssetNames.Add(elem.Name + \" (Appearance)\"<\/span>);\r\n                unusedAssetIds.Add(elementId);\r\n            }\r\n            \/\/ Check if the element is in the Material Assets category<\/span>\r\n            else<\/span> if<\/span> (elem.Category != null<\/span> && elem.Category.Name == \"Material Assets\"<\/span>)\r\n            {\r\n                unusedAssetNames.Add(elem.Name + \" (Material Asset)\"<\/span>);\r\n                unusedAssetIds.Add(elementId);\r\n            }\r\n        }\r\n    }\r\n\r\n    \/\/ Sort the list of names for better readability<\/span>\r\n    unusedAssetNames.Sort();\r\n\r\n    \/\/ Display the names of unused assets in a Task Dialog<\/span>\r\n    string<\/span> dialogContent = string<\/span>.Join(Environment.NewLine, unusedAssetNames);\r\n    TaskDialog.Show(\"Unused Assets\"<\/span>, dialogContent);\r\n\r\n    \/\/ Confirm with the user before deletion<\/span>\r\n    TaskDialogResult result = TaskDialog.Show(\"Confirm Deletion\"<\/span>, \"Are you sure you want to delete the following unused assets?\\n\\n\"<\/span> + dialogContent, TaskDialogCommonButtons.Yes | TaskDialogCommonButtons.No);\r\n\r\n    if<\/span> (result == TaskDialogResult.Yes)\r\n    {\r\n        \/\/ Delete the unused assets<\/span>\r\n        using<\/span> (Transaction t = new<\/span> Transaction(doc, \"Delete Unused Assets\"<\/span>))\r\n        {\r\n            t.Start();\r\n            try<\/span>\r\n            {\r\n                doc.Delete(unusedAssetIds);\r\n                t.Commit();\r\n            }\r\n            catch<\/span> (Exception ex)\r\n            {\r\n                \/\/ Handle the exception (could be element can't be deleted, etc.)<\/span>\r\n                t.RollBack();\r\n                TaskDialog.Show(\"Error\"<\/span>, \"An error occurred while deleting assets: \"<\/span> + ex.Message);\r\n            }\r\n        }\r\n    }\r\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
This macro picks up all material assets and cross-checks their element IDs with those in the unused element ID list. It’s a tidy solution that gives full control of what you remove from the model.<\/p>\n\n\n\n
\"\"
Before and after running the macro on the Snowden Towers example project<\/figcaption><\/figure>\n\n\n\n
However, this method is new in the 2024 API, which doesn’t help if you work in Revit 2023 and below. Revit 2023 still has an eTransmit tool though, and that eTransmit tool still can purge the models. <\/p>\n\n\n\n
If we take a look at the 2023 eTransmit DLL, the code calls the GetUnusedAppearances, GetUnusedMaterials, GetUnusedFamilies, GetUnusedImportCategories, GetUnusedStructures, GetUnusedSymbols, GetUnusedThermals<\/em> and GetNonDeletableUnusedElements<\/em> methods.<\/p>\n\n\n\n
These methods aren’t documented parts of the API; they are private, so that means they won’t appear in the Visual Studio object browser either. However, using a decompiler like JetBrains dotPeek<\/a> will reveal their presence.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
The problem is, if you attempt to access one of the GetUnused methods directly, you will be hit with the following error when you try to compile your code:<\/p>\n\n\n\n
\n
‘Autodesk.Revit.DB.Document’ does not contain a definition for ‘GetUnusedAppearances’ and no extension method ‘GetUnusedAppearances’ accepting a first argument of type ‘Autodesk.Revit.DB.Document’ could be found (are you missing a using directive or an assembly reference?)<\/p>\n<\/blockquote>\n\n\n\n
So how can you use them? You can invoke the method using System.Reflection like so:<\/p>\n\n\n
using<\/span> System;\r\nusing<\/span> System.Reflection;\r\nusing<\/span> Autodesk.Revit.DB;\r\n\r\npublic<\/span> void<\/span> PurgeUnusedMaterialAssets<\/span>(<\/span>)<\/span>\r\n{\r\n\tUIDocument uidoc = this<\/span>.ActiveUIDocument;\r\n\tDocument doc = uidoc.Document;\r\n\t\r\n\ttry<\/span>\r\n\t{\r\n\t\t\/\/ Get the MethodInfo for the internal method<\/span>\r\n\t\tMethodInfo getUnusedAppearancesMethod = typeof<\/span>(Document).GetMethod(\"GetUnusedAppearances\"<\/span>, BindingFlags.NonPublic | BindingFlags.Instance);\r\n\t\t\r\n\t\t\/\/ Invoke the method and get the result<\/span>\r\n\t\tif<\/span> (getUnusedAppearancesMethod != null<\/span>)\r\n\t\t{\r\n\t\t\tICollection<ElementId> unusedAppearances = (ICollection<ElementId>)getUnusedAppearancesMethod.Invoke(doc, null<\/span>);\r\n\t\t\t\r\n\t\t\t\/\/ Now you have the unused appearances and can proceed to delete them<\/span>\r\n\t\t\t\/\/ Similar reflection calls would need to be made for the other GetUnused... methods<\/span>\r\n\t\t}\r\n\t}\r\n\tcatch<\/span> (Exception ex)\r\n\t{\r\n\t\t\/\/ Handle exceptions<\/span>\r\n\t\tTaskDialog.Show(\"Error\"<\/span>, \"An error occurred: \"<\/span> + ex.Message);\r\n\t}\r\n}\r\n<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
This solution for purging model content using the API provides the same level of granularity as the new Revit 2024 API method; there are just a few extra steps to run through each GetUnused method. <\/p>\n\n\n\n
\"\"
Before and after running the macro on the RAC_basic_sample_project.rvt example project in Revit 2023<\/figcaption><\/figure>\n\n\n\n
Here is my streamlined version of the 2023 macro, which specifically looks to purge material assets:<\/p>\n\n\n
private<\/span> ICollection<ElementId> GetUnusedAssets<\/span>(Document doc, string<\/span> methodName<\/span>)<\/span>\r\n{\r\n\tMethodInfo method = typeof<\/span>(Document).GetMethod(methodName, BindingFlags.NonPublic | BindingFlags.Instance);\r\n\tif<\/span> (method != null<\/span>)\r\n\t{\r\n\t\treturn<\/span> (ICollection<ElementId>)method.Invoke(doc, null<\/span>);\r\n\t}\r\n\treturn<\/span> new<\/span> List<ElementId>();\r\n}\r\n\r\nprivate<\/span> void<\/span> AddUnusedAssets<\/span>(Document doc, ICollection<ElementId> elementIds, string<\/span> assetType, List<string<\/span>> names, List<ElementId> ids<\/span>)<\/span>\r\n{\r\n\tforeach<\/span> (var<\/span> id in<\/span> elementIds)\r\n\t{\r\n\t\tElement elem = doc.GetElement(id);\r\n\t\tif<\/span> (elem != null<\/span>)\r\n\t\t{\r\n\t\t\tnames.Add(elem.Name + \" (\"<\/span> + assetType + \")\"<\/span>);\r\n\t\t\tids.Add(id);\r\n\t\t}\r\n\t}\r\n}\r\n\r\npublic<\/span> void<\/span> PurgeUnusedMaterialAssets<\/span>(<\/span>)<\/span>\r\n{\r\n\tUIDocument uidoc = this<\/span>.ActiveUIDocument;\r\n\tDocument doc = uidoc.Document;\r\n\t\r\n\tList<string<\/span>> unusedAssetNames = new<\/span> List<string<\/span>>();\r\n\tList<ElementId> unusedAssetIds = new<\/span> List<ElementId>();\r\n\r\n\ttry<\/span>\r\n\t{\r\n\t\t\/\/ Retrieve unused assets using reflection<\/span>\r\n\t\tAddUnusedAssets(doc, GetUnusedAssets(doc, \"GetUnusedMaterials\"<\/span>), \"Material\"<\/span>, unusedAssetNames, unusedAssetIds);\r\n\t\tAddUnusedAssets(doc, GetUnusedAssets(doc, \"GetUnusedAppearances\"<\/span>), \"Appearance\"<\/span>, unusedAssetNames, unusedAssetIds);\r\n\t\tAddUnusedAssets(doc, GetUnusedAssets(doc, \"GetUnusedStructures\"<\/span>), \"Structure\"<\/span>, unusedAssetNames, unusedAssetIds);\r\n\t\tAddUnusedAssets(doc, GetUnusedAssets(doc, \"GetUnusedThermals\"<\/span>), \"Thermal\"<\/span>, unusedAssetNames, unusedAssetIds);\r\n\r\n\t\t\/\/ Sort the list of names for better readability<\/span>\r\n\t\tunusedAssetNames.Sort();\r\n\r\n\t\t\/\/ Display the list to the user and ask for confirmation before deletion<\/span>\r\n\t\tstring<\/span> dialogContent = string<\/span>.Join(Environment.NewLine, unusedAssetNames);\r\n\t\tTaskDialogResult result = TaskDialog.Show(\"Confirm Deletion\"<\/span>, \"Are you sure you want to delete the following unused assets?\\n\\n\"<\/span> + dialogContent, TaskDialogCommonButtons.Yes | TaskDialogCommonButtons.No);\r\n\r\n\t\tif<\/span> (result == TaskDialogResult.Yes)\r\n\t\t{\r\n\t\t\t\/\/ Delete the unused assets within a transaction<\/span>\r\n\t\t\tusing<\/span> (Transaction t = new<\/span> Transaction(doc, \"Delete Unused Assets\"<\/span>))\r\n\t\t\t{\r\n\t\t\t\tt.Start();\r\n\t\t\t\tdoc.Delete(unusedAssetIds);\r\n\t\t\t\tt.Commit();\r\n\t\t\t}\r\n\t\t}\r\n\t}\r\n\tcatch<\/span> (Exception ex)\r\n\t{\r\n\t\tTaskDialog.Show(\"Error\"<\/span>, \"An error occurred: \"<\/span> + ex.Message);\r\n\t}\r\n\r\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\t\t\t\n\n\n
\n
Comments<\/h3>\n
 \n
\n\t<\/a>\n\t
\n\t
It got me thinking: could I implement the same method used in eTransmit but with the ability to filter only the material assets? Turns out you can. A quick peek at the code in the DLL for Revit 2024 reveals that the purgeUnused the GetUnusedElements method<\/a>, which is a new method introduced in the 2024 API.<\/p>\n\n\n\n