kimminsung/ParaWiki
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases Wiki Activity

Revit API Developer's Guide MD 변환본 추가 (368 페이지)

Browse Source 
Revit 2026 공식 Developer's Guide HTML → MD 변환.
Output/revit-api-guide/에 8개 카테고리 폴더로 정리.
CLAUDE.md에 참조 규칙 추가, .gitignore에 .scratch/ 제외.

소스: help.autodesk.com/view/RVT/2026/ENU (CC BY-NC-SA 3.0)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
minsung
2026-04-14 17:33:42 +09:00
parent 3bd01e31c9
commit b4a8714793
370 changed files with 28908 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Add_in_Dependency_Isolation_html.md Normal file
View File

@@ -0,0 +1,89 @@
# Add-in Dependency Isolation
# Add-in Dependency Isolation
A new option has been introduced for add-in developers to be able to run add-ins in a separate Assembly load context from Revit and from other add-ins.
* This will isolate the add-in from dependencies and dependent assemblies loaded by Revit or by other add-ins in the same session.
* This should reduce or eliminate assembly version conflicts seen in Revit sessions due to conflicting add-ins.
Adoption of this feature is optional for this release. Developers can set the option "UseRevitContext" to false per add-in manifest (it applies to all registered add-ins in the given manifest). The default for add-ins where this is not specified is "true".
If the option is used, all add-ins loaded from the same folder will be placed into the same external context. Add-ins from different folder installation locations will go to different contexts.
Developers can also optionally set a custom ContextName for the add-in. If this is used, add-ins from different folder locations that use the same context name will be loaded into the same context.
Add-in developers are advised to check the dependencies that they load are correct and complete for their own add-in as they may no longer be able to rely on Revit or another add-in loading the dependency prior to the add-in being loaded.
Sample use of the new manifest flags:
<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
<AddIn Type="DBApplication">
<Name>SampleApplication</Name>
<FullClassName>SampleApplication.Application</FullClassName>
<Assembly>SampleApplication.dll</Assembly>
<ClientId>C96B32A3-98C6-4B47-99DA-562E64689C6F</ClientId>
<VendorId>Autodesk</VendorId>
</AddIn>
<ManifestSettings>
<UseRevitContext>False</UseRevitContext>
<ContextName>SampleContextName</ContextName>
</ManifestSettings>
</RevitAddIns>
In the RevitAddInUtility API, the new properties:
* RevitAddInManifestSettings.UseRevitContext
* RevitAddInManifestSettings.ContextName provide read and write access to these settings, while the new property:
* RevitAddInManifest.ManifestSettings provides access to the overall settings for a manifest.
## Add-in Management API additions
With the introduction of user control for loaded add-ins, new APIs have been added to facilitate the management of add-in settings in and out of Revit. These APIs are a part of RevitAddinUtility.dll and documented in RevitAddinUtility.chm.
The class:
* Autodesk.RevitAddIns.Manager.AddInsManagerSettings contains the settings to enable/disable loading of add-ins registered with Revit. It offers the following members:
* static AddInsManagerSettings.Get() - gets the settings for the current Windows user.
* AddInsManagerSettings.GetAllAddInItemSettings() - returns all Add-in settings.
* AddInsManagerSettings.GetAddInItemSettings() - returns a particular Add-in settings object for the given id.
* AddInsManagerSettings.CreateAddInItemSettings() - creates a new Add-in settings object.
* AddInsManagerSettings.Save() - saves any changes made.
* AddInsManagerSettings.DisableAllAddIns - used to disable (or enable) loading of all Add-ins (for those that are permitted to be disabled).
The class:
* Autodesk.RevitAddIns.Manager.AddInItemSettings represents the settings of an Add-in registered with Revit. It offers the following properties:
* AddInItemSettings.Disabled - used to disable (or enable) loading of a particular add-in in the next Revit session.
* AddInItemSettings.GUID - the add-in id.
* AddInItemSettings.Name - the add-in name.
* AddInItemSettings.Vendor - the add-in vendor.
* AddInItemSettings.LoadTime - the time taken to load the add-in the last time it loaded.
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

198
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Add_in_Registration_html.md Normal file
View File

@@ -0,0 +1,198 @@
# Add-in Registration
# Add-in Registration
External commands and external applications need to be registered in order to appear inside Revit. They can be registered by adding them to a .addin manifest file.
The order that external commands and applications are listed in Revit is determined by the order in which they are read in when Revit starts up.
## Manifest Files
Revit API applications are registered with Revit via a .addin manifest file. Manifest files are read automatically by Revit when they are placed in one of two locations on a user's system:
In a non-user-specific location in "application data":
* C:\ProgramData\Autodesk\Revit\Addins\Revit 2026\
In a user-specific location in "application data":
* C:\Users<user>\AppData\Roaming\Autodesk\Revit\Addins\Revit 2026\
All files named .addin in these locations will be read and processed by Revit during startup. All of the files in both the user-specific location and the all users location are considered together and loaded in alphabetical order. If an all users manifest file shares the same name with a user-specific manifest file, the all users manifest file is ignored. Within each manifest file, the external commands and external applications are loaded in the order in which they are listed.
A basic file adding one ExternalCommand looks like this:
**Code Region 3-9: Manifest .addin ExternalCommand**
---
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Command">
<Assembly>c:\MyProgram\MyProgram.dll</Assembly>
<AddInId>76eb700a-2c85-4888-a78d-31429ecae9ed</AddInId>
<FullClassName>Revit.Samples.SampleCommand</FullClassName>
<Text>Sample command</Text>
<VendorId>ADSK</VendorId>
<VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
<VisibilityMode>NotVisibleInFamily</VisibilityMode>
<Discipline>Structure</Discipline>
<Discipline>Architecture</Discipline>
<AvailabilityClassName>Revit.Samples.SampleAccessibilityCheck</AvailabilityClassName>
<LongDescription>
This is the long description for my command.
This is another descriptive paragraph, with notes about how to use the command properly.
</LongDescription>
<TooltipImage>c:\MyProgram\Autodesk.png</TooltipImage>
<LargeImage>c:\MyProgram\MyProgramIcon.png</LargeImage>
</AddIn>
</RevitAddIns>
A basic file adding one ExternalApplication looks like this:
**Code Region 3-10: Manifest .addin ExternalApplication**
---
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>SampleApplication</Name>
<Assembly>c:\MyProgram\MyProgram.dll</Assembly>
<AddInId>604B1052-F742-4951-8576-C261D1993107</AddInId>
<FullClassName>Revit.Samples.SampleApplication</FullClassName>
<VendorId>ADSK</VendorId>
<VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
</AddIn>
</RevitAddIns>
A basic file adding one DB-level External Application looks like this:
**Code Region: Manifest .addin ExternalDBApplication**
---
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="DBApplication">
<Assembly>c:\MyDBLevelApplication\MyDBLevelApplication.dll</Assembly>
<AddInId>DA3D570A-1AB3-4a4b-B09F-8C15DFEC6BF0</AddInId>
<FullClassName>MyCompany.MyDBLevelAddIn</FullClassName>
<Name>My DB-Level AddIn</Name>
<VendorId>ADSK</VendorId>
<VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
</AddIn>
</RevitAddIns>
Multiple AddIn elements may be provided in a single manifest file.
The following table describes the available XML tags:
**Tag** | **Description**
---|---
Assembly | The full path to the add-in assembly file. Required for all ExternalCommands and ExternalApplications.
FullClassName | The full name of the class in the assembly file which implements IExternalCommand or IExternalApplication. Required for all ExternalCommands and ExternalApplications.
AddInId | A GUID which represents the id of this particular application. AddInIds must be unique for a given session of Revit. Autodesk recommends you generate a unique GUID for each registered application or command. Required for all ExternalCommands and ExternalApplications.
Name | The name of application. Required for ExternalApplications only.
Text | The name of the button. Optional; use this tag for ExternalCommands only. The default is "External Tool".
VendorId | A unique vendor identifier that may be used by some operations in Revit (such as identification of extensible storage). This must be unique, and thus we recommend to use reversed version of your domain name, for example, com.autodesk or uk.co.autodesk.
VendorDescription | Description containing vendor's legal name and/or other pertinent information. Optional.
Description | Short description of the command, will be used as the button tooltip. Optional; use this tag for ExternalCommands only. The default is a tooltip with just the command text.
VisibilityMode | The modes in which the external command will be visible. Multiple values may be set for this option. Optional; use this tag for ExternalCommands only. The default is to display the command in all modes, including when there is no active document. Previously written external commands which need to run against the active document should either be modified to ensure that the code deals with invocation of the command when there is no active document, or apply the NotVisibleWhenNoActiveDocument mode. See table below for more information.
Discipline | The disciplines in which the external command will be visible. Multiple values may be set for this option. Optional; use this tag for ExternalCommands only. The default is to display the command in all disciplines. If any specific disciplines are listed, the command will only be visible in those disciplines. See table below for more information.
AvailabilityClassName | The full name of the class in the assembly file which implemented IExternalCommandAvailability. This class allows the command button to be selectively grayed out depending on context. Optional; use this tag for ExternalCommands only. The default is a command that is available whenever it is visible.
LargeImage | The icon to use for the button in the External Tools pulldown menu. Optional; use this tag for ExternalCommands only. The default is to show a button without an icon.
SmallImage | The icon to use if the button is promoted to the Quick Access Toolbar. Optional; use this tag for ExternalCommands only. The default is to show a Quick Access Toolbar button without an icon, which can be confusing to users.
LongDescription | Long description of the command, will be used as part of the button extended tooltip, shown when the mouse hovers over the command for a longer amount of time. Optional; use this tag for ExternalCommands only. If this property and TooltipImage are not supplied, the button will not have an extended tooltip.
TooltipImage | An image file to show as a part of the button extended tooltip, shown when the mouse hovers over the command for a longer amount of time. Optional; use this tag for ExternalCommands only. If this property and TooltipImage are not supplied, the button will not have an extended tooltip.
LanguageType | Localization setting for Text, Description, LargeImage, LongDescription, and TooltipImage of external tools buttons. Revit will load the resource values from the specified language resource dll. The value can be one of the eleven languages supported by Revit. If no LanguageType is specified, the language resource which the current session of Revit is using will be automatically loaded. For more details see the section on Localization.
AllowLoadIntoExistingSession | The flag for loading permission. Set to false to prevent Revit from automatically loading addins in a newly added .addin manifest file without restarting. Optional. By default. Revit will automatically load addins from newly added .addin manifest files without restarting Revit.
**Table 3: VisibilityMode Members**
**Member Name** | **Description**
---|---
AlwaysVisible | The command is available in all possible modes supported by the Revit API.
NotVisibleInProject | The command is invisible when there is a project document active.
NotVisibleInFamily | The command is invisible when there is a family document active.
NotVisibleWhenNoActiveDocument | The command is invisible when there is no active document.
**Table 4: Discipline Members**
**Member Name** | **Description**
---|---
Any | The command is available in all possible disciplines supported by the Revit API.
Architecture | The command is visible in Autodesk Revit Architecture.
Structure | The command is visible in Autodesk Revit Structure.
StructuralAnalysis | The command is visible when the Structural Analysis discipline editing tools are available.
MassingAndSite | The command is visible when the Massing and Site discipline editing tools are available.
EnergyAnalysis | The command is visible when Energy Analysis discipline editing tools are available.
Mechanical | The command is visible when the Mechanical discipline editing tools are available, e.g., in Autodesk Revit MEP.
Electrical | The command is visible when the Electrical discipline editing tools are available, e.g., in Autodesk Revit MEP.
Piping | The command is visible when the Piping discipline editing tools are available, e.g., in Autodesk Revit MEP.
MechanicalAnalysis | The command is visible when the Mechanical Analysis discipline editing tools are available.
PipingAnalysis | The command is visible when the Piping Analysis discipline editing tools are available.
ElectricalAnalysis | The command is visible when the Electrical Analysis discipline editing tools are available.
## .NET Add-in Utility for manifest files
The .NET utility DLL RevitAddInUtility.dll offers a dedicated API capable of reading, writing and modifying Revit Add-In manifest files. It is intended for use from product installers and scripts. Consult the API documentation in the RevitAddInUtility.chm help file in the SDK installation folder.
**Code Region 3-11: Creating and editing a manifest file**
---
public void ManifestFile()
{
//create a new addin manifest
RevitAddInManifest Manifest = new RevitAddInManifest();
//create an external command
RevitAddInCommand command1 = new RevitAddInCommand("full path\\assemblyName.dll",
Guid.NewGuid(), "namespace.className", "ADSK");
command1.Description = "description";
command1.Text = "display text";
// this command only visible in Revit MEP, Structure, and only visible
// in Project document or when no document at all
command1.Discipline = Discipline.Mechanical | Discipline.Electrical |
Discipline.Piping | Discipline.Structure;
command1.VisibilityMode = VisibilityMode.NotVisibleInFamily;
//create an external application
RevitAddInApplication application1 = new RevitAddInApplication("appName",
"full path\\assemblyName.dll", Guid.NewGuid(), "namespace.className", "ADSK");
//add both command(s) and application(s) into manifest
Manifest.AddInCommands.Add(command1);
Manifest.AddInApplications.Add(application1);
//save manifest to a file
RevitProduct revitProduct1 = RevitProductUtility.GetAllInstalledRevitProducts()[0];
Manifest.SaveAs(revitProduct1.AllUsersAddInFolder + "\\RevitAddInUtilitySample.addin");
}
**Code Region 3-12: Reading an existing manifest file**
---
public void ReadManifest()
{
RevitProduct revitProduct1 = RevitProductUtility.GetAllInstalledRevitProducts()[0];
RevitAddInManifest revitAddInManifest =
Autodesk.RevitAddIns.AddInManifestUtility.GetRevitAddInManifest(
revitProduct1.AllUsersAddInFolder + "\\RevitAddInUtilitySample.addin");
}
## Access to add-in data paths
Autodesk.Revit.ApplicationServices.Application.CurrentUsersAddinsDataFolderPath provides access to add-in data folder for the current Revit version and current user (such as %appdata%\Autodesk\Revit\Autodesk Revit 2026\AddinsData)
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

61
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Attributes_html.md Normal file
View File

@@ -0,0 +1,61 @@
# Attributes
# Attributes
The Revit API provides several attributes for configuring ExternalCommand and ExternalApplication behavior.
### TransactionAttribute
The custom attribute Autodesk.Revit.Attributes.TransactionMode must be applied to your implementation class of the IExternalCommand interface to control transaction behavior for the external command. There is no default for this option. This mode controls how the API framework expects transactions to be used when the command is invoked. The supported values are:
* _TransactionMode.Manual_ \- Revit will not create a transaction (but it will create an outer transaction group to roll back all changes if the external command returns a failure). Instead, you may use combinations of Transactions, SubTransactions, and TransactionGroups as you please. You will have to follow all rules regarding use of transactions and related classes. You will have to give your transactions names which will then appear in the Undo menu. Revit will check that all transactions (also groups and sub-transactions) are properly closed upon return from an external command. If not, Revit will discard all changes made to the model.
* _TransactionMode.ReadOnly_ \- No transaction (nor group) will be created, and no transaction may be created for the lifetime of the command. The External Command may only use methods that read from the model. Exceptions will be thrown if the command either tries to start a transaction (or group) or attempts to write to the model.
In either mode, the TransactionMode applies only to the active document. You may open other documents during the course of the command, and you may have complete control over the creation and use of Transactions, SubTransactions, and TransactionGroups on those other documents (even in ReadOnly mode).
For example, to set an external command to use manual transaction mode:
**Code Region 3-18: TransactionAttribute**
---
[Transaction(TransactionMode.Manual)]
public class CommandTransaction : IExternalCommand
{
public Result Execute(
ExternalCommandData commandData,
ref string message, Autodesk.Revit.DB.ElementSet elements)
{
// Command implementation, which modifies the active document directly
// after starting a new transaction
return Result.Succeeded;
}
}
See [Transactions](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Transactions_html.html).
### JournalingAttribute
The custom attribute Autodesk.Revit.Attributes.JournalingAttribute can optionally be applied to your implementation class of the IExternalCommand interface to control the journaling behavior during the external command execution. There are two options for journaling:
* _JournalMode.NoCommandData_ \- Contents of the ExternalCommandData.JournalData map are not written to the Revit journal. This option allows Revit API calls to write to the journal as needed. This option allows commands which invoke the Revit UI for selection or responses to task dialogs to replay correctly.
* _JournalMode.UsingCommandData_ \- Uses the IDictionary<String, String> supplied in the command data. This will hide all Revit journal entries between the external command invocation and the IDictionary<String, String< entry. Commands which invoke the Revit UI for selection or responses to task dialogs may not replay correctly. This is the default if the JournalingAttribute is not specified.
**Code Region 3-19: JournalingAttribute**
---
[Journaling(JournalingMode.UsingCommandData)]
public class CommandJournal : IExternalCommand
{
public Result Execute(
ExternalCommandData commandData,
ref string message, Autodesk.Revit.DB.ElementSet elements)
{
return Autodesk.Revit.UI.Result.Succeeded;
}
}
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

23
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_DB_level_External_Applications_html.md Normal file
View File

@@ -0,0 +1,23 @@
# DB-level External Applications
# DB-level External Applications
Database-level add-ins are External Applications that do not add anything to the Revit UI. DB-level External Applications can be used when the purpose of the application is to assign events and/or updaters to the Revit session.
To add a DB-level External Application to Revit, you create an object that implements the IExternalDBApplication interface.
The IExternalDBApplication interface has two abstract methods, OnStartup() and OnShutdown(), which you override in your DB-level external application. Revit calls OnStartup() when it starts, and OnShutdown() when it closes. This is very similar to IExternalApplication, but note that these methods return Autodesk.Revit.DB.ExternalDBApplicationResult rather than Autodesk.Revit.UI.Result and use ControlledApplication rather than UIControlledApplication.
**Code Region: IExternalDBApplication OnShutdown() and OnStartup()**
---
public interface IExternalDBApplication
{
public Autodesk.Revit.DB.ExternalDBApplicationResult OnStartup(ControlledApplication application);
public Autodesk.Revit.DB.ExternalDBApplicationResult OnShutdown(ControlledApplication application);
}
The ControlledApplication parameter provides access to Revit [Database Events](../../Advanced_Topics/Events/Database_Events.html). Events and Updaters to which the database-level application will respond can be registered in the OnStartup method.
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

42
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Digital_Signature_References_html.md Normal file
View File

@@ -0,0 +1,42 @@
# Digital Signature References
# Digital Signature References
The following references provide more information on digitally signing apps.
## Revit Help
* [About Digital Signatures](http://help.autodesk.com/view/RVT/2025/ENU/?guid=GUID-1C5947F2-4525-4B9F-9764-4D83D9FD2157)
* [Security: Signed File or Add-In](http://help.autodesk.com/view/RVT/2025/ENU/?guid=GUID-900A3EBF-A809-4A0E-96ED-5EEC965A2728)
* [Security: Unsigned File or Add-In](http://help.autodesk.com/view/RVT/2025/ENU/?guid=GUID-36D29367-A540-4CFD-9773-4995BF1DF08A)
* [Security: Invalid Signature](http://help.autodesk.com/view/RVT/2025/ENU/?guid=GUID-A5654402-D25A-4993-9059-0486B36AA708)
## Microsoft and Other Sites
* [How to sign an app package using SignTool](https://docs.microsoft.com/en-us/windows/win32/appxpkg/how-to-sign-a-package-using-signtool)
* [The truth about SHA1, SHA-256 and Code Signing Certificates](http://support.ksoftware.net/support/solutions/articles/215805-the-truth-about-sha1-sha-256-and-code-signing-certificates-)
## AutoCAD References
**AutoCAD Blog**
* <http://adndevblog.typepad.com/autocad/2015/01/digitally-signing-plug-in-files.html>
* <http://through-the-interface.typepad.com/through_the_interface/2015/05/signing-your-application-modules-for-autocad-2016-part-1.html>
**AutoCAD Help**
* [To Digitally Sign a Binary (ObjectARX or Managed .NET) File](http://help.autodesk.com/view/ACD/2025/ENU/?guid=GUID-3DA95353-9EF3-4E29-9671-6AEB7704EBE6)
* [To Digitally Sign a Binary (ObjectARX or Managed .NET) File with a Post-Build Event in Microsoft Visual Studio](http://help.autodesk.com/view/ACD/2025/ENU/?guid=GUID-AA7BBBED-98D0-4003-8C80-D66173664DBA)
* [To Make a Digital Certificate](http://help.autodesk.com/view/ACD/2025/ENU/?guid=GUID-26D7B31C-4165-410C-9FC4-2D556749D517)
* [To Create A Personal Information Exchange (PFX) File](http://help.autodesk.com/view/ACD/2025/ENU/?guid=GUID-DC1B25FE-E063-486C-B90C-565AB5E87BBC)
* [To Import a Digital Certificate](http://help.autodesk.com/view/ACD/2025/ENU/?guid=GUID-19D6716A-0AD1-4A7A-82BA-A067E6D65F66)
**Parent page:** [Digitally Signing Your Revit Add-in](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_html.html)

68
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Digitally_Signing_Your_App_html.md Normal file
View File

@@ -0,0 +1,68 @@
# Digitally Signing Your App
# Digitally Signing Your App
If you are publisher of a Revit add-in, you will have to sign your add-in with your own certificate.
To sign your add-in with your own certificate, you first need to purchase a digital signature from a digital certificate vendor. Once you obtain a certificate (cer) or Personal Information Exchange (pfx) file, you can sign your DLL(s) using **signtool**.
Alternatively, you can also use an online Authenticode signing service.
## Digital Certificate Venders
The following is a non-exhaustive list of vendors that provide digital certificates:
* Symantec - [www.symantec.com](https://www.symantec.com/)
* DigiCert - [www.digicert.com](https://www.digicert.com/)
* VERISIGN - [www.verisign.com](https://www.verisign.com/)
* Thawte - [www.thawte.com](https://www.thawte.com/)
## Signing using signtool
You can use [signtool.exe](https://msdn.microsoft.com/EN-US/LIBRARY/8S9B9YAZ\(V=VS.110\).ASPX) tool to sign your .NET dll. The tool is automatically installed with Visual Studio. To run the tool, use the Developer Command Prompt. The following is the format of the command line parameters:
### Command Region: Using signtool
signtool.exe sign /fd SHA256 /f <.pfx-file-name> /p <password> <file-to-sign>.dll
Where /fd is a flag for the file digest algorithm to use. Here we use SHA256. (SHA stands for Secure Hash Algorithm. The signtool default is SHA1. We recommend SHA256, which is a newer, more secure version.) <.pfx-file-name> is the name of .pfx (Personal Information Exchange) file you obtain from the vendor. `<password>` is the password that you specify when obtaining the pfx file. `<file-to-sign>.dll` is the name of the DLL that you want to sign.
For example, if you run the command in an arbitrary folder, the above command may look like this:
#### Command Region: signtool example
"C:\Program Files (x86)\Windows Kits\8.1\bin\x64\signtool" sign /fd SHA256 /f "C:/Dev/MyCert.pfx" /p "password123" “C:/Dev/HelloRevit.dll”
Note: The exact location of signtool may differ in your environment.
Once the DLL is signed with an authorized certification, Revit will no longer pop up a security warning dialog upon loading your add-in.
You can also include the command in the Post-Built Event section of Visual Studio for your application project properties.
#### Command Region: Post-Build Event signing
"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\signtool.exe" /fd SHA256 sign /f
"C:\Autodesk\MyCert.pfx" /p MyPassword "$(TargetDir)$(TargetFileName)"
It is also worth adding a time stamp while signing (/td and /tr switches in signtool.exe); otherwise the app becomes untrusted when the certificate expires. Adding the time stamp ensures the app is trusted forever as long as it was signed prior to expiration (unless the certificate gets revoked):
#### Command Region: Adding a time stamp
signtool.exe timestamp /td sha256 /tr <URL-of-time-stamp-server> <file-to-sign>.dll
For example, the following uses the verisign timestamp server:
#### Command Region: Time stamp example
signtool.exe timestamp /td sha256 /tr "http://sha256timestamp.ws.symantec.com/sha256/" HelloRevit.dll
Note: The /td sha256 and /tr switches used in the example above are used to sign with sha256 timestamp. Microsoft treats SHA1 timestamps as unsigned. Please refer to [this article](http://support.ksoftware.net/support/solutions/articles/215805-the-truth-about-sha1-sha-256-and-code-signing-certificates-) for more details.
**Parent page:** [Digitally Signing Your Revit Add-in](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_html.html)

87
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Making_Your_Own_Certificate_for_Testing_and_Internal_Use_html.md Normal file
View File

@@ -0,0 +1,87 @@
# Making Your Own Certificate for Testing and Internal Use
# Making Your Own Certificate for Testing and Internal Use
You can make your own digital certificate for testing or using within your company.
To create your own digital certificate:
1. Create a digital certificate using the [MakeCert.exe](https://msdn.microsoft.com/EN-US/LIBRARY/WINDOWS/DESKTOP/AA386968\(V=VS.85\).ASPX) tool.
2. Create a Personal Information Exchange (pfx) file using the Pvk2Pfx.exe tool.
3. [Digitally Signing Your App](./Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Digitally_Signing_Your_App_html.html).
4. Import a Digital Certificate to Windows Certificate Store ([CertMgr.msc or CertUtil.exe](https://msdn.microsoft.com/en-us/library/E78BYTA0\(V=VS.110\).aspx)).
## Create a Digital Certificate
You can use [MakeCert.exe](https://msdn.microsoft.com/EN-US/LIBRARY/WINDOWS/DESKTOP/AA386968\(V=VS.85\).ASPX) tool to make your own digital certificate for testing and internal use. The following is the command format:
Command Region: Make a certificate command format
---
MakeCert.exe -r -sv <name-of-private-key-file>.pvk -n "CN=<developer-name>" <name-of-certificate-file>.cer -b <start-data> -e <end-date>
Where `<name-of-private-key-file>` is the name of the file where the private key is stored, `<developer- name>` is the name of the developer, `<name-of-certificate-file>` is the name of the certificate file, `<start-date>` is the date when the certificate became valid (format is mm/dd/yyyy), and `<end-date>` is the date when the validity of the certificate ends.
For example:
Command Region: MakeCert.exe example
---
"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\MakeCert.exe" -r -sv MyCert.pvk -n "CN=DevABC" MyCert.cer -b 01/01/2016 -e 12/31/2016
Or:
Command Region: MakeCert.exe example
---
"C:\Program Files (x86)\Windows Kits\8.1\bin\x64\makecert.exe" -r -sv MyCert.pvk -n "CN=DevABC" MyCert.cer -b 01/01/2016 -e 12/31/2016
This command will bring up "Create Private Key Password" dialog. Enter the private key password in the dialog. If it asks for password, enter again. When everything is done, you will see a message "Succeeded" in the command window and .cer and .pvk files are created.
## Convert to PFX
The next step is to convert a digital certificate to a Personal Information Exchange (pfx) file using the pvk2pfx.exe tool. In this step, you need the .pvk file, .cer file, and password you created in the above step. The command format looks like this:
Command Region: Convert to PFX command format
---
pvk2pfx.exe" -pvk <name-of-private-key-file>.pvk -pi <password-for-pvk> -spc <name-of-certification-file-name>.cer
-pfx <name-of-pfx-file> -po <password-for-pfx>
Where `<name-of-private-key-file>` is the name of pvk file you created, `<password-for-pvk>` is the password you assigned to the pvk file. `<name-of-certification-file-name>` is the name of the certification file or .cer file. `<name-of-pfx-file>` is the name of the .pfx. `<password-for-pfx>` is a password to be assigned to the .pfx file.
For example:
Command Region: Convert to PFX example
---
"C:\Program Files (x86)\Windows Kits\8.1\bin\x64\pvk2pfx.exe" -pvk MyCert.pvk -pi password123 -spc MyCert.cer -pfx MyCert.pfx -po password234
When the operation succeeds, the command ends without error message and a .pfx file will be created.
Once you have a pfx file, you can [Digitally Signing Your App](./Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Digitally_Signing_Your_App_html.html).
## Import the Digital Certificate to Windows Certificate Store
One more step you need when you are making your own digital certificate is to import it to your computer. You can do this in Certificate Manager ([CertMgr.msc](https://msdn.microsoft.com/EN-US/LIBRARY/E78BYTA0\(V=VS.110\).ASPX)) or CertUtils.exe tool. Here we use the UI tool. Please refer [here for alternatives](http://help.autodesk.com/view/ACD/2026/ENU/?guid=GUID-19D6716A-0AD1-4A7A-82BA-A067E6D65F66).
1. From Start >> Run >> CertMgr.msc. (Or on Windows 8.1/10, right click on Start >> Run >> CertMgr.msc) CertMgr opens.
2. On CertMgr dialog, right click on **Trusted Publishers** >> All Tasks >> Import …
3. Follow the instructions on Certificate Import Wizard. Click Next.
4. On a dialog which asks "Files to Import", choose the pfx file you want to import.
5. On the "Password" dialog, enter the password. Keep "Include all extended properties" checked.
6. Choose "Place all certificates in the following store" then Click Next.
7. Confirm and Finish.
8. If you see "Import a new Private signature key" dialog, click OK. (This part may differ depending on your environment.)
9. Repeat the same step with **Trusted Root Certification Authorities**. This step is to validate digitally signed binary files.
**Parent page:** [Digitally Signing Your Revit Add-in](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_html.html)

19
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_html.md Normal file
View File

@@ -0,0 +1,19 @@
# Digitally Signing Your Revit Add-in
# Digitally Signing Your Revit Add-in
Revit checks security credentials of add-ins.
If an add-in is not digitally signed with a certificate issued by a trusted certificate authority, Revit pops up a dialog when opening asking the user to confirm if he/she wants to load the application. The figure below shows an example of the security warning dialog when an unsigned add-in is detected. The user is presented with choices of: 1) allowing the same add-in to always load from now on, 2) load only this time and ask again next time, and 3) do not allow to load the add-in.
If you are professional developer and your application is already digitally signed by a trusted certificate authority, your add-in is already compatible with the digital signature checking in Revit. The following sections are intended for developers who author add-ins, but who are not familiar with digital signing in Revit.
**Pages in this section**
* [Digitally Signing Your App](Digitally_Signing_Your_Revit_Add_in/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Digitally_Signing_Your_App_html.html)
* [Making Your Own Certificate for Testing and Internal Use](Digitally_Signing_Your_Revit_Add_in/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Making_Your_Own_Certificate_for_Testing_and_Internal_Use_html.html)
* [Digital Signature References](Digitally_Signing_Your_Revit_Add_in/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_Digital_Signature_References_html.html)
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

81
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_External_Application_html.md Normal file
View File

@@ -0,0 +1,81 @@
# External Application
# External Application
Developers can add functionality through External Applications as well as External Commands. Ribbon tabs and ribbon panels are customized using the External Application. Ribbon panel buttons are bound to an External command.
### IExternalApplication
To add an External Application to Revit, you create an object that implements the IExternalApplication interface.
The IExternalApplication interface has two abstract methods, OnStartup() and OnShutdown(), which you override in your external application. Revit calls OnStartup() when it starts, and OnShutdown() when it closes.
This is the OnStartup() and OnShutdown() abstract definition:
**Code Region 3-6: OnShutdown() and OnStartup()**
---
public interface IExternalApplication
{
public Autodesk.Revit.UI.Result OnStartup(UIControlledApplication application);
public Autodesk.Revit.UI.Result OnShutdown(UIControlledApplication application);
}
The UIControlledApplication parameter provides access to certain Revit events and allows customization of ribbon panels and controls and the addition of ribbon tabs. For example, the public event DialogBoxShowing of UIControlledApplication can be used to capture the event of a dialog being displayed.
The following code snippet registers the handling function that is called right before a dialog is shown and illustrates how to use the UIControlledApplication type to register an event handler and process the event when it occurs.
**Code Region 3-8: Using ControlledApplication**
---
public class Application_DialogBoxShowing : IExternalApplication
{
// Implement the OnStartup method to register events when Revit starts.
public Result OnStartup(UIControlledApplication application)
{
// Register related events
application.DialogBoxShowing +=
new EventHandler<Autodesk.Revit.UI.Events.DialogBoxShowingEventArgs>(AppDialogShowing);
return Result.Succeeded;
}
// Implement this method to unregister the subscribed events when Revit exits.
public Result OnShutdown(UIControlledApplication application)
{
// unregister events
application.DialogBoxShowing -=
new EventHandler<Autodesk.Revit.UI.Events.DialogBoxShowingEventArgs>(AppDialogShowing);
return Result.Succeeded;
}
// The DialogBoxShowing event handler, which allow you to
// do some work before the dialog shows
void AppDialogShowing(object sender, DialogBoxShowingEventArgs args)
{
// Get the help id of the showing dialog
string dialogId = args.DialogId;
// return if the dialog has no DialogId (such as with a Task Dialog)
if (dialogId == "")
return;
// Show the prompt message and allow the user to close the dialog directly.
TaskDialog taskDialog = new TaskDialog("Revit");
taskDialog.MainContent = "A Revit dialog is about to be opened.\n" +
"The DialogId of this dialog is " + dialogId + "\n" +
"Press 'Cancel' to immediately dismiss the dialog";
taskDialog.CommonButtons = TaskDialogCommonButtons.Ok |
TaskDialogCommonButtons.Cancel;
TaskDialogResult result = taskDialog.Show();
if (TaskDialogResult.Cancel == result)
{
// dismiss the Revit dialog
args.OverrideResult(1);
}
}
}
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

204
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_External_Commands_html.md Normal file
View File

@@ -0,0 +1,204 @@
# External Commands
# External Commands
Developers can add functionality by implementing External Commands which appear in the External Tools menu-button.
## Loading and Running External Commands
When no other commands or edit modes are active in Revit, registered external commands are enabled. When a command is selected, a command object is created and its Execute() method is called. Once this method returns back to Revit, the command object is destroyed. As a result, data cannot persist in the object between command executions. However, there are other ways to save data between command executions. For example, you can use the Revit shared parameters mechanism to store data in the Revit project.
You can add External Commands to the External Tools Panel under the External Tools menu-button, or as a custom ribbon panel on the Add-Ins tab, Analyze tab or a new custom ribbon tab. See the [Walkthrough: Hello World](../Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Hello_World_html.html) and [Walkthrough: Add Hello World Ribbon Panel](../Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Add_Hello_World_Ribbon_Panel_html.html) for examples of these two approaches.
External tools, ribbon tabs and ribbon panels are initialized upon start up. The initialization steps are as follows:
* Revit reads manifest files and identifies:
* External Applications that can be invoked.
* External Tools that can be added to the Revit External Tools menu-button.
* External Application session adds panels and content to the Add-ins tab.
## IExternalCommand
You create an external command by creating an object that implements the IExternalCommand interface. The IExternalCommand interface has one abstract method, Execute, which is the main method for external commands.
The Execute() method has three parameters:
* commandData (ExternalCommandData)
* message (String)
* elements (ElementSet)
### commandData (ExternalCommandData)
The ExternalCommandData object contains references to Application and View which are required by the external command. All Revit data is retrieved directly or indirectly from this parameter in the external command.
For example, the following statement illustrates how to retrieve Autodesk.Revit.Document from the commandData parameter:
**Code Region 3-1: Retrieving the Active Document**
---
Document doc = commandData.Application.ActiveUIDocument.Document;
The following table illustrates the ExternalCommandData public properties:
**Table 1: ExternalCommandData public properties**
**Property** | **Description**
---|---
Application (Autodesk.Revit.UI.UIApplication) | Retrieves an object that represents the current UIApplication for external command.
JournalData (IDictionary<String, String>>) | A data map that can be used to read and write data to the Revit journal file.
View (Autodesk.Revit.DB.View) | Retrieves an object that represents the View external commands work on.
### message (String):
Error messages are returned by an external command using the output parameter message. The string-type parameter is set in the external command process. When Autodesk.Revit.UI.Result.Failed or Autodesk.Revit.UI.Result.Cancelled is returned, and the message parameter is set, an error dialog appears.
The following code sample illustrates how to use the message parameter.
**Code Region 3-2: Setting an error message string**
---
class IExternalCommand_message : IExternalCommand
{
public Autodesk.Revit.UI.Result Execute(
ExternalCommandData commandData, ref string message,
ElementSet elements)
{
message = "Could not locate walls for analysis.";
return Autodesk.Revit.UI.Result.Failed;
}
}
Implementing the previous external command causes the following dialog box to appear:
**Figure 12: Error message dialog box**
### elements (ElementSet):
Whenever Autodesk.Revit.UI.Result.Failed or Autodesk.Revit.UI.Result.Canceled is returned and the parameter message is not empty, an error or warning dialog box appears. Additionally, if any elements are added to the elements parameter, these elements will be highlighted on screen. It is a good practice to set the message parameter whenever the command fails, whether or not elements are also returned.
The following code highlights pre-selected walls:
**Code Region 3-3: Highlighting walls**
---
class IExternalcommand_elements : IExternalCommand
{
public Result Execute(
Autodesk.Revit.UI.ExternalCommandData commandData, ref string message,
Autodesk.Revit.DB.ElementSet elements)
{
message = "Please note the highlighted Walls.";
FilteredElementCollector collector = new FilteredElementCollector(commandData.Application.ActiveUIDocument.Document);
ICollection<Element> collection = collector.OfClass(typeof(Wall)).ToElements();
foreach (Element e in collection)
{
elements.Insert(e);
}
return Result.Failed;
}
}
### Return
The Return result indicates that the execution failed, succeeded, or is canceled by the user. If it does not succeed, Revit reverses changes made by the external command.
**Table 2: IExternalCommand.Result**
**Member Name** | **Description**
---|---
Autodesk.Revit.UI.Result.Succeeded | The external command completed successfully. Revit keeps all changes made by the external command.
Autodesk.Revit.UI.Result.Failed | The external command failed to complete the task. Revit reverses operations performed by the external command. If the message parameter of Execute is set, Revit displays a dialog with the text "Error - cannot be ignored".
Autodesk.Revit.UI.Result.Cancelled | The user cancelled the external command. Revit reverses changes made by the external command. If the message parameter of Execute is set, Revit displays a dialog with the text "Warning - can be ignored".
The following example displays a greeting message and allows the user to select the return value. Use the Execute() method as the entrance to the Revit application.
**Code Region 3-4: Prompting the user**
---
public Autodesk.Revit.UI.Result Execute(ExternalCommandData commandData,
ref string message, ElementSet elements)
{
try
{
Document doc = commandData.Application.ActiveUIDocument.Document;
UIDocument uidoc = commandData.Application.ActiveUIDocument;
// Delete selected elements
ICollection<Autodesk.Revit.DB.ElementId> ids =
doc.Delete(uidoc.Selection.GetElementIds());
TaskDialog taskDialog = new TaskDialog("Revit");
taskDialog.MainContent =
("Click Yes to return Succeeded. Selected members will be deleted.\n" +
"Click No to return Failed. Selected members will not be deleted.\n" +
"Click Cancel to return Cancelled. Selected members will not be deleted.");
TaskDialogCommonButtons buttons = TaskDialogCommonButtons.Yes |
TaskDialogCommonButtons.No | TaskDialogCommonButtons.Cancel;
taskDialog.CommonButtons = buttons;
TaskDialogResult taskDialogResult = taskDialog.Show();
if (taskDialogResult == TaskDialogResult.Yes)
{
return Autodesk.Revit.UI.Result.Succeeded;
}
else if (taskDialogResult == TaskDialogResult.No)
{
ICollection<ElementId> selectedElementIds = uidoc.Selection.GetElementIds();
foreach (ElementId id in selectedElementIds)
{
elements.Insert( doc.GetElement(id) );
}
message = "Failed to delete selection.";
return Autodesk.Revit.UI.Result.Failed;
}
else
{
return Autodesk.Revit.UI.Result.Cancelled;
}
}
catch
{
message = "Unexpected Exception thrown.";
return Autodesk.Revit.UI.Result.Failed;
}
}
### IExternalCommandAvailability
This interface allows you control over whether or not an external command button may be pressed. The IsCommandAvailable interface method passes the application and a set of categories matching the categories of selected items in Revit to your implementation. The typical use would be to check the selected categories to see if they meet the criteria for your command to be run.
In this example the accessibility check allows a button to be clicked when there is no active selection, or when at least one wall is selected:
**Code Region 3-5: Setting Command Availability**
---
public class SampleAccessibilityCheck : IExternalCommandAvailability
{
public bool IsCommandAvailable(Autodesk.Revit.UI.UIApplication applicationData,
CategorySet selectedCategories)
{
// Allow button click if there is no active selection
if (selectedCategories.IsEmpty)
return true;
// Allow button click if there is at least one wall selected
foreach (Category c in selectedCategories)
{
if (c.Id.Value == (int)BuiltInCategory.OST_Walls)
return true;
}
return false;
}
}
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

31
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Localization_html.md Normal file
View File

@@ -0,0 +1,31 @@
# Localization
# Localization
You can let Revit localize the user-visible resources of an external command button (including Text, large icon image, long and short descriptions and tooltip image). You will need to create a .NET Satellite DLL which contains the strings, images, and icons for the button. Then change the values of the tags in the .addin file to correspond to the names of resources in the Satellite dll, but prepended with the @character. So the tag:
**Code Region 3-13: Non-localized Text Entry**
---
`<Text>Extension Manager</Text>`
Becomes:
**Code Region 3-14: Localized Text Entry**
---
`<Text>@ExtensionText</Text>`
where ExtensionText is the name of the resource found in the Satellite DLL.
The Satellite DLLs are expected to be in a directory with the name of the language of the language-culture, such as en or en-US. The directory should be located in the directory that contains the add-in assembly. See <http://msdn.microsoft.com/en-us/library/e9zazcx5.aspx> to create managed Satellite DLLs.
You can force Revit to use a particular language resource DLL, regardless of the language of the Revit session, by specifying the language and culture explicitly with a LanguageType tag.
**Code Region 3-15: Using LanguageType Tag**
---
`<LanguageType>English_USA</LanguageType>`
For example, the entry above would force Revit to always load the values from the en-US Satellite DLL and to ignore the current Revit language and culture settings when considering the localizable members of the external command manifest file.
Revit supports the 11 languages defined in the Autodesk.Revit.ApplicationServices.LanguageType enumerated type: English_USA, German, Spanish, French, Italian, Dutch, Chinese_Simplified, Chinese_Traditional, Japanese, Korean, and Russian.
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

27
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Overview_html.md Normal file
View File

@@ -0,0 +1,27 @@
# Overview
# Overview
The Revit Platform API is based on Revit application functionality. The Revit Platform API is composed of two class Libraries that only work when Revit is running.
The RevitAPI.dll contains methods used to access Revit's application, documents, elements, and parameters at the database level. It also contains IExternalDBApplication and related interfaces.
The RevitAPIUI.dll contains all API interfaces related to manipulation and customization of the Revit user interface, including:
* IExternalCommand and External Command related interfaces
* IExternalApplication and related interfaces
* Selection
* RibbonPanel, RibbonItem and subclasses
* TaskDialogs
As the following picture shows, Revit Architecture, Revit Structure, and Revit MEP are specific to Architecture, Structure, and MEP respectively.
**Figure 11: Revit, RevitAPI and Add-ins**
To create a RevitAPI based add-in, you must provide specific entrypoint types in your add-in DLL. These entrypoint classes implement interfaces, either IExternalCommand, IExternalApplication, or IExternalDBApplication. In this way, the add-in is run automatically on certain events or, in the case of IExternalCommand and IExternalApplication, manually from the External Tools menu-button.
IExternalCommand, IExternalApplication, IExternalDBApplication, and other available Revit events for add-in integration are introduced in this chapter.
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

23
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Revit_Exceptions_html.md Normal file
View File

@@ -0,0 +1,23 @@
# Revit Exceptions
# Revit Exceptions
When API methods encounter a non-fatal error, they throw an exception. Exceptions should be caught by Revit add-ins. The Revit API help file specifies exceptions that are typically encountered for specific methods. All Revit API methods throw a subclass of Autodesk.Revit.Exceptions.ApplicationException. These exceptions closely mirror standard .NET exceptions such as:
* ArgumentException
* InvalidOperationException
* FileNotFoundException
However, some of these subclasses are unique to Revit:
* AutoJoinFailedException
* RegenerationFailedException
* ModificationOutsideTransactionException
In addition, there is a special exception type called InternalException, which represents a failure path which was not anticipated. Exceptions of this type carry extra diagnostic information which can be passed back to Autodesk for diagnosis.
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

85
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Revit_style_Task_Dialogs_html.md Normal file
View File

@@ -0,0 +1,85 @@
# Revit-style Task Dialogs
# Revit-style Task Dialogs
A TaskDialog is a Revit-style alternative to a simple Windows MessageBox. It can be used to display information and receive simple input from the user. It has a common set of controls that are arranged in a standard order to assure consistent look and feel with the rest of Revit.
**Figure 19: Revit-style Task Dialog**
There are two ways to create and show a task dialog to the user. The first option is to construct the TaskDialog, set its properties individually, and use the instance method Show() to show it to the user. The second is to use one of the static Show() methods to construct and show the dialog in one step. When you use the static methods only a subset of the options can be specified.
The property `TaskDialog.EnableMarqueeDialogBar` allows the TaskDialog to include a progress bar that has an indeterminate start and stop. The animation continues until the TaskDialog is closed.
The FooterText property can link to the help document and can contain a hyperlink of the form "rvthelptopic:[topic]" to launch Revit's contextual for the topic specified.
Please see [Dialog Guidelines](../../Appendices/API_User_Interface_Guidelines/Revit_API_Revit_API_Developers_Guide_Appendices_API_User_Interface_Guidelines_Dialog_Guidelines_html.html) in the [API User Interface Guidelines](../../Appendices/Revit_API_Revit_API_Developers_Guide_Appendices_API_User_Interface_Guidelines_html.html) section for information on developing a task dialog that is compliant with the standards used by Autodesk.
* * *
The following example shows how to create and display the task dialog shown above.
**Code Region 3-27: Displaying Revit-style TaskDialog**
---
[Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.ReadOnly)]
class TaskDialogExample : IExternalCommand
{
public Autodesk.Revit.UI.Result Execute(ExternalCommandData commandData, ref string message, Autodesk.Revit.DB.ElementSet elements)
{
// Get the application and document from external command data.
Application app = commandData.Application.Application;
Document activeDoc = commandData.Application.ActiveUIDocument.Document;
// Creates a Revit task dialog to communicate information to the user.
TaskDialog mainDialog = new TaskDialog("Hello, Revit!");
mainDialog.MainInstruction = "Hello, Revit!";
mainDialog.MainContent =
"This sample shows how to use a Revit task dialog to communicate with the user."
+ "The command links below open additional task dialogs with more information.";
// Add commmandLink options to task dialog
mainDialog.AddCommandLink(TaskDialogCommandLinkId.CommandLink1,
"View information about the Revit installation");
mainDialog.AddCommandLink(TaskDialogCommandLinkId.CommandLink2,
"View information about the active document");
// Set common buttons and default button. If no CommonButton or CommandLink is added,
// task dialog will show a Close button by default
mainDialog.CommonButtons = TaskDialogCommonButtons.Close;
mainDialog.DefaultButton = TaskDialogResult.Close;
// Set footer text. Footer text is usually used to link to the help document.
mainDialog.FooterText =
"" + "Click here for the Revit API Developer Center";
TaskDialogResult tResult = mainDialog.Show();
// If the user clicks the first command link, a simple Task Dialog
// with only a Close button shows information about the Revit installation.
if (TaskDialogResult.CommandLink1 == tResult)
{
TaskDialog dialog_CommandLink1 = new TaskDialog("Revit Build Information");
dialog_CommandLink1.MainInstruction =
"Revit Version Name is: " + app.VersionName + "\n"
+ "Revit Version Number is: " + app.VersionNumber + "\n"
+ "Revit Version Build is: " + app.VersionBuild;
dialog_CommandLink1.Show();
}
// If the user clicks the second command link, a simple Task Dialog
// created by static method shows information about the active document
else if (TaskDialogResult.CommandLink2 == tResult)
{
TaskDialog.Show("Active Document Information",
"Active document: " + activeDoc.Title + "\n"
+ "Active view name: " + activeDoc.ActiveView.Name);
}
return Autodesk.Revit.UI.Result.Succeeded;
}
}
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

391
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Ribbon_Panels_and_Controls_html.md Normal file
View File

@@ -0,0 +1,391 @@
# Ribbon Panels and Controls
# Ribbon Panels and Controls
Revit provides API solutions to integrate custom ribbon panels and controls.
These APIs are used with IExternalApplication. Custom ribbon panels can be added to the Add-Ins tab, the Analyze tab or to a new custom ribbon tab.
Panels can include buttons, both large and small, which can be either simple push buttons, pulldown buttons containing multiple commands, or split buttons which are pulldown buttons with a default push button attached. In addition to buttons, panels can include radio groups, combo boxes and text boxes. Panels can also include vertical separators to help separate commands into logical groups. Finally, panels can include a slide out control accessed by clicking on the bottom of the panel.
Please see [Ribbon Guidelines](../../Appendices/API_User_Interface_Guidelines/Revit_API_Revit_API_Developers_Guide_Appendices_API_User_Interface_Guidelines_Ribbon_Guidelines_html.html) in the [API User Interface Guidelines](../../Appendices/Revit_API_Revit_API_Developers_Guide_Appendices_API_User_Interface_Guidelines_html.html) section for information on developing a user interface that is compliant with the standards used by Autodesk.
### Create a New Ribbon Tab
Although ribbon panels can be added to the Add-Ins or Analyze tab, they can also be added to a new custom ribbon tab. This option should only be used if necessary. To ensure that the standard Revit ribbon tabs remain visible, a limit of 20 custom ribbon tabs is imposed. The following image shows a new ribbon tab with one ribbon panel and a few simple controls.
Below is the code that generated the above ribbon tab.
**Code Region: New Ribbon tab**
---
public Result OnStartup(UIControlledApplication application)
{
// Create a custom ribbon tab
String tabName = "This Tab Name";
application.CreateRibbonTab(tabName);
// Create two push buttons
PushButtonData button1 = new PushButtonData("Button1", "My Button #1",
@"C:\ExternalCommands.dll", "Revit.Test.Command1");
PushButtonData button2 = new PushButtonData("Button2", "My Button #2",
@"C:\ExternalCommands.dll", "Revit.Test.Command2");
// Create a ribbon panel
RibbonPanel m_projectPanel = application.CreateRibbonPanel(tabName, "This Panel Name");
// Add the buttons to the panel
List<RibbonItem> projectButtons = new List<RibbonItem>();
projectButtons.AddRange(m_projectPanel.AddStackedItems(button1, button2));
return Result.Succeeded;
}
### Create a New Ribbon Panel and Controls
The following image shows a ribbon panel on the Add-Ins tab using various ribbon panel controls. The following sections describe these controls in more detail and provide code samples for creating each portion of the ribbon.
**Figure 14: New ribbon panel and controls**
The following code outlines the steps taken to create the ribbon panel pictured above. Each of the functions called in this sample is provided in subsequent samples later in this section. Those samples assume that there is an assembly located at D:\ Sample\HelloWorld\bin\Debug\Hello.dll which contains the External Command Types:
* Hello.HelloButton
* Hello.HelloOne
* Hello.HelloTwo
* Hello.HelloThree
* Hello.HelloA
* Hello.HelloB
* Hello.HelloC
* Hello.HelloRed
* Hello.HelloBlue
* Hello.HelloGreen
**Code Region: Ribbon panel and controls**
---
public Result OnStartup(Autodesk.Revit.UI.UIControlledApplication app)
{
RibbonPanel panel = app.CreateRibbonPanel("New Ribbon Panel");
AddRadioGroup(panel);
panel.AddSeparator();
AddPushButtonWithContextualHelp(panel);
AddSplitButton(panel);
AddStackedButtons(panel);
AddSlideOut(panel);
return Result.Succeeded;
}
### Ribbon Panel
Custom ribbon panels can be added to the Add-Ins tab (the default) or the Analyze tab, or they can be added to a new custom ribbon tab. There are various types of ribbon controls that can be added to ribbon panels which are discussed in more detail in the next section. All ribbon controls have some common properties and functionality.
#### Ribbon Control Classes
Each ribbon control has two classes associated with it - one derived from RibbonItemData that is used to create the control (i.e. SplitButtonData) and add it to a ribbon panel and one derived from RibbonItem (i.e. SplitButton) which represents the item after it is added to a panel. The properties available from RibbonItemData (and the derived classes) are also available from RibbonItem (and the corresponding derived classes). These properties can be set prior to adding the control to the panel or can be set using the RibbonItem class after it has been added to the panel.
#### Tooltips
Most controls can have a tooltip set (using the ToolTip property) which is displayed when the user moves the mouse over the control. When the user hovers the mouse over a control for an extended period of time, an extended tooltip will be displayed using the LongDescription and the ToolTipImage properties. If neither LongDescription nor ToolTipImage are set, the extended tooltip is not displayed. If no ToolTip is provided, then the text of the control (RibbonItem.ItemText) is displayed when the mouse moves over the control.
**Figure 15: Extended Tooltip**
#### Contextual Help
Controls can have contextual help associated with them. When the user hovers the mouse over the control and hits F1, the contextual help is triggered. Contextual help options include linking to an external URL, launching a locally installed help (chm) file, or linking to a topic on the Autodesk help wiki. The ContextualHelp class is used to create a type of contextual help, and then RibbonItem.SetContextualHelp() (or RibbonItemData.SetContextualHelp()) associates it with a control. When a ContextualHelp instance is associated with a control, the text "Press F1 for more help" will appear below the tooltip when the mouse hovers over the control, as shown below.
The following example associates a new ContextualHelp with a push button control. Pressing F1 when hovered over the push button will open the Autodesk homepage in a new browser window.
**Code Region: Contextual Help**
---
private void AddPushButtonWithContextualHelp(RibbonPanel panel)
{
PushButton pushButton = panel.AddItem(new PushButtonData("HelloWorld",
"HelloWorld", @"D:\Sample\HelloWorld\bin\Debug\HelloWorld.dll", "HelloWorld.CsHelloWorld")) as PushButton;
// Set ToolTip and contextual help
pushButton.ToolTip = "Say Hello World";
ContextualHelp contextHelp = new ContextualHelp(ContextualHelpType.Url,
"http://www.autodesk.com");
pushButton.SetContextualHelp(contextHelp);
// Set the large image shown on button
pushButton.LargeImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
}
The ContextualHelp class has a Launch() method that can be called to display the help topic specified by the contents of this ContextualHelp object at any time, the same as when the F1 key is pressed when the control is active. This allows the association of help topics with user interface components inside dialogs created by an add-in application.
#### Associating images with controls
All of these controls can have an image associated with them using the LargeImage property. The best size for images associated with large controls, such as non-stacked ribbon and drop-down buttons, is 32×32 pixels, but larger images will be adjusted to fit the button. Stacked buttons and small controls such as text boxes and combo boxes should have a 16×16 pixel image set. Large buttons should also have a 16×16 pixel image set for the Image property. This image is used if the command is moved to the Quick Access Toolbar. If the Image property is not set, no image will be displayed if the command is moved to the Quick Access Toolbar. Note that if an image larger than 16×16 pixels is used, it will NOT be adjusted to fit the toolbar.
The ToolTipImage will be displayed below the LongDescription in the extended tooltip, if provided. There is no recommended size for this image.
#### Ribbon control availability
Ribbon controls can be enabled or disabled with the RibbonItem.Enabled property or made visible or invisible with the RibbonItem.Visible property.
### Ribbon Controls
In addition to the following controls, vertical separators can be added to ribbon panels to group related sets of controls.
#### Push Buttons
There are three types of buttons you can add to a panel: simple push buttons, drop-down buttons, and split buttons. The HelloWorld button in Figure 14 is a push button. When the button is pressed, the corresponding command is triggered.
In addition to the Enabled property, PushButton has the AvailabilityClassName property which can be used to set the name of an IExternalCommandAvailability interface that controls when the command is available.
**Code Region: Adding a push button**
---
private void AddSimplePushButton(RibbonPanel panel)
{
PushButton pushButton = panel.AddItem(new PushButtonData("HelloWorld",
"HelloWorld", @"D:\HelloWorld.dll", "HelloWorld.CsHelloWorld")) as PushButton;
pushButton.ToolTip = "Say Hello World";
// Set the large image shown on button
pushButton.LargeImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
}
#### Drop-down buttons
Drop-down buttons expand to display two or more commands in a drop-down menu. In the Revit API, drop-down buttons are referred to as PulldownButtons. Horizontal separators can be added between items in the drop-down menu.
Each command in a drop-down menu can also have an associated LargeImage as shown in the example above.
#### Split buttons
Split buttons are drop-down buttons with a default push button attached. The top half of the button works like a push button while the bottom half functions as a drop-down button. The Option One button in Figure 14 is a split button.
Initially, the push button will be the top item in the drop-down list. However, by using the IsSynchronizedWithCurrentItem property, the default command (which is displayed as the push button top half of the split button) can be synchronized with the last used command. By default it will be synched. Selecting Option Two in the split button from Figure 14 above yields:
**Figure 16: Split button synchronized with current item**
Note that the ToolTip, ToolTipImage and LongDescription properties for SplitButton are ignored. The tooltip for the current push button is shown instead.
**Code Region: Adding a split button**
---
private void AddSplitButton(RibbonPanel panel)
{
string assembly = @"D:\Sample\HelloWorld\bin\Debug\Hello.dll";
// create push buttons for split button drop down
PushButtonData bOne = new PushButtonData("ButtonNameA", "Option One",
assembly, "Hello.HelloOne");
bOne.LargeImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\One.bmp"));
PushButtonData bTwo = new PushButtonData("ButtonNameB", "Option Two",
assembly, "Hello.HelloTwo");
bTwo.LargeImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Two.bmp"));
PushButtonData bThree = new PushButtonData("ButtonNameC", "Option Three",
assembly, "Hello.HelloThree");
bThree.LargeImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Three.bmp"));
SplitButtonData sb1 = new SplitButtonData("splitButton1", "Split");
SplitButton sb = panel.AddItem(sb1) as SplitButton;
sb.AddPushButton(bOne);
sb.AddPushButton(bTwo);
sb.AddPushButton(bThree);
}
#### Radio buttons
A radio button group is a set of mutually exclusive toggle buttons; only one can be selected at a time. After adding a RadioButtonGroup to a panel, use the AddItem() or AddItems() methods to add toggle buttons to the group. Toggle buttons are derived from PushButton. The RadioButtonGroup.Current property can be used to access the currently selected button.
Note that tooltips do not apply to radio button groups. Instead, the tooltip for each toggle button is displayed as the mouse moves over the individual buttons.
**Code Region: Adding radio button group**
---
private void AddRadioGroup(RibbonPanel panel)
{
// add radio button group
RadioButtonGroupData radioData = new RadioButtonGroupData("radioGroup");
RadioButtonGroup radioButtonGroup = panel.AddItem(radioData) as RadioButtonGroup;
// create toggle buttons and add to radio button group
ToggleButtonData tb1 = new ToggleButtonData("toggleButton1", "Red");
tb1.ToolTip = "Red Option";
tb1.LargeImage = new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Red.bmp"));
ToggleButtonData tb2 = new ToggleButtonData("toggleButton2", "Green");
tb2.ToolTip = "Green Option";
tb2.LargeImage = new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Green.bmp"));
ToggleButtonData tb3 = new ToggleButtonData("toggleButton3", "Blue");
tb3.ToolTip = "Blue Option";
tb3.LargeImage = new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Blue.bmp"));
radioButtonGroup.AddItem(tb1);
radioButtonGroup.AddItem(tb2);
radioButtonGroup.AddItem(tb3);
}
#### Text box
A text box is an input control for users to enter text. The image for a text box can be used as a clickable button by setting the ShowImageAsButton property to true. The default is false. The image is displayed to the left of the text box when ShowImageAsButton is false, and displayed at the right end of the text box when it acts as a button, as in Figure 14.
The text entered in the text box is only accepted if the user hits the Enter key or if they click the associated image when the image is shown as a button. Otherwise, the text will revert to its previous value.
In addition to providing a tooltip for a text box, the PromptText property can be used to indicate to the user what type of information to enter in the text box. Prompt text is displayed when the text box is empty and does not have keyboard focus. This text is displayed in italics. The text box in Figure 14 has the prompt text "Enter a comment".
The width of the text box can be set using the Width property. The default is 200 device-independent units.
The TextBox.EnterPressed event is triggered when the user presses enter, or when they click on the associated image for the text box when ShowImageAsButton is set to true. When implementing an EnterPressed event handler, cast the sender object to TextBox to get the value the user has entered as shown in the following example.
**Code Region: TextBox.EnterPressed event handler**
---
void ProcessText(object sender, Autodesk.Revit.UI.Events.TextBoxEnterPressedEventArgs args)
{
// cast sender as TextBox to retrieve text value
TextBox textBox = sender as TextBox;
string strText = textBox.Value as string;
}
The inherited ItemText property has no effect for TextBox. The user-entered text can be obtained from the Value property, which must be converted to a string.
See the section on stacked ribbon items for an example of adding a TextBox to a ribbon panel, including how to register the event above.
#### Combo box
A combo box is a pulldown with a set of selectable items. After adding a ComboBox to a panel, use the AddItem() or AddItems() methods to add ComboBoxMembers to the list.
Separators can also be added to separate items in the list or members can be optionally grouped using the ComboBoxMember.GroupName property. All members with the same GroupName will be grouped together with a header that shows the group name. Any items not assigned a GroupName will be placed at the top of the list. Note that when grouping items, separators should not be used as they will be placed at the end of the group rather than in the order they are added.
**Figure 17: Combo box with grouping**
ComboBox has three events:
* CurrentChanged - triggered when the current item of the ComboBox is changed
* DropDownClosed - triggered when the drop-down of the ComboBox is closed
* DropDownClosed - triggered when the drop-down of the ComboBox is opened
See the code region in the following section on stacked ribbon items for a sample of adding a ComboBox to a ribbon panel.
#### Stacked Panel Items
To conserve panel space, you can add small panel items in stacks of two or three. Each item in the stack can be a push button, a drop-down button, a combo box or a text box. Radio button groups and split buttons cannot be stacked. Stacked buttons should have an image associated through their Image property, rather than LargeImage. A 16×16 image is ideal for small stacked buttons.
The following example produces the stacked text box and combo box in Figure 14.
**Code Region: Adding a text box and combo box as stacked items**
---
private void AddStackedButtons(RibbonPanel panel)
{
ComboBoxData cbData = new ComboBoxData("comboBox");
TextBoxData textData = new TextBoxData("Text Box");
textData.Image =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_16x16.png"));
textData.Name = "Text Box";
textData.ToolTip = "Enter some text here";
textData.LongDescription = "This is text that will appear next to the image"
+ "when the user hovers the mouse over the control";
textData.ToolTipImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
IList<RibbonItem> stackedItems = panel.AddStackedItems(textData, cbData);
if (stackedItems.Count > 1)
{
TextBox tBox = stackedItems[0] as TextBox;
if (tBox != null)
{
tBox.PromptText = "Enter a comment";
tBox.ShowImageAsButton = true;
tBox.ToolTip = "Enter some text";
// Register event handler ProcessText
tBox.EnterPressed +=
new EventHandler<Autodesk.Revit.UI.Events.TextBoxEnterPressedEventArgs>(ProcessText);
}
ComboBox cBox = stackedItems[1] as ComboBox;
if (cBox != null)
{
cBox.ItemText = "ComboBox";
cBox.ToolTip = "Select an Option";
cBox.LongDescription = "Select a number or letter";
ComboBoxMemberData cboxMemDataA = new ComboBoxMemberData("A", "Option A");
cboxMemDataA.Image =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\A.bmp"));
cboxMemDataA.GroupName = "Letters";
cBox.AddItem(cboxMemDataA);
ComboBoxMemberData cboxMemDataB = new ComboBoxMemberData("B", "Option B");
cboxMemDataB.Image =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\B.bmp"));
cboxMemDataB.GroupName = "Letters";
cBox.AddItem(cboxMemDataB);
ComboBoxMemberData cboxMemData = new ComboBoxMemberData("One", "Option 1");
cboxMemData.Image =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\One.bmp"));
cboxMemData.GroupName = "Numbers";
cBox.AddItem(cboxMemData);
ComboBoxMemberData cboxMemData2 = new ComboBoxMemberData("Two", "Option 2");
cboxMemData2.Image =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Two.bmp"));
cboxMemData2.GroupName = "Numbers";
cBox.AddItem(cboxMemData2);
ComboBoxMemberData cboxMemData3 = new ComboBoxMemberData("Three", "Option 3");
cboxMemData3.Image =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Three.bmp"));
cboxMemData3.GroupName = "Numbers";
cBox.AddItem(cboxMemData3);
}
}
}
#### Slide-out panel
Use the RibbonPanel.AddSlideOut() method to add a slide out to the bottom of the ribbon panel. When a slide-out is added, an arrow is shown on the bottom of the panel, which when clicked will display the slide-out. After calling AddSlideOut(), subsequent calls to add new items to the panel will be added to the slide-out, so the slide-out must be added after all other controls have been added to the ribbon panel.
**Figure 18: Slide-out**
The following example produces the slide-out shown above:
**Code Region: TextBox.EnterPressed event handler**
---
private static void AddSlideOut(RibbonPanel panel)
{
string assembly = @"D:\Sample\HelloWorld\bin\Debug\Hello.dll";
panel.AddSlideOut();
// create some controls for the slide out
PushButtonData b1 = new PushButtonData("ButtonName1", "Button 1",
assembly, "Hello.HelloButton");
b1.LargeImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
PushButtonData b2 = new PushButtonData("ButtonName2", "Button 2",
assembly, "Hello.HelloTwo");
b2.LargeImage =
new System.Windows.Media.Imaging.BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_16x16.png"));
// items added after call to AddSlideOut() are added to slide-out automatically
panel.AddItem(b1);
panel.AddItem(b2);
}
**Parent page:** [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html)

37
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.md Normal file
View File

@@ -0,0 +1,37 @@
# Add-In Integration
# Add-In Integration
Developers add functionality by creating and implementing External Commands and External Applications. Revit identifies the new commands and applications using .addin manifest files.
* External Commands appear under the External Tools menu-button on the Add-Ins tab.
* External Applications are invoked when Revit starts up and unloaded when Revit shuts down.
This chapter focuses on the following:
* Learning how to add functionality using External Commands and External Applications.
* How to access Revit events.
* How to customize the Revit UI.
**Pages in this section**
* [Overview](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Overview_html.html)
* [External Commands](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_External_Commands_html.html)
* [External Application](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_External_Application_html.html)
* [Add-in Registration](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Add_in_Registration_html.html)
* [Digitally Signing Your Revit Add-in](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Digitally_Signing_Your_Revit_Add_in_html.html)
* [Localization](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Localization_html.html)
* [Attributes](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Attributes_html.html)
* [Revit Exceptions](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Revit_Exceptions_html.html)
* [Ribbon Panels and Controls](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Ribbon_Panels_and_Controls_html.html)
* [Revit-style Task Dialogs](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Revit_style_Task_Dialogs_html.html)
* [DB-level External Applications](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_DB_level_External_Applications_html.html)
* [Add-in Dependency Isolation](Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Add_in_Dependency_Isolation_html.html)
**Parent page:** [Introduction](../Revit_API_Revit_API_Developers_Guide_Introduction_html.html)

26
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_Discipline_Controls_html.md Normal file
View File

@@ -0,0 +1,26 @@
# Discipline Controls
# Discipline Controls
The properties:
* Application.IsArchitectureEnabled
* Application.IsStructureEnabled
* Application.IsStructuralAnalysisEnabled
* Application.IsMassingEnabled
* Application.IsEnergyAnalysisEnabled
* Application.IsSystemsEnabled
* Application.IsMechanicalEnabled
* Application.IsMechanicalAnalysisEnabled
* Application.IsElectricalEnabled
* Application.IsElectricalAnalysisEnabled
* Application.IsPipingEnabled
* Application.IsPipingAnalysisEnabled
provide read and modify access to the available disciplines. An application can read the properties to determine when to enable or disable aspects of it's UI.
When a discipline's status is toggled, Revit's UI will be adjusted, and certain operations and features will be enabled or disabled as appropriate. Enabling an analysis mode will only take effect if the corresponding discipline is enabled. For example, enabling mechanical analysis will not take effect unless the mechanical discipline is also enabled.
**Parent page:** [Application Functions](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_html.html)

35
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_How_to_use_Application_properties_to_enforce_a_correct_version_for_your_add_in_html.md Normal file
View File

@@ -0,0 +1,35 @@
# How to use Application properties to enforce a correct version for your add-in
# How to use Application properties to enforce a correct version for your add-in
Sometimes you need your add-in to operate only in the presence of a particular Update Release of Revit due to the presence of specific fixes or compatible APIs.
Properties of Application make it possible to check for specific versions of Revit. While the property VersionNumber will return a string representing the primary version number, the VersionBuild property will return the internal build number of the Autodesk Revit application.
Another useful property is the Application.SubVersionNumber property. It returns a string representing the major-minor version number for the Revit application such as "2018.0.0". This string is updated by Autodesk for all major and minor updates. Point releases (such as 2018.1.0) may have additional APIs and functionality not available in the initial customer release (such as 2018.0.0). Add-ins written to support initial releases will likely be compatible with subscription updates, but add-ins using new features in subscription updates would not be compatible with the initial releases.
The following sample code demonstrates a technique to determine if the Revit version is any Update Release after the initial known Revit release.
**Code Region: Use VersionBuild to identify if your add-in is compatible**
---
public void GetVersionInfo(Autodesk.Revit.ApplicationServices.Application app)
{
// 20110309_2315 is the datecode of the initial release of Revit 2012
if (app.VersionNumber == "2012" &&
String.Compare(app.VersionBuild, "20110309_2315") > 0)
{
TaskDialog.Show("Supported version",
"This application supported in this version.");
}
else
{
TaskDialog dialog = new TaskDialog("Unsupported version.");
dialog.MainIcon = TaskDialogIcon.TaskDialogIconWarning;
dialog.MainInstruction = "This Revit 2012 application is supported in UR1 and later releases.";
dialog.Show();
}
}
**Parent page:** [Application Functions](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_html.html)

112
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_html.md Normal file
View File

@@ -0,0 +1,112 @@
# Application Functions
# Application Functions
Application and UIApplication members provide access to application-wide data and settings as well as the active session of Revit.
## Application
The class represents the Autodesk Revit Application, providing access to documents, options and other application wide data and settings.
### Application Version Information
Application properties include VersionBuild, VersionNumber and VersionName. These can be used to provide add-in behavior based on the release and build of Revit, as shown in [How to use Application properties to enforce a correct version for your add-in](./Application_Functions/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_How_to_use_Application_properties_to_enforce_a_correct_version_for_your_add_in_html.html).
#### Application-wide Settings
##### Shared Parameters
Revit uses one shared parameter file at a time. The Application.OpenSharedParameterFile() method accesses the shared parameter file whose path is set in the SharedParametersFilename property. For more details, see [Shared Parameters](../../Basic_Interaction_with_Revit_Elements/Parameters/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_Shared_Parameters_html.html).
##### Library Content
The GetLibraryPaths() and SetLibraryPaths() methods provide access to the path information identifying where Revit searches for content .
##### Graphical Display
The BackgroundColor property allows read and write of the background color to use for model views in this session. The AllowNavigationDuringRedraw property enables or disables the option to allow view manipulation during redraw. This can be used to optimize performance during a redraw of the model.
#### Document Management
The Application class provides methods to create the following types of documents:
* Family document
* Project document
* Project template
The OpenDocumentFile() method can be used to open any of these document types.
All open documents can be retrieved using the Documents property.
For more details, see [Document and File Management](./Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_and_File_Management_html.html).
#### Session Information
Properties such as UserName and methods such as GetRevitServerNetworkHosts() provide read-only access to this session specific information.
#### Login Information
The static IsLoggedIn property checks if the user is logged in from this session to their Autodesk A360 account. If they are logged in, the LoginUserId property will return the user id of the user currently logged in. (The user id will be empty if the user is not logged in.) Unlike the UserName from the section above, the LoginUserId value is not a recognizable value, but an internal id. In conjunction with the Store Entitlement REST API, a publisher of an Autodesk app can verify if the current user has purchased their app from the Autodesk App Store. For more information about Store Entitlement API, please refer to [www.autodesk.com/developapps](http://www.autodesk.com/developapps).
#### Shared Parameter Management
#### Events
The Application class exposes document and application events such as document open and save. Subscribing to these events notifies the application when the events are enabled and acts accordingly. For more details, see [Events](../../Appendices/Glossary/Revit_API_Revit_API_Developers_Guide_Appendices_Glossary_Events_html.html) in the [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html) section.
#### Create
The Create property returns an Object Factory used to create application-wide utility and geometric objects in the Revit Platform API. Create is used when you want to create an object in the Revit application memory rather than your application's memory.
#### Failure Posting and Handling
The FailureDefinitionRegistry, which contains all registered FailureDefinitions is available from the static GetFailureDefinitionRegistry() method. The static method RegisterFailuresProcessor() can be used to register a custom IFailuresProcessor. For more information on posting and handling failures, see [Failure Posting and Handling](../../Advanced_Topics/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Failure_Posting_and_Handling_html.html).
#### Disconnect Warnings
The following properties control whether or not to show the graphical warnings for various types of disconnects.
* ShowGraphicalWarningCableTrayConduitDisconnects
* ShowGraphicalWarningDuctDisconnects
* ShowGraphicalWarningElectricalDisconnects
* ShowGraphicalWarningHangerDisconnects
* ShowGraphicalWarningPipeDisconnects
### UIApplication
This class represents an active session of the Autodesk Revit user interface, providing access to UI customization methods, events, and the active document.
#### UI Document Management
The UIApplication provides access to the active document using the UIActiveDocument property. Additionally, a Revit document may be opened using the overloaded OpenAndActivateDocument() method. The document will be opened with the default view active. This method may not be called inside a transaction and may only be invoked during an event when no active document is open yet in Revit and the event is not nested inside another event.
#### Add-in Management
The ActiveAddInId property gets the current active external application or external command id, while the LoadedApplications property returns an array of successfully loaded external applications.
#### Ribbon Panel Utility
Use the UIApplication object to add new ribbon panels and controls to Revit.
For more details, see [Ribbon Panels and Controls](../Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Ribbon_Panels_and_Controls_html.html) in the [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html) section.
#### Extents
The DrawingAreaExtents property returns a rectangle that represents the screen pixel coordinates of drawing area, while the MainWindowExtents property returns the rectangle that represents the screen pixel coordinates of the Revit main window
#### UI Events
The UIApplication class exposes UI related events such as when a dialog box is displayed. Subscribing to these events notifies the application when the events are enabled and acts accordingly. For more details, see [Events](../../Appendices/Glossary/Revit_API_Revit_API_Developers_Guide_Appendices_Glossary_Events_html.html) in the [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html) section.
**Pages in this section**
* [Discipline Controls](Application_Functions/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_Discipline_Controls_html.html)
* [How to use Application properties to enforce a correct version for your add-in](Application_Functions/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_How_to_use_Application_properties_to_enforce_a_correct_version_for_your_add_in_html.html)
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

143
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_CloudFiles_html.md Normal file
View File

@@ -0,0 +1,143 @@
# Cloud Models
# Cloud Models
## Basic Info
* Document.IsModelInCloud indicates if the current document is located in the cloud.
* Document.GetCloudModelPath() returns the cloud model path.
Autodesk provides two different web portals and regions with different URLs. You can save your Revit cloud models to either:
* Autodesk Docs US, at [Autodesk Insight](https://insight.b360.autodesk.com)
* Autodesk Docs EU, at [Autodesk Insight](https://insight.b360.eu.autodesk.com)
The property, ModelPath.Region, returns the region of the account and project which contains this model. `ModelPathUtils.CloudRegionUS` and `ModelPathUtils.CloudRegionEMEA` return the region names of different Autodesk cloud services. They can be used as the first argument of the ModelPathUtils.ConvertCloudGUIDsToCloudPath() method.
## Open
To open a cloud-hosted model with `Application.OpenDocumentFile` a `ModelPath` is needed. Such a ModelPath is returned by the method `ModelPathUtils.ConvertCloudGUIDsToCloudPath()` whose inputs are a region, ProjectGUID, and ModelGUID.
* Document.CloudModelGUID returns the Model GUID if it is stored in the cloud.
* ModelPath.GetProjectGUID() returns the Project GUID.
* Document.GetWorksharingCentralModelPath() returns the model path of the central model.
### Getting the CloudPath for a Model
The region argument for ConvertCloudGUIDsToCloudPath is a string type and should be either "US" or "EMEA", depending on which Autodesk Construction Cloud or Autodesk Docs region account and project the model is stored in.
* US - [Autodesk Insight](https://insight.b360.autodesk.com) \- ModelPathUtils.CloudRegionUS
* EU - [Autodesk Insight](https://insight.b360.eu.autodesk.com) \- ModelPathUtils.CloudRegionEMEA
Depending on where the cloud model is stored, provide the appropriate region argument "US" or "EMEA", respectively.
To get a valid CloudPath with the Revit API call `ModelPathUtils.ConvertCloudGUIDsToCloudPath()`. You will need to register a Autodesk Platform Services application and use the Autodesk Platform Services Data Management API to get the project Guid and model Guid as the other two arguments.
The [Autodesk Platform Services DM API reference on GET hubs](https://forge.autodesk.com/en/docs/data/v2/reference/http/hubs-GET) shows how to list the hubs your Autodesk Platform Services application can access. You can filter out the accounts of interest using the `data.attributes.name` field. You can also get the region information here.
The [Autodesk Platform Services DM API reference on GET project folder contents](https://forge.autodesk.com/en/docs/data/v2/reference/http/projects-project_id-folders-folder_id-contents-GET) shows how to list the folder contents you plan to open. You can filter out the relevant cloud model using the `included.attributes.name` field; the project Guid and model Guid information is provided in the `included.attributes.extension.data` field.
With these three pieces of information - region, project guid, and model guid - you can obtain a valid cloud path with the ModelPathUtils.ConvertCloudGUIDsToCloudPath method and then open the model with the OpenDocument or OpenAndActivateDocument methods.
### Getting the Autodesk Platform Services ID for a Model
These methods allow you to identify the Autodesk Platform Services IDs for Cloud Models:
* Document.GetHubId(): Autodesk Platform Services hub id where the model is located
* Document.GetProjectId(): Autodesk Platform Services project id where the model is located
* Document.GetCloudFolderId(bool forceRefresh): Autodesk Platform Services folder id where the model is located
* Document.GetCloudModelUrn(): A Autodesk Platform ServicesDM Urn identifying the model
They return strings which will be empty for a document which is not a cloud model.
### IOpenFromCloudCallback
An implementation of interface `IOpenFromCloudCallback` can be specified to control Revit's behavior when opening the cloud model. `IOpenFromCloudCallback.OnOpenConflict` method is called when a conflict happens during the model opening.
It receives a value of enum `OpenConflictScenario` that describes the conflict:
* Rollback indicates that the Central model is restored to an earlier version.
* Relinquished indicates that Ownership to model elements is relinquished.
* OutOfDate indicates that the model is out of date.
* VersionArchived indicates that last central version merged into the local model to open has been archived in the central model. Editing is limited to elements and worksets the user owns until Reload Latest or Synchronize with Central is conducted after the model is opened.
And it returns a value of enum `OpenConflictResult` that describes the action Revit should take:
* KeepLocalChanges - Keeps the local changes and open the model
* DiscardLocalChangesAndOpenLatestVersion - Discard the local changes and open the latest version of the model
* DetachFromCentral - Detach the local model from its central model, with worksets preserved
* Cancel
`DefaultOpenFromCloudCallback` class is the default callback used by an overload of the Application.OpenDocumentFile method. `DiscardLocalChangesAndOpenLatestVersion` is returned for all kinds of conflicts.
## Save
* Document.SaveAsCloudModel() saves the current model as a cloud model and supports upload of local workshared file into Autodesk Construction Cloud as a Revit Cloud Worksharing central model.
* Document.SaveCloudModel() saves the current cloud model.
To save a local Revit file to the cloud as a workshared or non-workshared cloud model, you need to get the Autodesk Construction Cloud or Autodesk Docs account id, project id, folder id, and a model name. There are two ways to retrieve this information:
1. From the web browser
2. Using the Autodesk Platform Services DM API
### SaveAsCloudModel Information from the Web Browser
Open a web browser, navigate to your project home page, and copy the URL:
The account id and project id are both GUID strings.
They can be extracted from the URL like this:
Navigate to your target Autodesk Docs folder in the web browser and copy the URL:
The folder id is embedded in this URL; in this example, it is "urn:adsk.wipprod:fs.folder:co.Foe4ZYNhTTKOhCqKApQkoQ":
With this information, you can save a local file which is opened in Revit to Autodesk document management as a cloud model with a call like this:
public void SaveAsCloud(Document currentDocument)
{
Guid account = new Guid("a8d3b76e-cf23-4dd7-a090-9e893efcf949");
Guid project = new Guid("bf46f5e3-285e-496f-be03-b5b1f8b1e154");
string folder_id = "urn:adsk.wipemea:fs.folder:co.Jo68ieLRRcKvQr4fI2Q8uQ";
string model_name = "rac_advanced_sample_project.rvt";
currentDocument.SaveAsCloudModel(
account, // account id
project, // project id
folder_id, // folder id
model_name // model name
);
}
### SaveAsCloudModel Information with Autodesk Platform Services DM API
With your Autodesk Platform Services application, you can:
* List hubs with the [GET hubs API](https://forge.autodesk.com/en/docs/data/v2/reference/http/hubs-GET) to retrieve the region and account ids.
* List projects the [GET projects API](https://forge.autodesk.com/en/docs/data/v2/reference/http/hubs-hub_id-projects-GET) to get all the projects of the given hub and their project ids.
* List the top folders with the [GET top folders API](https://forge.autodesk.com/en/docs/data/v2/reference/http/hubs-hub_id-projects-project_id-topFolders-GET) to get all accessible top folders (depending on permission) and you their valid folder ids, or continue to get the nested folders with the [list folder contents API](https://forge.autodesk.com/en/docs/data/v2/reference/http/projects-project_id-folders-folder_id-contents-GET) until the target folder and its folder id is found and can be stored for later use.
With this information, you can save a local file opened in Revit to Autodesk document management as a cloud model using the same Revit API call as above.
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

79
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_Functions_Default_Types_html.md Normal file
View File

@@ -0,0 +1,79 @@
# Default Types
# Default Types
Revit has a default type for different categories. This default type is shown in the Revit User Interface when the related tool is invoked to create an element of this category. The Revit API exposes the default type for both family and non-family types via the Document class.
## Family Types
The document members listed in the table below provide access to the default type for a given family category id.
Document Method | Description
---|---
GetDefaultFamilyTypeId() | Gets the default family type id associated to the given family category id.
SetDefaultFamilyTypeId() | Sets the default family type id associated to the given family category id.
IsDefaultFamilyTypeIdValid() | Checks whether the family type id is valid to set as default for the given family category id.
Additionally, given an ElementType, the ElementType.IsValidDefaultFamilyType() identifies if it is a valid default family type for the given family category id.
The example below demonstrates how to get the default family type Id for the structural column category. It then gets the family symbol for the default type and assigns it to a given column.
Code Region: Get default family type id
---
private void AssignDefaultTypeToColumn(Document document, FamilyInstance column)
{
ElementId defaultTypeId = document.GetDefaultFamilyTypeId(new ElementId(BuiltInCategory.OST_StructuralColumns));
if (defaultTypeId != ElementId.InvalidElementId)
{
FamilySymbol defaultType = document.GetElement(defaultTypeId) as FamilySymbol;
if (defaultType != null)
{
column.Symbol = defaultType;
}
}
}
The next example sets the default type for the doors category from a given door, after first checking that it is a valid default family type id.
Code Region: Set default family type id
---
private void SetDefaultTypeFromDoor(Document document, FamilyInstance door)
{
ElementId doorCategoryId = new ElementId(BuiltInCategory.OST_Doors);
// It is necessary to test the type suitability to be a default family type, for not every type can be set as default.
// Trying to set a non-qualifying default type will cause an exception
if (door.Symbol.IsValidDefaultFamilyType(doorCategoryId))
{
document.SetDefaultFamilyTypeId(doorCategoryId, door.Symbol.Id);
}
}
## Non-family Types
The document members in the table below provide access to the default types for non-Family element types.
Document Method | Description
---|---
GetDefaultElementTypeId() | Gets the default element type id for a given non-Family element type.
SetDefaultElementTypeId() | Sets the default element type id for a given non-Family element type.
IsDefaultElementTypeIdValid() | Checks whether the element type id is valid for a given non-Family element type.
The example below checks whether a given wall is using the default element type for wall types.
Code Region: Get default element type id
---
private bool IsWallUsingDefaultType(Document document, Wall wall)
{
ElementId defaultElementTypeId = document.GetDefaultElementTypeId(ElementTypeGroup.WallType);
return (wall.WallType.Id == defaultElementTypeId);
}
**Parent page:** [Document Functions](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_Functions_html.html)

101
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_Functions_html.md Normal file
View File

@@ -0,0 +1,101 @@
# Document Functions
# Document Functions
Document stores the Revit Elements, manages the data, and updates multiple data views. The Document class mainly provides the following functions.
## Document
The Document class represents an open Autodesk Revit project.
### Settings Property
The Settings property returns an object that provides access to general components within Revit projects. For more details, see [Settings](./Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Settings_html.html).
### Place and Locations
Each project has only one site location that identifies the physical project location on Earth. There can be several project locations for one project. Each location is an offset, or rotation, of the site location. For more details, see [Place and Locations](../../Advanced_Topics/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Place_and_Locations_html.html).
### View Management
A project document can have multiple views. The ActiveView property returns a View object representing the active view. You can filter the elements in the project to retrieve other views. For more details, see [Views](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Views_html.html).
### Element Retrieval
The Document object stores elements in the project. Retrieve specific elements by ElementId or UniqueId using the Element property.
For more details, see [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html).
### File Management
Each Document object represents a Revit project file. Document provides the following functions:
* Retrieve file information such as file path name and project title.
* Provides Close() and Save() methods to close and save the document.
For more details, see [Document and File Management](./Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_and_File_Management_html.html).
### Element Management
Revit maintains all Element objects in a project. To create new elements, use the Create property which returns an Object Factory used to create new project element instances in the Revit Platform API, such as FamilyInstance or Group.
The Document class can also be used to delete elements. Use the Delete() method to delete an element in the project. Deleted elements and any dependent elements are not displayed and are removed from the Document. References to deleted elements are invalid and cause an exception. For more details, see [Editing Elements](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Editing_Elements_html.html).
### Events
Events are raised on certain actions, such as when you save a project using Save or Save As. To capture the events and respond in the application, you must register the event handlers. For more details, see [Events](../../Appendices/Glossary/Revit_API_Revit_API_Developers_Guide_Appendices_Glossary_Events_html.html).
### Document Status
Several properties provide information on the status of the document:
* IsModifiable - whether the document may currently be modified (meaning that is there is an active transaction in the document and changes are not temporarily blocked by anything else)
* IsModified - whether the document was changed since it was opened or saved
* IsReadOnly - if true, the document is currently read-only and cannot be modified
* IsReadOnlyFile - whether the document was opened in read-only mode
* IsFamilyDocument - whether the document is a family document
* IsWorkshared - whether worksets have been enabled in the document
### Others
Document also provides other functions:
* ParameterBindings Property - Mapping between parameter definitions and categories. For more details, see [Shared Parameters](../../Basic_Interaction_with_Revit_Elements/Parameters/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_Shared_Parameters_html.html).
* ReactionsAreUpToDate Property - Reports whether the reactionary loads changed. For more details, see [Loads](../../Discipline_Specific_Functionality/Structural_Engineering/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_Structural_Engineering_Loads_html.html).
* Default Types - Access to the default types for family and non-family elements. For more details, see [Default Types](Document_Functions/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_Functions_Default_Types_html.html).
## UIDocument
The UIDocument class represents an Autodesk Revit project opened in the Revit user interface.
### Element Retrieval in UIDocument
Retrieve selected elements using the Selection property in UIDocument. This property returns an object representing the active selection containing the selected project elements. It also provides UI interaction methods to pick objects in the Revit model.
For more details, see [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html).
### Element Display
The ShowElements() method uses zoom to fit to focus in on one more elements.
### View Management in UIDocument
The UIDocument class can be used to refresh the active view in the active document by calling the RefreshActiveView() method. The ActiveView property can be used to retrieve or set the active view for the document. Changing the active view has some restrictions. It can only be used in an active document, which must not be in read-only state and must not be inside a transaction. Additionally, the active view may not be changed during the ViewActivating or ViewActivated event, or during any pre-action event, such as DocumentSaving, DocumentClosing, or other similar events.
The UIDocument.ActiveGraphicalView property retrieves the active graphical view for the document. Unlike UIDocument.ActiveView, this property will never return auxiliary views like the Project Browser or System Browser if the user has happened to make a selection in one of those views.
The UIDocument can also be used to get a list of all open view windows in the Revit user interface. The GetOpenUIViews method returns a list of UIViews which contain data about the view windows in the Revit user interface.
**Pages in this section**
* [Default Types](Document_Functions/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_Functions_Default_Types_html.html)
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

155
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_and_File_Management_html.md Normal file
View File

@@ -0,0 +1,155 @@
# Document and File Management
# Document and File Management
Document and file management make it easy to create and find your documents. For information about cloud-based Revit files, see [Cloud Models](Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_CloudFiles_html.html).
### Document Retrieval
The Application class maintains all documents. As previously mentioned, you can open more than one document in a session. The active document is retrieved using the UIApplication class property, ActiveUIDocument.
All open documents, including the active document, are retrieved using the Application class Documents property. The property returns a set containing all open documents in the Revit session.
### Document File Information
The Document class provides two properties for each corresponding file, PathName, and Title.
* PathName returns the document's fully qualified file path. The PathName returns an empty string if the project has not been saved since it was created.
* Title is the project title, which is usually derived from the project filename. The returned value varies based on your system settings.
### Basic File Info
BasicFileInfo provides fast access to basic information about a Revit file, including worksharing status, Revit version, username and central path. This is done without fully opening the file.
static BasicFileInfo.Extract(string file)
Returns a BasicFileInfo object whose properties provide information about the file.
Extract is not forward-compatible, meaning that Calling Extract from a version of Revit prior to Revit 2019 will result in an exception if it is called on a Revit 2019 or later file. This may occur again with future versions of Revit.
### Open a Document
The Application class provides an overloaded method to open an existing project file:
**Table 3: Open Document in API**
**Method** | **Event**
---|---
`Document OpenDocumentFile(string filename)` `Document OpenDocumentFile(ModelPath modelPath, OpenOptions openOptions)` `Document OpenDocumentFile(ModelPath modelPath, OpenOptions openOptions, IOpenFromCloudCallback openFromCloudCallback)` | DocumentOpened
When you specify a string with a fully qualified file path, Revit opens the file and creates a Document instance. Use this method to open a file on other computers by assigning the files Universal Naming Conversion (UNC) name to this method.
The file can be a project file with the extension .rvt, a family file with the extension .rfa, or a template file with the extension .rte.
The second overload takes a path to the model as a ModelPath rather than a string and the OpenOptions parameter offers options for opening the file, such as the ability to detach the opened document from central if applicable, as well as options related to worksharing. For more information about opening a workshared document, see [Opening a Workshared Document](../../Advanced_Topics/Worksharing/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Worksharing_Opening_a_Workshared_Document_html.html).
These methods throw specific documented exceptions in the event of a failure. Exceptions fall into 4 main categories.
**Table 4: Types of exceptions thrown**
**Type** | **Example**
---|---
Disk errors | File does not exist or is wrong version
Resource errors | Not enough memory or disk space to open file
Central model file errors | File is locked or corrupt
Central model/server errors | Network communication error with server
If the document is opened successfully, the DocumentOpened event is raised.
#### Create a Document
Create new documents using the Application methods in the following table.
**Table 5: Create Document in the API**
**Method** | **Event**
---|---
`Document NewProjectDocument(string templateFileName);` | DocumentCreated
`Document NewProjectDocument(UnitSystem unitSystem);` | DocumentCreated
`Document NewFamilyDocument(string templateFileName);` | DocumentCreated
`Document NewProjectTemplateDocument(string templateFilename);` | DocumentCreated
For the methods that require a template file name as a parameter, the created document is returned based on the template file. NewProjectDocument(UnitSystem)creates a new imperial or metric project document without a specified template.
#### Save and Close a Document
The Document class provides methods to save or close instances.
**Table 6: Save and Close Document in API**
**Method** | **Event**
---|---
Save() | DocumentSaved
SaveAs() | DocumentSavedAs
Close() | DocumentClosed
Save() has 2 overloads, one with no arguments and one with a SaveOptions argument that can specify whether to force the OS to delete all dead data from the file on disk. If the file has not been previously saved, SaveAs() must be called instead.
SaveAs() has 3 overloads. One overload takes only the filename as an argument and an exception will be thrown if another file exists with the given filename. The other 2 overloads takes a filename as an argument (in the form of a ModelPath in one case) as well as a second SaveAsOptions argument that can be used to specify whether to overwrite an existing file, if it exists. SaveAsOptions can also be used to specify other relevant options such as whether to remove dead data on disk related to the file and worksharing options.
Save() and SaveAs() throw specific documented exceptions in the same 4 categories as when opening a document and listed in Table 4 above.
Close() has two overloads. One takes a Boolean argument that indicates whether to save the file before closing it. The second overload takes no arguments and if the document was modified, the user will be asked if they want to save the file before closing. This method will throw an exception if the document's path name is not already set or if the saving target file is read-only.
Note: The Close() method does not affect the active document or raise the DocumentClosed event, because the document is used by an external application. You can only call this method on non-active documents.
The UIDocument class also provides methods to save and close instances.
**Table 7: Save and Close UIDocument in API**
**Method** | **Event**
---|---
SaveAndClose() | DocumentSaved, DocumentClosed
SaveAs() | DocumentSavedAs
SaveAndClose() closes the document after saving it. If the document's path name has not been set the "Save As" dialog will be shown to the Revit user to set its name and location.
The SaveAs() method saves the document to a file name and path obtained from the Revit user via the "Save As" dialog.
#### Document Preview
The DocumentPreviewSettings class can be obtained from the Document and contains the settings related to the saving of preview images for a given document.
**Code Region: Document Preview**
---
public void SaveActiveViewWithPreview(UIApplication application)
{
// Get the handle of current document.
Autodesk.Revit.DB.Document document = application.ActiveUIDocument.Document;
// Get the document's preview settings
DocumentPreviewSettings settings = document.GetDocumentPreviewSettings();
// Find a candidate 3D view
FilteredElementCollector collector = new FilteredElementCollector(document);
collector.OfClass(typeof(View3D));
Func<View3D, bool> isValidForPreview = v => settings.IsViewIdValidForPreview(v.Id);
View3D viewForPreview = collector.OfType<View3D>().First<View3D>(isValidForPreview);
// Set the preview settings
using (Transaction setTransaction = new Transaction(document, "Set preview view id"))
{
setTransaction.Start();
settings.PreviewViewId = viewForPreview.Id;
setTransaction.Commit();
}
// Save the document
document.Save();
}
#### Load Family
The Document class provides you with the ability to load an entire family and all of its symbols into the project. Because loading an entire family can take a long time and a lot of memory, the Document class provides a similar method, LoadFamilySymbol() to load only specified symbols.
For more details, see [Family](../../Revit_Geometric_Elements/Family_Instances/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Family_Instances_Family_html.html).
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

48
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_ForgeTypeId_html.md Normal file
View File

@@ -0,0 +1,48 @@
# ForgeTypeId
# ForgeTypeId
`Autodesk.Revit.DB.ForgeTypeId` is an extensible identifier for a unit, symbol, or other object, and is used throughout the Revit API to identify data such as units of measurement, symbols, and unit types. Unit types are referred to as "specs" to avoid confusion with units themselves.
A `ForgeTypeId` instance holds a string, called a "typeid", that uniquely identifies a Forge schema. A Forge schema is a JSON document describing a data structure, supporting data interchange between applications. A typeid string includes a namespace and version number such as:
* `autodesk.spec.aec:length-1.0.0`
* `autodesk.unit.unit:meters-1.0.0`
* `autodesk.revit.category.local:walls-1.0.0`
By default, comparison of ForgeTypeId values in the Revit API ignores the version number.
The members of the following classes have a ForgeTypeId data type:
* DisciplineTypeId - Product disciplines used in the Revit UI such as Architecture, Electrical, HVAC, Piping, and Structural
* GroupTypeId - Groupings used for parameters in the Revit UI such as Construction, General, Geometry, IdentityData
* ParameterTypeId - Type of parameters such as AllModelInstanceComments, InstanceSillHeightParam, WallTopOffset
* SpecTypeId - Type of quantity to be measured such as Area, Currency, HvacDensity, Wattage
* SymbolTypeId - Unit symbol displayed in the formatted string representation of a number to indicate the units of the value, such as DegreeC, Ft, KipPerFt, MSup2
* UnitTypeId - Units and display format used to format numbers as strings or convert units such as Acres, Degrees, Feet, Liters
For example, the following properties all have a ForgeTypeId data type:
* DisciplineTypeId.Architecture
* GroupTypeId.Constraints
* ParameterTypeId.WallTopOffset
* SpecTypeId.Volume
* SymbolTypeId.Hour
* UnitTypeId.Millimeters
These static methods convert a BuiltInCategory to a ForgeTypeId and vice versa:
* Category.GetBuiltInCategoryTypeId(BuiltInCategory)
* Category.GetBuiltInCategory(ForgeTypeId)
For example, `Category.GetBuiltInCategoryTypeId(BuiltInCategory.OST_Furniture)` returns a `ForgeTypeId` with a `TypeId` equal to `autodesk.revit.category.family:furniture-1.0.0`.
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

101
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Import_html.md Normal file
View File

@@ -0,0 +1,101 @@
# Import Functions
# Import Functions
The overloads for the `Document.Import` method allow several different file types to be imported.
## CAD file import
* Import(String, SATImportOptions, View) - Imports an SAT file into the document.
* Import(String, SKPImportOptions, View) - Imports an SKP file into the document.
* Import(String, DGNImportOptions, View, out ElementId) - Imports a DGN file to the document.
* Import(String, DWGImportOptions, View, out ElementId) - Imports a DWG or DXF file to the document.
## GBXML import
* Import(String, GBXMLImportOptions)
## Images and PDF import
Revit can import images (JPG, PNG, etc) and raster images generated from PDF files.
The class `ImageInstance` represents an instance of an ImageType placed in a view. Its members include:
* Create(Document, View, ElementId, ImagePlacementOptions) - The ImagePlacementOptions describes where an image instance should be placed in a view.
* GetLocation(BoxPlacement) - The BoxPlacment enumeration is used to specify which corner (or the center) of the image the location pertains to.
* SetLocation(XYZ, BoxPlacement)
* property Width
* property Height
* property EnableSnaps
The class `ImageType` represents a type containing an image. Its members include:
* Create(Document, ImageTypeOptions)
* CanReload() - validates the corresponding image or PDF file and performs additional validation if the file is served by an external provider.
* ReloadFrom(ImageTypeOptions)
* property ExternalResourceType - the type of external resources that represents images (and PDF files).
* property PageNumber
* property PathType - the type of path that was used to refer to the file from which the ImageType was loaded.
The class `ImageTypeOptions` represents the options that are used when creating or reloading an ImageType, which contains image data corresponding to an image or PDF file. Its members include:
* IsValid() - tests whether ImageTypeOptions can be used to create or reload an ImageType; additional validation is performed for PDF files and external files.
* property PageNumber
* property Path
* property Resolution - is measured in dpi and relates the number of pixels in raster images to their size.
* setExternalResourceReference() - specifies the location of an image or PDF file using an external resource reference.
ImageTypeOptions can be used to specify a local file or a file served by an external provider. Local files can be referred to using relative paths. For PDF files, ImageType loads a single page at a time, which is rasterized at the resolution specified in ImageTypeOptions.
The class `ImagePlacementOptions` is used to describe where an ImageInstance should be placed in a view.
* ImagePlacementOptions() constructs a new ImagePlacementOptions that will place an ImageInstance with its center at the origin of the model.
* ImagePlacementOptions(XYZ, BoxPlacement) constructs a new ImagePlacementOptions with the provided Location and PlacementPoint.
* Location specifies where a point of the ImageInstance, determined by the PlacementPoint property, is going to be inserted.
* PlacementPoint uses a `BoxPlacement` to identify which point of the ImageInstance will be aligned to the Location.
### Converting images between links and imports
`ImageTypeOptions.SourceType` along with the new enumerated value `ImageTypeSource` and `ImageType.ReloadFrom()` allow you to create or convert an ImageType to a link or import.
The overall process is:
* Create a new ImageTypeOptions instance from the existing ImageType properties.
* Modify the ImagesTypeOptions, for example by changing the ImageTypeOptions.SourceType between Link and Import, or change the path with ImageTypeOptions.SetPath().
* Use those new ImageTypeOptions in ImageType.ReloadFrom.
ImageType properties include:
* ImageType.Source - Indicates how the image is created (as a link, import, or internally-generated image).
* ImageType.Status - Indicates whether the image is loaded or unloaded (if applicable).
Two constructors take an ImageTypeSource as an argument:
* ImageTypeOptions(String, Boolean, ImageTypeSource)
* ImageTypeOptions(ExternalResourceReference, ImageTypeSource)
The enumeration: `ImageTypeStatus` contains possible values for the load status of an ImageType.
## Rhino
`Document.Import(String, ImportOptions3DM, View)` and `Document.Link(String, ImportOptions3DM, View)` import or link a 3DM file into the document.
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

46
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Settings_html.md Normal file
View File

@@ -0,0 +1,46 @@
# Settings
# Settings
The following table identifies the commands in the Revit Platform UI Manage tab, and corresponding APIs.
**Table 7: Settings in API and UI**
| |
---|---|---
UI command | Associated API | Reference
Settings → Project Information | Document.ProjectInformation | See the following note
Settings → Project Parameters | Document.ParameterBindings (Only for Shared Parameter) | See [Shared Parameters](../../Basic_Interaction_with_Revit_Elements/Parameters/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_Shared_Parameters_html.html)
Project Location panel | Document.ProjectLocations Document.ActiveProjectLocation | [Place and Locations](../../Advanced_Topics/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Place_and_Locations_html.html)
Settings → Additional Settings → Fill Patterns | FilteredElementCollector filtering on class FillPatternElement | See the following note
Settings → Materials | FilteredElementCollector filtering on class Material | See [Material Management](../../Revit_Geometric_Elements/Material/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Material_Material_Management_html.html)
Settings → Object Styles | Document.Settings.Categories | See the following note
Phasing → Phases | Document.Phases | See the following note
Settings → Structural Settings | Loads and related structural settings are available in the API | See [Structural Engineering](../../Discipline_Specific_Functionality/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_Structural_Engineering_html.html)
Settings → Project Units | Document.GetUnits() | See [Units](./Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Units_html.html)
Area and Volume Calculations (on the Room & Area panel) | AreaVolumeSettings.GetAreaVolumeSettings() | See the following note
Note: Project Information - The API provides the ProjectInfo class which is retrieved using Document.ProjectInformation to represent project information in the Revit project. The following table identifies the corresponding APIs for the Project Information parameters.
**Table 8: ProjectInformation**
**Parameters** | **Corresponding API** | **Built-in Parameters**
---|---|---
Project Issue Date | ProjectInfo.IssueDate | PROJECT_ISSUE_DATE
Project Status | ProjectInfo.Status | PROJECT_STATUS
Client Name | ProjectInfo.ClientName | CLIENT_NAME
Project Address | ProjectInfo.Address | PROJECT_ADDRESS
Project Name | ProjectInfo.Name | PROJECT_NAME
Project Number | ProjectInfo.Number | PROJECT_NUMBER
Use the properties exposed by ProjectInfo to retrieve and set all strings. These properties are implemented by the corresponding built-in parameters. You can get or set the values through built-in parameters directly. For more information about how to gain access to these parameters through the built-in parameters, see [Parameter](../../Basic_Interaction_with_Revit_Elements/Parameters/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_Parameter_html.html) in the [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html) section. The recommended way to get project information is to use the ProjectInfo properties.
* Fill Patterns - Retrieve all Fill Patterns in the current document using a FilteredElementCollector filtering on class FillPatternElement. Specific FillPatterns can be retrieved using the static methods FillPatternElement.GetFillPattern(Document, ElementId) or FillPatternElement.GetFillPatternByName (Document, string).
* Object Styles - Use Settings.Categories to retrieve all information in Category objects except for Line Style. For more details, see [Other Classifications](../Elements_Essentials/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Other_Classifications_html.html) in the [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html) and [Material](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Material_html.html) sections.
* Phases - Revit maintains the element lifetime by phases, which are distinct time periods in the project lifecycle. All phases in a document are retrieved using the Document.Phases property. The property returns an array containing Phase class instances. However, the Revit API does not expose functions from the Phase class.
* Options - The Options command configures project global settings. You can retrieve an Options.Application instance using the Application.Options property. Currently, the Options.Application class only supports access to library paths and shared parameters file.
* Area and Volume Calculations - The AreaVolumeSettings class allows you to enable or disable volume calculations, and to change the room boundary location.
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

141
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Units_html.md Normal file
View File

@@ -0,0 +1,141 @@
# Units
# Units
The two main classes in the Revit API for working with units are Units and FormatOptions. The Units class represents a document's default settings for formatting numbers with units as strings. It contains a FormatOptions object for each unit type as well as settings related to decimal symbol and digit grouping.
The `Units` class stores a `FormatOptions` object for every valid unit type, but not all of them can be directly modified. Some, like `SpecTypeId.Number` and `SpecTypeId.SiteAngle`, have fixed definitions. Others have definitions which are automatically derived from other unit types. For example, `SpecTypeId.SheetLength` is derived from `SpecTypeId.Length` and `SpecTypeId.ForceScale` is derived from `SpecTypeId.Force`.
The FormatOptions class contains settings that control how to format numbers with units as strings. It contains those settings that are typically chosen by an end-user in the Format dialog and stored in the document, such as rounding, accuracy, display units, and whether to suppress spaces or leading or trailing zeros.
The FormatOptions class is used in two different ways. A FormatOptions object in the Units class represents the default settings for the document. A FormatOptions object used elsewhere represents settings that may optionally override the default settings.
The UseDefault property controls whether a FormatOptions object represents default or custom formatting. If UseDefault is true, formatting will be according to the default settings in the Units class, and none of the other settings in the object are meaningful. If UseDefault is false, the object contains custom settings that override the default settings in the Units class. UseDefault is always false for FormatOptions objects in the Units class.
## Unit Conversion
The Revit API provides utility classes to facilitate working with quantities in Revit. The UnitUtils class makes it easy to convert unit data to and from Revit's internal units.
The UnitUtils class offers a set of methods for mapping between enumeration values and ForgeTypeId values to assist clients in migrating code to ForgeTypeId such as:
* UnitUtils.GetDiscipline()
* UnitUtils.IsMeasurableSpec()
* UnitUtils.IsSymbol()
Revit has seven base quantities, each with its own internal unit. These internal units are identified in the following table.
**Table 9: 7 Base Units in Revit Unit System**
**Base Unit** | **Unit In Revit** | **Unit System**
---|---|---
Length | Feet (ft) | Imperial
Angle | Radian | Metric
Mass | Kilogram (kg) | Metric
Time | Seconds (s) | Metric
Electric Current | Ampere (A) | Metric
Temperature | Kelvin (K) | Metric
Luminous Intensity | Candela (cd) | Metric
Note: Since Revit stores lengths in feet and other basic quantities in metric units, a derived unit involving length will be a non-standard unit based on both the Imperial and the Metric systems. For example, since a force is measured in "mass-length per time squared", it is stored in kg-ft / s2. The following example uses the UnitUtils.ConvertFromInternalUnits() method to get the minimum yield stress for a material in kips per square inch.
**Code Region: Converting from Revit's internal units**
---
double GetYieldStressInKsi(Material material)
{
double dMinYieldStress = 0;
// Get the structural asset for the material
ElementId strucAssetId = material.StructuralAssetId;
if (strucAssetId != ElementId.InvalidElementId)
{
PropertySetElement pse = material.Document.GetElement(strucAssetId) as PropertySetElement;
if (pse != null)
{
StructuralAsset asset = pse.GetStructuralAsset();
// Get the min yield stress and convert to ksi
dMinYieldStress = asset.MinimumYieldStress;
dMinYieldStress = UnitUtils.ConvertFromInternalUnits(dMinYieldStress,
UnitTypeId.KipsPerSquareInch);
}
}
return dMinYieldStress;
}
The UnitUtils can also be used to convert a value from one unit type to another, such as square feet to square meters. In the following example, a wall's top offset value that was entered in inches is converted to feet, the expected unit for setting that value.
**Code Region: Converting between units**
---
void SetTopOffset(Wall wall, double dOffsetInches)
{
// convert user-defined offset value to feet from inches prior to setting
double dOffsetFeet = UnitUtils.Convert(dOffsetInches,
UnitTypeId.Inches,
UnitTypeId.Feet);
Parameter paramTopOffset = wall.GetParameter(ParameterTypeId.WallTopOffset);
paramTopOffset.Set(dOffsetFeet);
}
### Unit formatting and parsing
Another utility class, UnitFormatUtils, can format data or parse formatted unit data.
The overloaded method Format() can be used to format a value into a string based on formatting options as the following example demonstrates. The material density is retrieved and then the value is then converted to a user-friendly value with unit using the Format() method.
**Code Region: Format value to string**
---
void DisplayDensityOfMaterial(Material material)
{
double density = 0;
// get structural asset of material in order to get the density
ElementId strucAssetId = material.StructuralAssetId;
if (strucAssetId != ElementId.InvalidElementId)
{
PropertySetElement pse = material.Document.GetElement(strucAssetId) as PropertySetElement;
if (pse != null)
{
StructuralAsset asset = pse.GetStructuralAsset();
density = asset.Density;
// convert the density value to a user readable string that includes the units
Autodesk.Revit.DB.Units units = material.Document.GetUnits();
// false for maxAccuracy means accuracy specified by the FormatOptions should be used
// false for forEditing since this will be for display only and no formatting modifications are necessary
string strDensity = UnitFormatUtils.Format(units, SpecTypeId.UnitWeight, density, false);
string msg = string.Format("Raw Value: {0}\r\nFormatted Value: {1}", density, strDensity);
TaskDialog.Show("Material Density", msg);
}
}
}
The overloaded UnitFormatUtils.TryParse() method parses a formatted string, including units, into a value if possible, using the Revit internal units of the specified unit type. The following example takes a user entered length value, assumed to be a number and length unit, and attempts to parse it into a length value. The result is compared with the input string in a TaskDialog for demonstration purposes.
**Code Region: Parse string**
---
double GetLengthInput(Document document, String userInputLength)
{
double dParsedLength = 0;
Autodesk.Revit.DB.Units units = document.GetUnits();
// try to parse a user entered string (i.e. 100 mm, 1'6")
bool parsed = UnitFormatUtils.TryParse(units, SpecTypeId.Length, userInputLength, out dParsedLength);
if (parsed == true)
{
string msg = string.Format("User Input: {0}\r\nParsed value: {1}", userInputLength, dParsedLength);
TaskDialog.Show("Parsed Data", msg);
}
return dParsedLength;
}
**Parent page:** [Application and Document](../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html)

32
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.md Normal file
View File

@@ -0,0 +1,32 @@
# Application and Document
# Application and Document
The top level objects in the Revit Platform API are application and document. These are represented by the classes Application, UIApplication, Document and UIDocument.
* The application object refers to an individual Revit session, providing access to documents, options, and other application-wide data and settings.
* Autodesk.Revit.UI.UIApplication - provides access to UI-level interfaces for the application, including the ability to add RibbonPanels to the user interface, and the ability to obtain the active document in the user interface.
* Autodesk.Revit.ApplicationServices.Application - provides access to all other application level properties.
* The document object is a single Revit project file representing a building model. Revit can have multiple projects open and multiple views for one project.
* Autodesk.Revit.UI.UIDocument - provides access to UI-level interfaces for the document, such as the contents of the selection and the ability to prompt the user to make selections and pick points.
* Autodesk.Revit.DB.Document - provides access to all other document level properties.
* If multiple documents are open, the active document is the one whose view is active in the Revit session.
This chapter identifies all Application and Document functions, and then focuses on file management, settings, and units. For more details about the Element class, refer to [Elements Essentials](./Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html)s and [Editing Elements](../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Editing_Elements_html.html) and refer to the [Views](../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Views_html.html) for more details about the view elements.
**Pages in this section**
* [Application Functions](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Application_Functions_html.html)
* [Document Functions](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_Functions_html.html)
* [Document and File Management](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Document_and_File_Management_html.html)
* [ForgeTypeId](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_ForgeTypeId_html.html)
* [Import Functions](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Import_html.html)
* [Settings](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Settings_html.html)
* [Units](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_Units_html.html)
* [Cloud Models](Application_and_Document/Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_CloudFiles_html.html)
**Parent page:** [Introduction](../Revit_API_Revit_API_Developers_Guide_Introduction_html.html)

67
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Element_Classification_html.md Normal file
View File

@@ -0,0 +1,67 @@
# Element Classification
# Element Classification
Revit Elements are divided into six groups: Model, View, Group, Annotation, Sketch, and Information. Each group contains related Elements and their corresponding symbols.
### Model Elements
Model Elements represent physical items that exist in a building project. Elements in the Model Elements group can be subdivided into the following:
* Family Instances - Family Instances contain family instance objects. You can load family objects into your project or create them from family templates. For more information, see [Family Instances](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Family_Instances_html.html).
* Host Elements - Host Elements contain system family objects that can contain other model elements, such as wall, roof, ceiling, and floor. For more information about Host Elements, see [Walls, Floors, Roofs and Openings](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Walls_Floors_Ceilings_Roofs_and_Openings_html.html).
* Structure Elements. - Structure Elements contain elements that are only used in the structural features of Revit. For more information about Structure Elements, see [Structural Engineering](../../Discipline_Specific_Functionality/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_Structural_Engineering_html.html).
### View Elements
View Elements represent the way you view and interact with other objects in Revit. For more information, see [Views](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Views_html.html).
### Group Elements
Group Elements represent the assistant Elements such as Array and Group objects in Revit. For more information, see [Editing Elements](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Editing_Elements_html.html).
### Annotation and Datum Elements
Annotation and Datum Elements contain non-physical items that are visible.
* Annotation Elements represent 2D components that maintain scale on paper and are only visible in one view. For more information about Annotation Elements, see [Annotation Elements](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Annotation_Elements_html.html).
**Note:** Annotation Elements representing 2D components do not exist only in 2D views. For example, dimensions can be drawn in 3D view while the shape they refer to only exists in a 2D planar face.
Datum Elements represent non-physical items that are used to establish project context. These elements can exist in views. Datum Elements are further divided into the following:
* Common Datum Elements - Common Datum Elements represent non-physical visible items used to store data for modeling.
* Datum FamilyInstance - Datum FamilyInstance represents non-physical visible items loaded into your project or created from family templates. NoteFor more information about Common Datum Elements and Datum FamilyInstance, see [Datum and Information Elements](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Datum_and_Information_Elements_html.html); for ModelCurve related contents, see [Sketching](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Sketching_html.html).
* Structural Datum Elements - Structural Datum Elements represent non-physical visible items used to store data for structure modeling. For more information about Structural Datum Elements, see [Structural Engineering](../../Discipline_Specific_Functionality/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_Structural_Engineering_html.html).
### Sketch Elements
Sketch Elements represent temporary items used to sketch 2D/3D form. This group contains the following objects used in family modeling and massing:
* SketchPlane
* Sketch
* Path3D
* GenericForm
For Sketch details, see [Sketching](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Sketching_html.html).
### Information Elements
Information Elements contain non-physical invisible items used to store project and application data. Information Elements are further separated into the following:
* Project Datum Elements
* Project Datum Elements (Unique)
For more information about Datum Elements, see [Datum and Information Elements](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Datum_and_Information_Elements_html.html).
**Parent page:** [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html)

41
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Element_Retrieval_html.md Normal file
View File

@@ -0,0 +1,41 @@
# Element Retrieval
# Element Retrieval
Elements in Revit are very common. Retrieving the elements that you want from Revit is necessary before using the API for any Element command. There are several ways to retrieve elements with the Revit API:
* ElementId - If the ElementId of the element is known, the element can be retrieved from the document.
* Element filtering and iteration - This is a good way to retrieve a set of related elements in the document.
* Selected elements - Retrieves the set of elements that the user has selected.
* Specific elements - Some elements are available as properties of the document.
Each of these methods of element retrieval is discussed in more details in the following sections.
### Getting an Element by ID
When the ElementId of the desired element is known, use the Document.Element property to get the element.
### Filtering the Elements Collection
The most common way to get elements in the document is to use filtering to retrieve a collection of elements. The Revit API provides the FilteredElementCollector class, and supporting classes, to create filtered collections of element which can then be iterated. See [Filtering](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Filtering_html.html) for more information.
### Selection
Rather than getting a filtered collection of all of the elements in the model, you can access just the elements that have been selected. You can get the selected objects from the current active document using the UIDocument.Selection.GetElementIds method. For more information on using the active selection, see [Selection](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Selection_html.html).
### Accessing Specific Elements from Document
In addition to using the general way to access Elements, the Revit Platform API has properties in the Document class to get the specified Elements from the current active document without iterating all Elements. The specified Elements you can retrieve are listed in the following table.
**Table 11: Retrieving Elements from document properties**
**Element** | **Access in property of Document**
---|---
ProjectInfo | Document.ProjectInformation
ProjectLocation | Document.ProjectLocations Document.ActiveProjectLocation
SiteLocation | Document.SiteLocation
Phase | Document.Phases
**Parent page:** [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html)

155
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_General_Properties_html.md Normal file
View File

@@ -0,0 +1,155 @@
# General Properties
# General Properties
The following properties are common to each Element created using Revit.
### ElementId
Every element in an active document has a unique identifier represented by the ElementId storage type. ElementId objects are project wide. It is a unique number that is never changed in the element model, which allows it to be stored externally to retrieve the element when needed.
In the Revit Platform API, you can create an ElementId directly, and then associate a unique integer value to the new ElementId. The new ElementId value is 0 by default.
**Code Region 5-3: Setting ElementId**
---
private void SetElementId(Element element)
{
// Get the id of the element
Autodesk.Revit.DB.ElementId selectedId = element.Id;
long idLong = selectedId.Value;
// create a new id and set the value
Autodesk.Revit.DB.ElementId id = new Autodesk.Revit.DB.ElementId(idLong);
}
ElementId has the following uses:
* Use ElementId to retrieve a specific element from Revit. From the Revit Application class, gain access to the active document, and then get the specified element using the Document.GetElement(ElementId) method.
**Code Region 5-4: Using ElementId**
---
public void UsingElementId(Element element)
{
// Get the id of the element
Autodesk.Revit.DB.ElementId selectedId = element.Id;
int idLong = selectedId.Value;
// create a new id and set the value
Autodesk.Revit.DB.ElementId id = new Autodesk.Revit.DB.ElementId(idLong);
// Get the element
Autodesk.Revit.DB.Element first = element.Document.GetElement(id);
}
If the ID number does not exist in the project, the element you retrieve is null.
* Use ElementId to check whether two Elements in one project are equal or not. It is not recommended to use the Object.Equal() method.
### UniqueId
Every element has a UniqueId, represented by the String storage type. The UniqueId corresponds to the ElementId. However, unlike ElementId, UniqueId functions like a GUID (Globally Unique Identifier), which is unique across separate Revit projects. UniqueId can help you to track elements when you export Revit project files to other formats.
**Code Region 5-5: UniqueId**
---
`string uniqueId = element.UniqueId;`
Note: The ElementId is only unique in the current project. It is not unique across separate Revit projects. UniqueId is always unique across separate projects.
### Location
The location of an object is important in the building modeling process. In Revit, some objects have a point location. For example, a table has a point location. Other objects have a line location, representing a location curve or no location at all. A wall is an element that has a line location.
The Revit Platform API provides the Location class and location functionality for most elements. For example, it has the Move() and Rotate() methods to translate and rotate the elements. However, the Location class has no property from which you can get information such as a coordinate. In this situation, downcast the Location object to its subclass-like LocationPoint or LocationCurve-for more detailed location information and control using object derivatives.
Retrieving an element's physical location in a project is useful when you get the geometry of an object. The following rules apply when you retrieve a location:
* Wall, Beam, and Brace are curve-driven using LocationCurve.
* Room, RoomTag, SpotDimension, Group, FamilyInstances that are not curve-driven, and all In-Place-FamilyInstances use LocationPoint.
In the Revit Platform API, curve-driven means that the geometry or location of an element is determined by one or more associated curves. Almost all analytical model elements are curve-driven - linear and area loads, walls, framing elements, and so on.
Other Elements cannot retrieve a LocationCurve or LocationPoint. They return Location with no information.
**Table 12: Elements Location Information**
**Location Information** | **Elements**
---|---
LocationCurve | Wall, Beam, Brace, Structural Truss, LineLoad(without host)
LocationPoint | Room, RoomTag, SpotDimension, Group, Column, Mass
Only Location | Level, Floor, some Tags, BeamSystem, Rebar, Reinforcement, PointLoad, AreaLoad(without Host), Span Direction(IndependentTag)
No Location | View, LineLoad(with host), AreaLoad(with Host), BoundaryCondition
Note: There are other Elements without Location information. For example, a LineLoad (with host) or an AreaLoad (with host) have no Location.
Some FamilyInstance LocationPoints, such as all in-place-FamilyInstances and masses, are specified to point (0, 0, 0) when they are created. The LocationPoint coordinate is changed if you transform or move the instance.
To change a Group-s LocationPoint, do one of the following:
* Drag the Group origin in the Revit UI to change the LocationPoint coordinate. In this situation, the Group LocationPoint is changed while the Group-s location is not changed.
* Move the Group using the ElementTransformUtils.MoveElement() method to change the LocationPoint. This changes both the Group location and the LocationPoint.
For more information about LocationCurve and LocationPoint, see [Moving Elements](../../Basic_Interaction_with_Revit_Elements/Editing_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Editing_Elements_Moving_Elements_html.html).
### Level
Levels are finite horizontal planes that act as a reference for level-hosted or level-based elements, such as roofs, floors, and ceilings. The Revit Platform API provides a Level class to represent level lines in Revit. Get the Level object to which the element is assigned using the API if the element is level-based.
**Code Region 5-6: Assigning Level**
---
public void AssignLevel(Element element)
{
// Get the level object to which the element is assigned.
if (element.LevelId.Equals(ElementId.InvalidElementId))
{
TaskDialog.Show("Revit","The element isn't based on a level.");
}
else
{
Level level = element.Document.GetElement(element.LevelId) as Level;
// Format the prompt information(Name and elevation)
String prompt = "The element is based on a level.";
prompt += "\nThe level name is: " + level.Name;
prompt += "\nThe level elevation is: " + level.Elevation;
// Show the information to the user.
TaskDialog.Show("Revit",prompt);
}
}
A number of elements, such as a column, use a level as a basic reference. When you get the column level, the level you retrieve is the Base Level.
Note: Get the Beam or Brace level using the Reference Level parameter. From the Level property, you only get null instead of the reference level information.
Level is the most commonly used element in Revit. In the Revit Platform API, retrieve all levels using a Level class filter.
For more Level details, see [Datum and Information Elements](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Datum_and_Information_Elements_html.html).
### Parameter
Every element has a set of parameters that users can view and edit in Revit. The parameters are visible in the Element Properties dialog box (select any element and click the Properties button next to the type selector). For example, the following image shows Room parameters.
**Figure 25: Room parameters**
In the Revit Platform API, each Element object has a Parameters property, which is a collection of all the properties attached to the Element. You can change the property values in the collection. For example, you can get the area of a room from the room object parameters; additionally, you can set the room number using the room object parameters. The Parameter is another way to provide access to property information not exposed in the element object.
In general, every element parameter has an associated parameter ID. Parameter IDs are represented by the ElementId class. For user-created parameters, the IDs correspond to real elements in the document. However, most parameters are built-in and their IDs are constants stored in ElementIds.
Parameter is a generic form of data storage in elements. In the Revit Platform API, it is best to use the built-in parameter ID to get the parameter. Revit has a large number of built-in parameters available using the BuiltInParameter enumerated type.
For more details, see [Parameters](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_html.html).
**Parent page:** [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html)

184
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Other_Classifications_html.md Normal file
View File

@@ -0,0 +1,184 @@
# Other Classifications
# Other Classifications
Elements can be classified by Category, Family, Symbol and Instance.
There are some relationships between the classifications. For example:
* You can distinguish different kinds of FamilyInstances by the category. Items such as structural columns are in the Structural Columns category, beams and braces are in the Structural Framing category, and so on.
* You can differentiate structural FamilyInstance Elements by their symbol.
### Category
The Element.Category property represents the category or subcategory to which an Element belongs. It is used to identify the Element type. For example, anything in the walls Category is considered a wall. Other categories include doors and rooms.
Categories are the most general class. The Document.Settings.Categories property is a map that contains all Category objects in the document and is subdivided into the following:
* Model Categories - Model Categories include beams, columns, doors, windows, and walls.
* Annotation Categories. Annotation Categories include dimensions, grids, levels, and textnotes.
**Figure 20: Categories**
Note: The following guidelines apply to categories:
* In general, the following rules apply to categories:
* Each family object belongs to a category.
* Non-family objects, like materials and views, do not belong to a category.
* There are exceptions such as ProjectInfo, which belongs to the Project Information category.
* An element and its corresponding symbols are usually in the same category. For example, a basic wall and its wall type Generic - 8" are all in the Walls category.
* The same type of Elements can be in different categories. For example, SpotDimensions has the SpotDimensionType, but it can belong to two different categories: Spot Elevations and Spot Coordinates.
* Different Elements can be in the same category because of their similarity or for architectural reasons. ModelLine and DetailLine are in the Lines category.
To gain access to the categories you may access all categories from the document's Settings class (for example, to insert a new category set), or if you only need access to a category object associated with a built-in category, you may access the category object directly from the static overloaded GetCategory() method of the Category class.
To access categories:
* Get an entire map of Categories from the document properties: Document.Settings.Categories returns a CategoryNameMap containing a map of all Revit categories indexed by their name. `Category.IsVisibleInUI` returns true if the category is visible to the user in lists of categories in the Revit user interface (dialogs such as Visibility Graphics or View Filters)
* Get a specific built-in category by calling the appropriate overload of the static method Category.GetCategory().
* Get a specific category or subcategory by its ElementId by calling the corresponding overload of the static method Category.GetCategory().
**Code Region 5-1: Getting categories from document settings**
---
public void GetCategories(Document document)
{
// Get settings of current document
Settings documentSettings = document.Settings;
// Get all categories of current document
Categories groups = documentSettings.Categories;
// Show the number of all the categories to the user
String prompt = "Number of all categories in current Revit document:" + groups.Size;
// get Floor category according to OST_Floors and show its name
Category floorCategory = groups.get_Item(BuiltInCategory.OST_Floors);
prompt += floorCategory.Name;
// Give the user some information
TaskDialog.Show("Revit", prompt);
}
Category is used in the following manner:
* Category is used to classify elements. The element category determines certain behaviors. For example, all elements in the same category can be included in the same schedule.
* Elements have parameters based on their categories.
* Categories are also used for controlling visibility and graphical appearance in Revit.
**Figure 21: Visibility by Category**
An element's category is determined by the Category ID.
* Category IDs are represented by the ElementId class.
* Imported Category IDs correspond to elements in the document.
* Most categories are built-in and their IDs are constants stored in ElementIds.
* Each built-in category ID has a corresponding value in the BuiltInCategory Enumeration. They can be converted to corresponding BuiltInCategory enumerated types. `LabelUtils.GetLabelFor(BuiltInCategory)` returns the string name of the given BuiltInCategory in the current Revit language.
* If the category is not built-in, the ID is converted to a null value.
**Code Region 5-2: Getting element category**
---
public void GetElementCategory(UIDocument uidoc)
{
Element selectedElement = null;
foreach (ElementId id in uidoc.Selection.GetElementIds())
{
selectedElement = uidoc.Document.GetElement(id);
break; // just get one selected element
}
// Get the category instance from the Category property
Category category = selectedElement.Category;
BuiltInCategory enumCategory = (BuiltInCategory)category.Id.Value;
}
Note: To avoid Globalization problems when using Category.Name, BuiltInCategory is a better choice. Category.Name can be different in different languages.
### Family
Families are classes of Elements within a category. Families can group Elements by the following:
* A common set of parameters (properties).
* Identical use.
* Similar graphical representation.
Most families are component Family files, meaning that you can load them into your project or create them from Family templates. You determine the property set and the Family graphical representation.
Another family type is the system Family. System Families are not available for loading or creating. Revit predefines the system Family properties and graphical representation; they include walls, dimensions, roofs, floors (or slabs), and levels.
**Figure 22: Families**
In addition to functioning as an Element class, Family is also a template used to generate new items that belong to the Family.
#### Family in the Revit Platform API
In the Revit Platform API, both the Family class and FamilyInstance belong to the Component Family. Other Elements include System Family.
Families in the Revit Platform API are represented by three objects:
* Family
* FamilySymbol
* FamilyInstance
Each object plays a significant role in the Family structure.
The Family object has the following characteristics:
* Represents an entire family such as a beam.
* Represents the entire family file on a disk.
* Contains a number of FamilySymbols.
The FamilySymbol object represents a specific set of family settings in the Family such as the Type, Concrete-Rectangular Beam: 16×32.
The FamilyInstance object is a FamilySymbol instance representing a single instance in the Revit project. For example, the FamilyInstance can be a single instance of a 16×32 Concrete-Rectangular Beam in the project.
Note: Remember that the FamilyInstance exists in FamilyInstance Elements, Datum Elements, and Annotation Elements.
Consequently, the following rules apply:
* Each FamilyInstance has one FamilySymbol.
* Each FamilySymbol belongs to one Family.
* Each Family contains one or more FamilySymbols.
For more detailed information, see [Family Instances](../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Family_Instances_html.html).
### ElementType
In the Revit Platform API, Symbols are usually non-visible elements used to define instances. Symbols are called Types in the user interface.
* A type can be a specific size in a family, such as a 1730 × 2032 door, or an 8×4×1/2 angle.
* A type can be a style, such as default linear or default angular style for dimensions.
Symbols represent Elements that contain shared data for a set of similar elements. In some cases, Symbols represent building components that you can get from a warehouse, such as doors or windows, and can be placed many times in the same building. In other cases, Symbols contain host object parameters or other elements. For example, a WallType Symbol contains the thickness, number of layers, material for each layer, and other properties for a particular wall type.
FamilySymbol is a symbol in the API. It is also called Family Type in the Revit user interface. FamilySymbol is a class of elements in a family with the exact same values for all properties. For example, all 32×78 six-panel doors belong to one type, while all 24×80 six-panel doors belong to another type. Like a Family, a FamilySymbol is also a template. The FamilySymbol object is derived from the ElementType object and the Element object.
### Instance
Instances are items with specific locations in the building (model instances) or on a drawing sheet (annotation instances). Instance represents transformed identical copies of an ElementType. For example, if a building contains 20 windows of a particular type, there is one ElementType with 20 Instances. Instances are called Components in the user interface.
Note: For FamilyInstance, the Symbol property can be used instead of the GetTypeId() method to get the corresponding FamilySymbol. It is convenient and safe since you do not need to do a type conversion.
**Parent page:** [Elements Essentials](../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html)

16
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.md Normal file
View File

@@ -0,0 +1,16 @@
# Elements Essentials
# Elements Essentials
An Element corresponds to a single building or drawing component, such as a door, a wall, or a dimension. In addition, an Element can be a door type, a view, or a material definition.
**Pages in this section**
* [Element Classification](Elements_Essentials/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Element_Classification_html.html)
* [Other Classifications](Elements_Essentials/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Other_Classifications_html.html)
* [Element Retrieval](Elements_Essentials/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Element_Retrieval_html.html)
* [General Properties](Elements_Essentials/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_General_Properties_html.html)
**Parent page:** [Introduction](../Revit_API_Revit_API_Developers_Guide_Introduction_html.html)

36
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Debugging_Your_Application_in_Microsoft_Visual_Studio_html.md Normal file
View File

@@ -0,0 +1,36 @@
# Debugging Your Application in Microsoft Visual Studio
# Debugging Your Application in Microsoft Visual Studio
The following instructions apply to Visual Studio Professional. The relevant option is not available in the Visual Studio Community editions.
There are a few differences between debugging a standalone application (EXE) and an external application (DLL) that needs another program to launch it. To debug an application that is using the Autodesk Revit API it needs to be activated by Autodesk Revit. To do this in the developer environment for debugging you will need to:
1. Open up the Visual Studio project for the API application, for example, HelloWorld.csproj from the Samples folder.
2. From the Debug menu select HelloWorld Debug Properties.
3. Click the New Profile button to create a new launch profile.
4. Select "Executable." You are creating a new profile which will launch another program (in this case, Revit) upon debugging.
5. Click the Browse button and find the Revit.exe file and click Open.
6. Set your new launch profile as active from the dropdown on the Debug panel.
7. Set some break points in your source code.
8. From Visual Studio, select "Start Debugging". Autodesk Revit will launch.
9. To hit a break point select the option for your program from the External Tools menu. Once the compiler reaches one of your break points it will stop to let you debug your program.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

42
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Deployment_Options_html.md Normal file
View File

@@ -0,0 +1,42 @@
# Deployment Options
# Deployment Options
The Autodesk Revit API supports in-process DLLs only. This means that your API application will be compiled as a DLL loaded into the Autodesk Revit process.
The Autodesk Revit API supports single threaded access only. This means that your API application must perform all Autodesk Revit API calls in the main thread (which is called by the Autodesk Revit process at various API entry points), and your API application cannot maintain operations in other threads and expect them to be able to make calls to Autodesk Revit at any time. (For possible exceptions, see the Advanced Topic [External_Events](../../../Advanced_Topics/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_External_Events_html.html).)
There are two types of DLLs that you can create with the Autodesk Revit API: External Commands and External Applications.
## External Commands
The Autodesk Revit API enables you to add new commands to the user interface of Autodesk Revit. These commands will appear in the Add-ins tab under the 'External Tools' pulldown, as seen in Figure 1. Through the API, external tool commands have access to the Autodesk Revit database, as well as the currently selected elements.
Figure 1: External Tool added to Revit
## External Applications
The Autodesk Revit API enables you to also add external applications. These applications are invoked during Autodesk Revit startup and shutdown. They can create new panels in the Add-ins tab, as seen in Figure 2. They can also register handlers that can react to events occurring in the Autodesk Revit user interface.
Figure 2: New panels and controls added to Revit
## REX addins
REX (Revit Extensions) is an API framework that lets you build applications for Revit in .NET similar to classes that implement IExternalCommand. REX is meant to give you a more high-level development environment through built-in resources such as:
* Automatic dialog box creation and display.
* Libraries to work with units and geometry.
* Built-in command-based architecture to make menu and toolbar development easier.
* A standard mechanism for accessing a reference to the Revit application object.
* Automatic deployment and installation of addins for easy debugging.
Please see the "\Revit 2026 SDK\REX SDK" folder for more details.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

40
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_External_Applications_html.md Normal file
View File

@@ -0,0 +1,40 @@
# External Applications
# External Applications
Technically, an external application is an exposed .NET object that supports the Autodesk.Revit.IExternalApplication interface. Furthermore, there must be a .addin manifest file in the appropriate directory with one entry for each such object in order for Autodesk Revit to be able to load these applications when Autodesk Revit starts.
## The IExternalApplication Interface
The declaration (C#) of the interface is as follows:
Code Region: IExternalApplication interface
---
Autodesk.Revit.UI.IExternalApplication.Result OnStartup(Autodesk.Revit.UIControlledApplication application)
Autodesk.Revit.UI.IExternalApplication.Result OnShutdown(Autodesk.Revit.UIControlledApplication application)
### Parameters
* application: The object passed in this parameter contains information important to the commands OnStartup and OnShutdown that are being called. This object provides limited access methods of Autodesk Revit Application, such as VersionName, VersionNumber; and delegates for some events, such as OnDocumentOpened, OnDocumentSaved.
### Return Value
result: The return value can be one of the following:
* Success: Is returned if the external application succeeded as expected without any unhandled error conditions.
* Failure: Failure signifies that the external application failed in some manner from which it cannot recover.
* Cancelled: This value specifies that the external application be cancelled.
## External Application Object Lifetime
When Autodesk Revit starts, the external application object will be created and the OnStartup method called. Once this method returns back successfully to Autodesk Revit the external application object will be held during the entire Autodesk Revit session. The OnShutdown method will be called when Autodesk Revit shuts down.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

61
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_External_Commands_html.md Normal file
View File

@@ -0,0 +1,61 @@
# External Commands
# External Commands
Technically, an external command is an exposed .NET object that supports the Autodesk.Revit.UI.IExternalCommand interface. Furthermore, there must be a .addin manifest file in the appropriate directory with one entry for each such object in order for Revit to be able to "see" and to use the commands.
## The IExternalCommand Interface
The declaration (VB.NET) of the interface is as follows:
Code Region: VB.NET IExternalCommand interface
---
Function Execute(ByVal commandData As Autodesk.Revit.UI.ExternalCommandData,
ByRef message As String,
ByVal elements As Autodesk.Revit.DB.ElementSet)
As Result
### Parameters
* commandData : The object passed in this parameter contains information important to the command that is being executed. This data includes the Autodesk Revit Application object as well as the currently active view.
* message : The message string can be set to supply a specific message to the user when the command terminates. How this message is displayed is dependent upon the return value of the function. See the remarks section for more details.
* elements : Initially this is an empty set that can contain Autodesk Revit elements. When the command terminates, the elements within this set may be displayed, based on the return value. See the remarks section for more details.
### Return value
result: The return value can be one of the following:
* Success : Is returned if the command succeeded as expected without any unhandled error conditions. The external command will appear as an undoable operation in the Autodesk Revit user interface.
* Cancelled : This value specifies that the user requested that the command be cancelled. Any changes that were made to Autodesk Revit objects during the external commands execution will be undone. A message may be posted, see the Remarks section.
* Failure : Failure signifies that the external command failed in some manner from which it cannot recover. Any changes made to Autodesk Revit objects during the execution of the external command will be undone. A message will be posted, see the Remarks section.
### Remarks
The message and elements parameters are used if the command was cancelled or failed.
* Cancelled: If the external command was cancelled and the message parameter was set by the external command then the message is displayed when execution is returned back to Autodesk Revit. If the message parameter was not set then no message is displayed and the command will exit silently.
* Failed: If the external command failed then the contents of the message parameter will be displayed. If the element set contains Autodesk Revit elements then these elements will be highlighted when the error message is displayed thus giving the developer the ability to show the user the problem elements.
## Using an Autodesk Revit API External Command
1. User opens/creates a project in Autodesk Revit
2. User selects the external command from the External Tools pulldown on the Add-ins tab.
3. The user had the option to select a number of Autodesk Revit elements before invoking the External Tools program. If they did, the program can decide to only perform its function on the selected members.
4. The API program takes focus from Autodesk Revit and performs the required task. Often a dialog box may be required to obtain user input before the application can complete its work.
5. Once the add-in tool has completed its function or has been dismissed by the user the program will update the Autodesk Revit model as required and return from the external command, giving focus back to Autodesk Revit.
## External Command Object Lifetime
When no other command or edit modes are active within Autodesk Revit, the registered external command will become enabled. When picked, the command object will be created and the Execute method called. Once this method returns back to Autodesk Revit the command object will be destroyed. Due to this destruction, data cannot persist within the object between command executions. If you wish the data to persist you may use an external file or database to do so. If you wish the data to persist within the Autodesk Revit project you may use the shared parameters mechanism to store this data.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

168
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_NET8_Update_html.md Normal file
View File

@@ -0,0 +1,168 @@
# Migrating From .NET 4.8 to .NET 8
# **Migrating From .NET 4.8 to .NET 8**
Revit 2025 and future releases will be built on .NET 8 and legacy Revit add-ins need to be recompiled for .NET 8.
The move from .NET 4.8 is to .NET 8 is a relatively large jump. .NET 8 comes from the .NET Core lineage, which has significant differences from .NET 4.8.
## **Upgrade Process**
There are many Microsoft documents and tools to help application developers migrate from .NET 4.8 to .NET Core/5/6/7/8. Following is a list of some helpful documents:
* Overview of porting from .NET Framework to .NET document: <https://learn.microsoft.com/en-us/dotnet/core/porting/>
* .NET Upgrade Assistant can help with the project migration: <https://learn.microsoft.com/en-us/dotnet/core/porting/upgrade-assistant-overview>
* [The .NET Portability Analyzer - .NET](https://docs.microsoft.com/en-us/dotnet/standard/analyzers/portability-analyzer) on C# projects to roughly evaluate how much work is required to make the migration as well as dependencies between the assemblies.
* Lists of breaking changes for .NET Core and .NET 5+: <https://learn.microsoft.com/en-us/dotnet/core/compatibility/breaking-changes>
* The .NET 8 SDK can be installed from here: <https://dotnet.microsoft.com/en-us/download/visual-studio-sdks>
* .NET SDK 8.0.100 is used to build Revit 2025.
* Revit 2025 will install .NET 8 Windows Desktop Runtime x64 8.0.0 and ASP.NET Core Runtime x64 8.0.0.
* If you use Visual Studio to build .NET 8 code, you'll need [Visual Studio 17.8](https://visualstudio.microsoft.com) or later.
## **Basic upgrade process for projects**
### **For C# projects (CSPROJ)**
1. Convert C# projects to the new SDK-style format: <https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview>
1. The .NET Upgrade Assistant can help with the project migration: <https://learn.microsoft.com/en-us/dotnet/core/porting/upgrade-assistant-overview>
2. Convert packages.json into PackageReferences in your CSPROJ. <https://learn.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference>
2. Update the target framework for your projects from ****to**net8.0-windows**
1. You can run the [.NET Portability Analyzer](https://docs.microsoft.com/en-us/dotnet/standard/analyzers/portability-analyzer) on C# projects to evaluate how much work is required to make the migration.
2. The .NET Upgrade Assistant can help with the .NET version migration: <https://learn.microsoft.com/en-us/dotnet/core/porting/upgrade-assistant-overview>
3. If your application is a [WPF application](https://learn.microsoft.com/en-us/dotnet/desktop/wpf/migration/?view=netdesktop-7.0&preserve-view=true), then the CSPROJ will need **net8.0-windows** and **true**.
4. If your application uses [Windows forms](https://learn.microsoft.com/en-us/dotnet/desktop/winforms/migration/?view=netdesktop-6.0&preserve-view=true), then use **net8.0-windows** and **true**.
3. System references can be removed from the CSPROJ, as they are available by default.
4. Then address incompatible packages, library references and obsolete (unsupported) code.
### **For C++/CLI projects (VCXPROJ)**
Refer to Microsoft's guide for migrating C++/CLI projects to .NET Core/5+: <https://learn.microsoft.com/en-us/dotnet/core/porting/cpp-cli>
1. Replace **true** with **NetCore.** This property is often in configuration-specific property groups, so you may need to replace it in multiple places.
2. Replace ****property with**net8.0-windows.**
3. Remove any .NET Framework references (like ****) and add**FrameworkReference** when needed. .NET Core SDK assemblies are automatically referenced when using **NetCore** support.
4. Add FrameworkReferences:
1. To use Windows Forms APIs, add this reference to the vcxproj file: ****
2. To use WPF APIs, add this reference to the vcxproj file: ****
3. To use both Windows Forms and WPF APIs, add this reference to the vcxproj file: ****
5. Remove any ****for cpp files. It will be set as NetCore by default. Any other values may cause issues.
6. Then address incompatible packages, library references and obsolete (unsupported) code**.**
### **Global.json**
You may need to set **net8.0-windows** as the target in your global.json, if you have one. Refer the link for global.json overview: <https://learn.microsoft.com/en-us/dotnet/core/tools/global-json>
# **Component Versions**
Your add-in may avoid instability by matching the version of these key components used by the Revit preview release:
* CefSharp
* "cef.redist.x64" Version="119.4.3"
* "cef.redist.x86" Version="119.4.3"
* "CefSharp.Wpf.HwndHost" Version="119.4.30"
* "CefSharp.Common.NetCore" Version="119.4.30"
* "CefSharp.Wpf.NetCore" Version="119.1.20"
* Newtonsoft Json
* "Newtonsoft.Json" Version="13.0.1"
# **Supporting Multiple Revit Releases**
A single code base can support older Revit releases on .NET 4.8 as well as Revit 2025 on .NET 8. [See this discussion on the Autodesk forums](https://forums.autodesk.com/t5/revit-api-forum/optimal-add-in-code-base-approach-to-target-multiple-revit/m-p/12532755/highlight/true#M76622) for ideas on configuring your projects and code to support multi-targeting.
# **Common Issues**
Here are some common issues you may encounter when upgrading to .NET 8:
### **Build Warning MSB3277**
When building code that references RevitAPI or RevitUIAPI, you will see the [build warning MSB3277](https://learn.microsoft.com/en-us/visualstudio/msbuild/errors/msb3277?view=vs-2022). To fix this, add a reference to the Windows Desktop framework: ****
### **Build Error CA1416**
If your application uses functions that are only available on Windows systems, you may see a [CA1416](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1416) error. This can be fixed for the project by adding **[assembly: System.Runtime.Versioning.SupportedOSPlatformAttribute("windows")]** to **AssemblyInfo.cs**.
## **Obsolete Classes and Functions with .NET 8**
Your .NET 4.8 application may see compile time or runtime errors if it uses classes or functions that are obsolete or deprecated in .NET Core/5/6/7/8.
Lists of breaking changes for .NET Core/5/6/7/8 are here: <https://learn.microsoft.com/en-us/dotnet/core/compatibility/breaking-changes>
* [BinaryFormatter](https://learn.microsoft.com/en-us/dotnet/core/compatibility/serialization/5.0/binaryformatter-serialization-obsolete) and [SOAPFormatter](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.serialization.formatters.soap.soapformatter?view=netframework-4.8.1) are obsolete.
* Resource files that contain images or bitmaps will need to be updated as [BinaryFormatter will not be available in .NET 8 to interpret those images/bitmaps](https://stackoverflow.com/questions/69796653/binaryformatter-not-supported-in-net-5-app-when-loading-bitmap-resource).
* [Windows Forms dialogs using ImageList](https://github.com/dotnet/winforms/issues/9701) may need to be updated as BinaryFormatter loads the images for the ImageList.
* [System.Threading.Thread.Abort](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/5.0/thread-abort-obsolete) is obsolete.
* [System.Reflection.AssemblyName.CodeBase](https://learn.microsoft.com/en-us/dotnet/api/system.reflection.assemblyname.codebase?view=net-7.0) and [System.Reflection.Assembly.CodeBase](https://learn.microsoft.com/en-us/dotnet/api/system.reflection.assembly.codebase?view=net-7.0) are deprecated.
* [Delegate.BeginInvoke](https://devblogs.microsoft.com/dotnet/migrating-delegate-begininvoke-calls-for-net-core/) is not supported.
* [Debug.Assert failure or Debug.Fail](https://github.com/dotnet/winforms/issues/3739) silently exits the application by default.
## **Assembly Loading**
Your .NET 4.8 application may need updates to help it find and load assemblies:
* .NET 8 uses a different [assembly probing approach for DLL loading](https://learn.microsoft.com/en-us/dotnet/core/dependency-loading/default-probing). When in doubt, try putting the DLL to be loaded in the build output root directory.
* .NET 8 [assembly loading details](https://learn.microsoft.com/en-us/dotnet/core/dependency-loading/loading-managed) are different than .NET 4.8.
* .NET 8 projects need [runtimeconfig.json files for many DLLs](https://learn.microsoft.com/en-us/dotnet/core/runtime-config/). The **runtimeconfig.json** needs to be installed next to the matching DLL, and it configures the behavior of that DLL. These files can be created with **true**
* .NET 8 projects will create **deps.json** files for many DLLs. These **deps.json** files can be deleted if dependencies are placed in the [same directory as the application](https://learn.microsoft.com/en-us/dotnet/core/dependency-loading/default-probing). These files can be deleted with **false**
## **Assembly Properties**
After updating your application to .NET 8, you may see build errors for your assembly properties. Many assembly properties are now auto-generated and [can be removed from AssemblyInfo.cs](https://learn.microsoft.com/en-us/dotnet/architecture/modernize-desktop/example-migration#assemblyinfo-considerations).
## **Double Numbers To String**
If you have unit tests or integration tests that compare doubles as strings, they may fail when you upgrade to .NET 8. This is because the number of decimal places printed by **ToString()** for doubles is [different in .NET 4.8 and .NET 8](https://devblogs.microsoft.com/dotnet/floating-point-parsing-and-formatting-improvements-in-net-core-3-0/). You can call **ToString("G15")** when converting doubles to strings to use the old .NET 4.8 formatting.
## **String.Compare**
String.Compare behavior has changed, see [.NET globalization and ICU](https://learn.microsoft.com/en-us/dotnet/core/extensions/globalization-icu) and [Use Globalization and ICU](https://learn.microsoft.com/en-us/dotnet/core/extensions/globalization-icu#use-nls-instead-of-icu).
## **Windows Dialogs May Change Appearance**
Your dialogs may change appearance with .NET 8.
* [WinForms dialogs experience UI layout changes.](https://github.com/dotnet/winforms/issues/9293) The workaround is to set `Scale(new SizeF(1.0F, 1.0F));` in the dialog constructor.
* The dialog [default font changed from "Microsoft Sans Serif 8 pt" to "Segoe UI"](https://learn.microsoft.com/en-us/dotnet/core/compatibility/winforms#default-control-font-changed-to-segoe-ui-9-pt). This can change dialog appearance and spacing.
## **Process.Start() May Fail**
If your application is having trouble starting new processes, this may be because [System.Diagnostics.Process.Start(url) has a behavior change](https://github.com/dotnet/core/issues/4109). The [ProcessStartInfo.UseShellExecute Property](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.processstartinfo.useshellexecute?view=net-7.0) defaults to **true** in .NET 4.8 and **false** in .NET 8. Set **UseShellExecute=true** to workaround this change.
## **Encoding.Default Behaves Differently in .NET 8**
If your application is having problems getting the text encoding used by Windows, it may be because **Encoding.Default** behaves differently in .NET 8. In .NET 4.8 **Encoding.Default** would get the system's active code page, but in .NET Core/5/6/7/8 [Encoding.Default is always UTF8](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding.default?view=net-7.0).
## **Items Order Differently in Sorted Lists**
If you see different orderings of items in sorted lists after updating to .NET 8, this may be because [List.Sort() behaves differently](https://github.com/microsoft/dotnet/blob/main/Documentation/compatibility/list_sort-algorithm-changed.md) in .NET 8 than .NET 4.8. The change fixes a .NET 4.8 bug which affected **Sort()** of items of equal value.
## **System.ServiceModel**
System.ServiceModel has been ported to .NET Core through [CoreWCF](https://dotnet.microsoft.com/en-us/platform/support/policy/corewcf), which is now available through Nuget packages. There are various changes, including **< System.ServiceModel>** not being supported in configuration files.
## **C# Language Updates**
If you are building code from .NET 4.8 in .NET 8, you may see build errors or warnings about C# nullable types.
[C# has introduced nullable value types](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/nullable-value-types) and [nullable reference types](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/nullable-reference-types). Prior to .NET 6, new projects used the default **disable**. Beginning with .NET 6, new projects include the **enable** element in the project file.
You can set **disable** if you want to revert to .NET 4.8 behavior.
## **Environment Variables**
If you use managed .NET to run native C++ code, be aware that environmental variables, including the path variable for DLL loading, are not shared from managed .NET code with native C++ code.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

59
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Registration_of_add_ins_html.md Normal file
View File

@@ -0,0 +1,59 @@
# Registration of add-ins
# Registration of add-ins
The Revit API offers the ability to register API applications via a .addin manifest file.
Manifest files will be read automatically by Revit when they are placed in one of two locations on a user's system:
* **In a non-user specific location in "application data"**
* C:\ProgramData\Autodesk\Revit\Addins\<version number>\
* **In a user specific location in "application data"**
* C:\Users\<user>\AppData\Roaming\Autodesk\Revit\Addins\<version number>\
All files named .addin in these locations will be read and processed by Revit during startup.
A basic file adding one ExternalCommand looks like this:
**Code Region: Basic manifest file for an ExternalCommand**
---
<?xml version="1.0" encoding="utf-16" standalone="no"?>
<RevitAddIns>
<AddIn Type="Command">
<Assembly>c:\MyProgram\MyProgram.dll</Assembly>
<AddInId>76eb700a-2c85-4888-a78d-31429ecae9ed</AddInId>
<FullClassName>Revit.Samples.SampleCommand</FullClassName>
<Text>Sample command</Text>
<VisibilityMode>NotVisibleInFamily</VisibilityMode>
<VisibilityMode>NotVisibleInMEP</VisibilityMode>
<AvailabilityClassName>Revit.Samples.SampleAccessibilityCheck</AvailabilityClassName>
</AddIn>
</RevitAddIns>
A basic file adding one ExternalApplication looks like this:
**Code Region: Basic manifest file for an ExternalApplication**
---
<?xml version="1.0" encoding="utf-16" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>My sample application</Name>
<Assembly>c:\MyProgram\MyProgram.dll</Assembly>
<AddInId>604B1052-F742-4951-8576-C261D1993107</AddInId>
<FullClassName>Revit.Samples.SampleApplication</FullClassName>
</AddIn>
</RevitAddIns>
Multiple AddIn elements may be provided in a single manifest file.
See [Add-in Registration](../../Add_In_Integration/Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_Add_in_Registration_html.html) for more information on the available XML tags for .addin files.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

13
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Storing_and_accessing_Custom_Data_for_Applications_html.md Normal file
View File

@@ -0,0 +1,13 @@
# Storing and accessing Custom Data for Applications
# Storing and accessing Custom Data for Applications
Often programs linked to Autodesk Revit require information that is not available in the Autodesk Revit model database. There are a number of ways for the user to enter such additional information. How and where the information is entered depends on its use:
* When the information is of a general type and the user will want to see and edit it inside Autodesk Revit, then it should be stored as a visible Project or Shared Parameter.
* If the information needs to be kept with the Autodesk Revit model as it evolves but does not need to be visible then it can be stored in the Autodesk Revit model as a non-visible Project or Shared Parameter or using Extensible Storage.
* If the information is specific to a single add-on program, and is too large to practically store within the Autodesk Revit model such as specifications for a multitude of building products subject to change, then the best solution may be to create a concurrent model database that stores the program specific information. In this case it may be useful to use the element UniqueId property for each element as a key for the database, because the element's UniqueId is stable within a model.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

19
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_The_Revit_Unit_System_html.md Normal file
View File

@@ -0,0 +1,19 @@
# The Revit Unit System
# The Revit Unit System
The Revit Unit System uses the following base units:
**Base Unit** | **Unit in Revit** | **Unit System**
---|---|---
Length | Feet (ft) | Imperial
Angle | Radian | Metric
Mass | Kilogram (kg) | Metric
Time | Seconds (s) | Metric
Electric Current | Ampere (A) | Metric
Temperature | Kelvin (K) | Metric
Luminous Intensity | Candela (cd) | Metric
**Note:** Because Revit stores lengths in feet and other quantities in metric, a derived unit involving length uses a non-standard unit using the Imperial and the Metric systems. For example, force is measured in mass-length per time squared and is stored in kg-ft/s2.
**Parent page:** [Using the Autodesk Revit API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)

46
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.md Normal file
View File

@@ -0,0 +1,46 @@
# Using the Autodesk Revit API
# Using the Autodesk Revit API
## Autodesk Revit SDK and Online Help
The Autodesk Revit API Software Development Kit (SDK) is installed from the Tools and Utilities section of the Autodesk Revit installation. In the SDK, there are example files that will help you get a better understanding of the API and its use. Each example file has a sample .addin manifest file with the information that you will need to edit and place into the appropriate folder, which Autodesk Revit will access on launch.
RevitAPI.chm is the Autodesk Revit API reference documentation help chm file, included with the SDK package in the \Revit 2026 SDK\ folder.
**For more information:**
* [Glossary of Autodesk Revit Terms](../../Appendices/Revit_API_Revit_API_Developers_Guide_Appendices_Glossary_html.html)
* [FAQ](../../Revit_API_Revit_API_Developers_Guide_FAQ_html.html)
**Resources:**
* [www.autodesk.com/adn](http://www.autodesk.com/adn) \- Autodesk Developer Network home (ADN)
* [www.autodesk.com/developrevit](http://www.autodesk.com/developrevit) \- Autodesk Revit development resources
* <http://forums.autodesk.com/t5/Revit-API/bd-p/160> \- Revit API discussion group
* <http://thebuildingcoder.typepad.com/blog/> \- The Building Coder, an ADN blog dedicated to Revit coding
* <http://bimapps.typepad.com/> \- BIM Apps, a blog dedicated to BIM applications
**Pages in this section**
* [Deployment Options](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Deployment_Options_html.html)
* [Registration of add-ins](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Registration_of_add_ins_html.html)
* [External Commands](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_External_Commands_html.html)
* [External Applications](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_External_Applications_html.html)
* [Debugging Your Application in Microsoft Visual Studio](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Debugging_Your_Application_in_Microsoft_Visual_Studio_html.html)
* [The Revit Unit System](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_The_Revit_Unit_System_html.html)
* [Storing and accessing Custom Data for Applications](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_Storing_and_accessing_Custom_Data_for_Applications_html.html)
* [Migrating From .NET 4.8 to .NET 8](Using_the_Autodesk_Revit_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_NET8_Update_html.html)
**Parent page:** [Getting Started](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html)

162
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Add_Hello_World_Ribbon_Panel_html.md Normal file
View File

@@ -0,0 +1,162 @@
# Walkthrough: Add Hello World Ribbon Panel
# Walkthrough: Add Hello World Ribbon Panel
In the Walkthrough: Hello World section you learn how to create an add-in application and invoke it in Revit. You also learn to create a .addin manifest file to register the add-in application as an external tool. Another way to invoke the add-in application in Revit is through a custom ribbon panel.
### Create a New Project
Complete the following steps to create a new project:
1. Create a C# project in Visual Studio using the Class Library template.
2. Type AddPanel as the project name.
3. Add references to the RevitAPI.dll and RevitAPIUI.dll using the directions in the previous walkthrough, Walkthrough: Hello World.
4. Add the WindowsDesktop reference to use BitmapImage:
* In the Solution Explorer, double-click on the AddPanel project to open the .csproj file.
* Add the following lines before the final tag:
<ItemGroup>
<FrameworkReference Include="Microsoft.WindowsDesktop.App" />
</ItemGroup>
5. Save the file. Microsoft.WindowsDesktop.App should appear under AddPanel -> Dependencies -> Frameworks in the Solution Explorer.
**Figure 8: Add Reference**
### Change the Class Name
To change the class name, complete the following steps:
1. In the Solution Explorer, right-click the Class1.cs file to display a context.
2. From the context menu, select Rename and change the file's name to CsAddPanel.cs.
3. Double click CsAddPanel.cs to open it for editing.
### Add Code
The Add Panel project is different from Hello World because it is automatically invoked when Revit runs. Use the IExternalApplication interface for this project. The IExternalApplication interface contains two abstract methods, OnStartup() and OnShutdown(). For more information about IExternalApplication, refer to [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html).
Add the following code to the file:
#### Code Region 2-5: Adding a ribbon panel
using System;
using System.Reflection;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
using System.Windows.Media.Imaging;
namespace Walkthrough
{
/// <remarks>
/// This application's main class. The class must be Public.
/// </remarks>
public class CsAddPanel : IExternalApplication
{
// Both OnStartup and OnShutdown must be implemented as public method
public Result OnStartup(UIControlledApplication application)
{
// Add a new ribbon panel
RibbonPanel ribbonPanel = application.CreateRibbonPanel("NewRibbonPanel");
// Create a push button to trigger a command add it to the ribbon panel.
string thisAssemblyPath = Assembly.GetExecutingAssembly().Location;
PushButtonData buttonData = new PushButtonData("cmdHelloWorld",
"Hello World", thisAssemblyPath, "Walkthrough.HelloWorld");
PushButton pushButton = ribbonPanel.AddItem(buttonData) as PushButton;
// Optionally, other properties may be assigned to the button
// a) tool-tip
pushButton.ToolTip = "Say hello to the entire world.";
// b) large bitmap
Uri uriImage = new Uri(@"C:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png");
BitmapImage largeImage = new BitmapImage(uriImage);
pushButton.LargeImage = largeImage;
return Result.Succeeded;
}
public Result OnShutdown(UIControlledApplication application)
{
// nothing to clean up in this simple case
return Result.Succeeded;
}
}
/// <remarks>
/// The "HelloWorld" external command. The class must be Public.
/// </remarks>
[Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.Manual)]
public class HelloWorld : IExternalCommand
{
// The main Execute method (inherited from IExternalCommand) must be public
public Autodesk.Revit.UI.Result Execute(ExternalCommandData revit,
ref string message, ElementSet elements)
{
TaskDialog.Show("Revit", "Hello World");
return Autodesk.Revit.UI.Result.Succeeded;
}
}
}
### Add an Icon
The sample code references an image at C:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png. Please replace that path with a path to any 32x32 pixel image you wish to use as an icon on the ribbon.
### Build the Application
After completing the code, build the application. From the Build menu, click Build Solution. Output from the build appears in the Output window indicating that the project compiled without errors. AddPanel.dll is located in the project output directory.
### Create the .addin manifest file
To invoke the application in Revit, create a manifest file to register it into Revit.
1. Create a new text file using Notepad.
2. Add the following text to the file:
#### Code Region 2-6: Creating a .addin file for the external application
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>Hello World Panel</Name>
<Assembly>C:\Sample\AddPanel\AddPanel\bin\Debug\net8.0\AddPanel.dll</Assembly>
<AddInId>604b1052-f742-4951-8576-c261d1993108</AddInId>
<FullClassName>Walkthrough.CsAddPanel</FullClassName>
<VendorId>NAME</VendorId>
<VendorDescription>Your Company Information</VendorDescription>
</AddIn>
</RevitAddIns>
Two notes. First, make sure the Assembly path points to the actual location of your library. The build output will note your actual path. Second, replace the AddInId with a newly-created GUID. Revit will refuse to load multiple addins with the same identifier, so it's important to create your own. You can get a new GUID from Visual Studio via Tools -> Create GUID, or any of a number of online tools.
3. Save the file as HelloWorldRibbon.addin and put it in: C:\ProgramData\Autodesk\Revit\Addins\2026.
Note: For this sample, we have listed AddPanel.dll file in the default file folder in a new folder called Debug (C:\Sample\HelloWorld\bin\Debug\AddPanel.dll). Use the file path to evaluate Assembly.
Refer to [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html) for more information about .addin manifest files.
### Running the addin
To see the addin in action, build the project and run Revit. A new ribbon panel appears on the Add-Ins tab named NewRibbonPanel and Hello World appears as the only button on the panel, with a large globe image (or another image you have chosen).
**Figure 9: Add a new ribbon panel to Revit**
Click Hello World to run the application and display the following dialog box.
**Figure 10: Hello World dialog box**
**Parent page:** [Getting Started](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html)

210
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Hello_World_html.md Normal file
View File

@@ -0,0 +1,210 @@
# Walkthrough: Hello World
# Walkthrough: Hello World
Use the Revit Platform API and C# to create a Hello World program using the directions provided. For information about how to create an add-in application using VB.NET, refer to [Hello World for VB.NET](../../Appendices/Revit_API_Revit_API_Developers_Guide_Appendices_Hello_World_for_VB_NET_html.html) .
The Hello World walkthrough covers the following topics:
* Create a new project.
* Add references.
* Change the class name.
* Write the code.
* Debug the add-in.
All operations and code in this section were created using Visual Studio 2022.
## Create a New Project
The first step in writing a C# program with Visual Studio is to choose a project type and create a new Class Library.
1. Select "Create a new project".
2. Select the C#, Windows, and Library filters and the `Class Library` template, and click Next.
3. In the Project Name field, type `HelloWorld` as the project name and click OK.
4. Select the `.NET 8.0` framework and click Create.
## Add References
* If the Solution Explorer window is not open, select Solution Explorer from the View menu.
* In the Solution Explorer, click the arrow to the left of the HelloWorld project (not the top-level Solution) to expand it. Right-click on Dependencies and select `Add Project Reference`.
* Click Browse, go to the folder where Revit is installed (such as C:\Program Files\Autodesk\Revit 2025), and select `RevitAPI.dll`.
* Click Browse again and select `RevitAPIUI.dll`.
* Click OK to add both dll files which will then appear in the Solution Explorer under the HelloWorld proejct / Dependencies / Assemblies.
* Set the `Copy Local` property of RevitAPI.dll and RevitAPIUI.dll to No. This saves disk space, and prevents the Visual Studio debugger from getting confused about which copy of the DLL to use. Select both files, right-click, select Properties, and change the Copy Local setting to No. (If they are not visible, expand the `Assemblies` item under Dependencies.)
## Add Code
Open the `Class1.cs` file, delete all of its contents, and add this code:
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
namespace HelloWorld
{
[Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.ReadOnly)]
public class Class1 : IExternalCommand
{
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elementSet)
{
TaskDialog.Show("Hello", "Hello World");
return Result.Succeeded;
}
}
}
**Tip** : The Visual Studio Intellisense feature can create a skeleton implementation of an interface for you, adding stubs for all the required methods. If you are typing this code into Visual Studio (instead of pasting it) After you add ":IExternalCommand" after Class1 in the example above, you can right-click on IExternalCommand, select Quick Actions and Refactorings, and then choose "Implement Interface" to get the code:
**Figure 3: Using Intellisense to Implement Interface**
Every Revit add-in application must have an entry point class that implements the IExternalCommand interface, and you must implement the Execute() method. The Execute() method is the entry point for the add-in application similar to the Main() method in other programs. The add-in entry point class definition is contained in an assembly. For more details, refer to [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html).
## Build the Program
After completing the code, you must build the file. From the Build menu, click Build Solution. Output from the build appears in the Output window indicating that the project compiled without errors.
## Create a .addin manifest file
The HelloWorld.dll file appears in the project output directory. If you want to invoke the application in Revit, create a manifest file to register it into Revit.
1. To create a manifest file, create a new text file in Notepad.
2. Add the following text, replacing the `Assembly` path with the correct path to the `HelloWorld.dll` on your computer:
---
**Code Region 2-2: Creating a .addin manifest file for an external command**
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Command">
<Assembly>C:\Users\<your user name>\source\repos\HelloWorld\HelloWorld\bin\Debug\net8.0\HelloWorld.dll</Assembly>
<AddInId>239BD853-36E4-461f-9171-C5ACEDA4E721</AddInId>
<FullClassName>HelloWorld.Class1</FullClassName>
<Text>HelloWorld</Text>
<VendorId>NAME</VendorId>
</AddIn>
</RevitAddIns>
3. Replace the AddInId field with a new GUID. You can create GUIDs in Visual Studio by going to Tools->Create GUID. (Every addin must have a unique idenfier. Revit will refuse to load two addins with the same identifier, so it is good practice to create new ids even for test applications.)
4. Save the file as HelloWorld.addin and put it in the following location:
* C:\ProgramData\Autodesk\Revit\Addins\\{Release Year}\
* ProgramData may default to being a hidden folder. You can display it by going to `View` in Windows Explorer and checking `Hidden items.`
* If your application assembly dll is on a network share instead of your local hard drive, you must modify Revit.exe.config to allow .NET assemblies outside your local machine to be loaded. In the "runtime" node in Revit.exe.config, add the element `<loadFromRemoteSources enabled="true"/>` as shown below.
<runtime>
<generatePublisherEvidence enabled="false" />
<loadFromRemoteSources enabled="true"/>
</runtime>
Refer to [Add-In Integration](../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html) for more details using manifest files.
## Debug the Add-in
Running a program in Debug mode uses breakpoints to pause the program so that you can examine the state of variables and objects. If there is an error, you can check the variables as the program runs to deduce why the value is not what you might expect.
1. Start Revit.
2. In Visual Studio, choose Debug - Attach To Process, and select Revit.exe.
3. From the Debug menu, select Toggle Breakpoint (or press F9) to set a breakpoint on the following line.
`TaskDialog.Show("Revit", "Hello World");`
Test debugging:
* On the Add-Ins tab, HelloWorld appears in the External Tools menu-button.
**Figure 4: HelloWorld External Tools command**
* Click HelloWorld to execute the program, activating the breakpoint.
* Press F5 to continue executing the program. The following system message appears.
**Figure 5: TaskDialog message**
## Troubleshooting
_Q:_ My add-in application will not compile.
_A:_ If an error appears when you compile the sample code, the problem may be with the version of the RevitAPI used to compile the add-in. Delete the old RevitAPI reference and load a new one. For more details, refer to [Walkthrough: Hello World](./Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Hello_World_html.html).
_Q:_ Why is there no Add-Ins tab or why isn't my add-in application displayed under External Tools?
_A:_ In many cases, if an add-in application fails to load, Revit will display an error dialog on startup with information about the failure. For example, if the add-in DLL cannot be found in the location specified in the manifest file, a message similar to the following appears.
**Figure 6: External Tools Error Message**
In this case, ensure that the .addin file has the correct path to the assembly.
Error messages will also be displayed if the class name specified in FullClassName is not found or does not inherit from IExternalCommand.
However, in some cases, an add-in application may fail to load without any message. Possible causes include:
* The add-in application is compiled with a different RevitAPI version
* The manifest file is not found
* There is a formatting error in the .addin manifest file (Make sure there are no leading spaces before the outermost tag.)
_Q:_ Why does Revit say the publisher of my addin cannot be verified?
_A:_ Revit expects addins to be signed, which is beyond the scope of the Hello World tutorial. You can select `Always Load` or `Load Once` to continue.
_Q:_ Why does my add-in application not work?
_A:_ Even though your add-in application is available under External Tools, it may not work. This is most often caused by an exception in the code.
Revit will display an error dialog with information about the exception when the command fails.
**Figure 7: Unhandled exception in External Command**
This is intended as an aid to debugging your command; commands deployed to users should use try..catch..finally in the example entry method to prevent the exception from being caught by Revit. Here is an example:
**Code Region 2-4: Using try catch in execute:**
---
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
{
ExternalCommandData cdata = commandData;
Autodesk.Revit.ApplicationServices.Application app = cdata.Application.Application;
try
{
// Your code here
}
catch (Exception ex)
{
message = ex.Message;
return Autodesk.Revit.UI.Result.Failed;
}
return Autodesk.Revit.UI.Result.Succeeded;
}
**Parent page:** [Getting Started](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html)

32
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Retrieve_Filtered_Elements_html.md Normal file
View File

@@ -0,0 +1,32 @@
# Walkthrough: Retrieve Filtered Elements
# Walkthrough: Retrieve Filtered Elements
You can use a filter to select only elements that meet certain criteria. For more information on creating and using element filters, see [Element Retrieval](../Elements_Essentials/Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_Element_Retrieval_html.html).
This example retrieves all the doors in the document and returns the list of door elements.
**Code Region 2-8: Retrieve filtered elements**
---
public ICollection<Element> CreateLogicAndFilter(Autodesk.Revit.DB.Document document)
{
// Find all door instances in the project by finding all elements that both belong to the door
// category and are family instances.
ElementClassFilter familyInstanceFilter = new ElementClassFilter(typeof(FamilyInstance));
// Create a category filter for Doors
ElementCategoryFilter doorsCategoryfilter = new ElementCategoryFilter(BuiltInCategory.OST_Doors);
// Create a logic And filter for all Door FamilyInstances
LogicalAndFilter doorInstancesFilter = new LogicalAndFilter(familyInstanceFilter, doorsCategoryfilter);
// Apply the filter to the elements in the active document
FilteredElementCollector collector = new FilteredElementCollector(document);
IList<Element> doors = collector.WherePasses(doorInstancesFilter).ToElements();
return doors;
}
**Parent page:** [Getting Started](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html)

65
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Retrieve_Selected_Elements_html.md Normal file
View File

@@ -0,0 +1,65 @@
# Walkthrough: Retrieve Selected Elements
# Walkthrough: Retrieve Selected Elements
This section introduces you to an add-in application that gets selected elements from Revit.
In add-in applications, you can perform a specific operation on a specific element. For example, you can get or change an element's parameter value. Complete the following steps to get a parameter value:
1. Create a new project and add the references as summarized in the previous walkthroughs.
2. Use the UIApplication.ActiveUIDocument.Selection.GetElementIds() method to retrieve the selected elements.
3. Create a .addin file as explained in previous walkthroughs.
GetElementIds() returns a collection of ElementIds of the selected elements. It can be iterated with a foreach loop. Use the Document.GetElement() method to get the Element object for each ElementId in the selection.
The following code is an example of how to retrieve the ids of the selected element.
**Code Region 2-7: Retrieving selected elements**
---
[Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.ReadOnly)]
public class Document_Selection : IExternalCommand
{
public Autodesk.Revit.UI.Result Execute(ExternalCommandData commandData,
ref string message, ElementSet elements)
{
try
{
// Select some elements in Revit before invoking this command
// Get the handle of current document.
UIDocument uidoc = commandData.Application.ActiveUIDocument;
// Get the element selection of current document.
ICollection<ElementId> selectedIds = uidoc.Selection.GetElementIds();
if (selectedIds.Count == 0)
{
TaskDialog.Show("Revit", "You haven't selected any elements.");
}
else
{
string info = "Ids of selected elements in the document are: ";
foreach (ElementId id in selectedIds)
{
info += Environment.NewLine + id.Value;
}
TaskDialog.Show("Revit", info);
}
}
catch (Exception e)
{
message = e.Message;
return Autodesk.Revit.UI.Result.Failed;
}
return Autodesk.Revit.UI.Result.Succeeded;
}
}
After you get the selected elements, you can get the properties or parameters for the elements. For more information, see [Parameters](../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_html.html).
**Parent page:** [Getting Started](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html)

15
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthroughs_html.md Normal file
View File

@@ -0,0 +1,15 @@
# Walkthroughs
# Walkthroughs
If you are new to the Revit Platform API, the following topics are good starting points to help you understand the product. Walkthroughs provide step-by-step instructions for common scenarios, helping you learn about the product or a particular feature. The following walkthroughs will help you get started using the Revit Platform API:
[Walkthrough: Hello World](./Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Hello_World_html.html) \- Illustrates how to create an add-in using the Revit Platform API.
[Walkthrough: Add Hello World Ribbon Panel](./Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Add_Hello_World_Ribbon_Panel_html.html) \- Illustrates how to add a custom ribbon panel.
[Walkthrough: Retrieve Selected Elements](./Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Retrieve_Selected_Elements_html.html) \- Illustrates how to retrieve selected elements.
[Walkthrough: Retrieve Filtered Elements](./Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Retrieve_Filtered_Elements_html.html) \- Illustrates how to retrieve elements based on filter criteria.
**Parent page:** [Getting Started](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html)

63
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Component_Versions_html.md Normal file
View File

@@ -0,0 +1,63 @@
# Third-Party Component Versions
# Third-Party Component Versions
Revit is built with framework references to Microsoft.NETCore.App 8.0.0 and Microsoft.WindowsDesktop.App 8.0.0. Additionally, Revit references other common open source packages listed in the table below:
Name | Version
---|---
cef.redist.x64 | 119.4.3
cef.redist.x86 | 119.4.3
CefSharp.Common.NetCore | 119.4.30
CefSharp.Wpf.HwndHost | 119.1.20
CefSharp.Wpf.NetCore | 119.4.30
Microsoft.AspNet.WebApi.Client | 5.2.9
Microsoft.AspNetCore.OData | 8.2.0
Microsoft.Bcl.AsyncInterfaces | 7.0.0
Microsoft.CSharp | 4.7.0
Microsoft.Data.Edm | 5.8.5
Microsoft.Data.OData | 5.8.5
Microsoft.Extensions.Caching.Abstractions | 7.0.0
Microsoft.Extensions.Caching.Memory | 7.0.0
Microsoft.Extensions.Configuration | 7.0.0
Microsoft.Extensions.Configuration.Abstractions | 7.0.0
Microsoft.Extensions.Configuration.Binder | 7.0.0
Microsoft.Extensions.Configuration.FileExtensions | 7.0.0
Microsoft.Extensions.Configuration.Json | 7.0.0
Microsoft.Extensions.DependencyInjection | 7.0.0
Microsoft.Extensions.DependencyInjection.Abstractions | 7.0.0
Microsoft.Extensions.FileProviders.Abstractions | 7.0.0
Microsoft.Extensions.FileProviders.Physical | 7.0.0
Microsoft.Extensions.FileSystemGlobbing | 7.0.0
Microsoft.Extensions.Http | 7.0.0
Microsoft.Extensions.Logging | 7.0.0
Microsoft.Extensions.Logging.Abstractions | 7.0.0
Microsoft.Extensions.Options | 7.0.0
Microsoft.Extensions.Primitives | 7.0.0
Microsoft.Net.Http | 2.0.20710.0
Microsoft.NET.Test.Sdk | 17.7.2
Microsoft.NETCore.Platforms | 2.0.0
Microsoft.OData.Core | 7.17.0
Microsoft.OData.Edm | 7.17.0
Microsoft.Spatial | 7.17.0
Microsoft.TestPlatform.TestHost | 17.7.2
Microsoft.Web.Administration | 7.0.0
Microsoft.Web.WebView2 | 1.0.2045.28
Microsoft.Win32.Registry | 5.0.0
Microsoft.Xaml.Behaviors.Wpf | 1.1.39
Newtonsoft.Json | 13.0.1
Newtonsoft.Json.Schema | 3.0.10
System.ComponentModel.Composition | 7.0.0
System.Data.SQLite | 1.0.118.0
System.IO.Abstractions | 13.2.47
System.Management | 7.0.1
System.Reflection.MetadataLoadContext | 7.0.0
System.Runtime.Caching | 7.0.0
System.Security.Cryptography.Pkcs | 6.0.3
System.ServiceModel.Http | 6.0.0
System.ServiceModel.NetNamedPipe | 6.0.0
System.ServiceModel.NetTcp | 6.0.0
System.ServiceModel.Primitives | 6.0.0
System.Spatial | 5.8.5
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

30
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Development_Requirements_html.md Normal file
View File

@@ -0,0 +1,30 @@
# Development Requirements
# Development Requirements
The Autodesk Revit API requires Microsoft .NET 8.0.
To edit and debug your API applications, you need an interactive development environment such as Microsoft Visual Studio 2022 Professional or MS Visual Studio Community for C# or Visual Basic.NET. (Visual Studio Professional is recommended, as Express editions do not support DLL debugging.) When developing with the Autodesk Revit API, ensure that your project references two DLLs: **RevitAPI.dll** and **RevitAPIUI.dll** contained in the Autodesk Revit Program directory.
Some programming skills are required to effectively use the API. If you are a beginner in programming, we strongly advise you to learn Microsoft Visual Studio 2022 and one of the compatible languages like C# or Visual Basic.NET. There are many good books and classes to get you started.
**Resources:**
Online resources
* Free Visual Studio - [http://msdn.microsoft.com/VStudio/Express/](https://www.visualstudio.com/en-US/products/visual-studio-express-vs)
* <http://www.codeguru.com/>
* <http://devx.com/>
* <http://www.msdn.microsoft.com/>
* <http://msdn.microsoft.com/en-us/library/aa288436(v=vs.71).aspx>
Books
* Code Complete, Second Edition, by Steve McConnell
* Software Project Survival Guide, by Steve McConnell
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

11
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Documentation_Conventions_html.md Normal file
View File

@@ -0,0 +1,11 @@
# Documentation Conventions
# Documentation Conventions
This document contains class names in namespace format, such as Autodesk.Revit.DB.Element. In C++/CLI Autodesk.Revit.Element is Autodesk::Revit::DB::Element. Since only C# is used for sample code in this manual, the default namespace is Autodesk.Revit.DB. If you want to see code in Visual Basic, you will find several VB.NET applications in the SDK Samples directory.
### Indexed Properties
Some Revit Platform API class properties are "indexed", or described as overloaded in the API help file (RevitAPI.chm). For example, the Element.Geometry property. In the text of this document, these are referred to as properties, although you access them as if they were methods in C# code by pre-pending the property name with "get_" or "set_". For example, to use the Element.Geometry(Options) property, you use Element.get_Geometry(Options).
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

11
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Installation_html.md Normal file
View File

@@ -0,0 +1,11 @@
# Installation
# Installation
The Autodesk Revit API is automatically installed with the default installation of the Autodesk Revit based product. Any .NET based application will reference the RevitAPI.dll and the RevitAPIUI.dll located in the Revit Program directory. The RevitAPI.dll contains methods used to access Revit's application, documents, elements and parameters at the database level. The RevitAPIUI.dll contains the interfaces related to manipulation and customization of the Revit user interface.
Note that additional API functionality exists in RevitAPIIFC.dll, RevitAPIMacros.dll, and RevitAPIUIMacros.dll, which also install with Revit, but these assemblies are not immediately required to get started.
The Autodesk Revit API Software Development Kit (SDK) is installed from the Tools and Utilities section of the Autodesk Revit installation.
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

19
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Introduction_to_the_Revit_Platform_API_html.md Normal file
View File

@@ -0,0 +1,19 @@
# Introduction to the Revit Platform API
# Introduction to the Revit Platform API
The Revit .NET API allows you to program with any .NET compliant language including Visual Basic.NET, C#, and C++/CLI.
Autodesk Revit offers an API designed to allow power users and external application developers to integrate their applications with Autodesk Revit. It is strongly recommended that you become familiar with Autodesk Revit and its features before attempting to use the Autodesk Revit API. Training can be found through the Autodesk Developer Network (ADN).
Learning Revit can help you:
* Maintain consistency with the Revit UI and commands.
* Design your add-in application seamlessly.
* Utilize API classes and class members efficiently and effectively.
If you are not familiar with Revit or BIM, learn more in the Revit product center at [www.autodesk.com/revit](http://www.autodesk.com/revit).
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

93
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_User_Manual_html.md Normal file
View File

@@ -0,0 +1,93 @@
# User Manual
# User Manual
This document is part of the Revit SDK. It provides an introduction to implementing Revit add-in applications using the Revit Platform API.
Before creating a Revit Platform API add-in application read through the manual and try the sample code. If you already have some experience with the Revit Platform API, you may just want to review the Notes and Troubleshooting sections.
### Introduction to the Revit Platform API
The first two chapters present an introduction to the Revit Platform API and provide an overview of the User Manual.
[Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html) \- Presents an introduction to the Revit Platform API and necessary prerequisite knowledge before you create your first add-in.
[Getting Started](../../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html) \- Step-by-step instructions for creating your first Hello World add-in application using Visual Studio 2022 and four other walkthroughs covering primary add-in functions.
### Basic Topics
These chapters cover the Revit Platform API basic mechanisms and functionality.
[Add-In Integration](../../Revit_API_Revit_API_Developers_Guide_Introduction_Add_In_Integration_html.html) \- Discusses how an add-in is integrated into the Revit UI and invoked by user commands or specific Revit events such as program startup.
[Application and Document](../../Revit_API_Revit_API_Developers_Guide_Introduction_Application_and_Document_html.html) \- Application and Document classes respectively represent the Revit application and project file in the Revit Platform API. This chapter explains basic concepts and links to pertinent chapters and sections.
[Elements Essentials](../../Revit_API_Revit_API_Developers_Guide_Introduction_Elements_Essentials_html.html) \- The bulk of the data in a Revit project is in a collection of Elements. This chapter discusses the essential Element mechanism, classification, and features.
[Filtering](../../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Filtering_html.html) \- Filtering is used to get a set of elements from the document.
[Selection](../../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Selection_html.html) \- Working with the set of selected elements in a document.
[Parameters](../../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_html.html) \- Most Element information is stored as Parameters. This chapter discusses Parameter functionality.
[Collections](../../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Collections_html.html) \- Utility collection types such as Array, Map, Set collections, and related Iterators.
### Element Topics
Elements are introduced based on element classification. Make sure that you read the Elements Essentials and Parameter chapters before reading about the individual elements.
[Editing Elements](../../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Editing_Elements_html.html) \- Learn how to move, rotate, delete, mirror, group, and array elements.
[Walls, Floors, Ceilings, Roofs and Openings](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Walls_Floors_Ceilings_Roofs_and_Openings_html.html) \- Discusses Elements, their corresponding ElementTypes representing built-in place construction, and different types of Openings in the API.
[Family Instances](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Family_Instances_html.html) \- Learn about the relationship between family and family instance, family and family instance features, and how to load or create them.
[Family Creation](../../../Discipline_Specific_Functionality/MEP_Engineering/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_MEP_Engineering_Family_Creation_html.html) \- Learn about creation and modification of Revit Family documents.
[Conceptual Design](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Conceptual_Design_html.html) \- Discusses how to create complex geometry and forms in a Revit Conceptual Mass document.
[Datum and Information Elements](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Datum_and_Information_Elements_html.html) \- Learn how to set up grids, add levels, use design options, and more.
[Annotation Elements](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Annotation_Elements_html.html) \- Discusses document annotation including adding dimensions, detail curves, tags, and annotation symbols.
[Sketching](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Sketching_html.html) \- Sketch functions include 2D and 3D sketch classes such as SketchPlane, ModelCurve, GenericForm, and more.
[Views](../../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Views_html.html) \- Learn about the different ways to view models and components and how to manipulate the view in the API.
[Material](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Material_html.html) \- Material data is an Element that identifies the physical materials used in the project as well as texture, color, and more.
### Advanced Topics
[Geometry](../../../Revit_Geometric_Elements/Revit_API_Revit_API_Developers_Guide_Revit_Geometric_Elements_Geometry_html.html) \- Discusses graphics-related types in the API used to describe the graphical representation of the model including the three classes that describe and store the geometry information.
[Place and Locations](../../../Advanced_Topics/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Place_and_Locations_html.html) \- Defines the project location including city, country, latitude, and longitude.
[Shared Parameters](../../../Basic_Interaction_with_Revit_Elements/Parameters/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Parameters_Shared_Parameters_html.html) \- Shared parameters are external text files containing parameter specifications. This chapter introduces how to access to shared parameters through the Revit Platform API.
[Transactions](../../../Basic_Interaction_with_Revit_Elements/Revit_API_Revit_API_Developers_Guide_Basic_Interaction_with_Revit_Elements_Transactions_html.html) \- Introduces the two uses for Transaction and the limits that you must consider when using Transaction.
[Events](../../../Appendices/Glossary/Revit_API_Revit_API_Developers_Guide_Appendices_Glossary_Events_html.html) \- Discusses how to take advantage of Revit Events.
[Dynamic Model Update](../../../Advanced_Topics/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Dynamic_Model_Update_html.html) \- Learn how to use updaters to modify the model in reaction to changes in the document.
[Failure Posting and Handling](../../../Advanced_Topics/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Failure_Posting_and_Handling_html.html) \- Learn how to post failures and interact with Revit's failure handling mechanism.
[Analysis Visualization](../../../Advanced_Topics/Analysis/Revit_API_Revit_API_Developers_Guide_Advanced_Topics_Analysis_Analysis_Visualization_html.html) \- How to display analysis results in a Revit project.
### Discipline Specific
Revit includes discipline-specific features for architecture, structural engineering, and MEP engineering. Some APIs only work for specific feature sets.
[Architecture](../../../Discipline_Specific_Functionality/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_Architecture_html.html) \- Discusses the APIs specific to the architectural features of Revit.
[Structural Engineering](../../../Discipline_Specific_Functionality/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_Structural_Engineering_html.html) \- Discusses the APIs specific to the structural engineering features of Revit.
[MEP Engineering](../../../Discipline_Specific_Functionality/Revit_API_Revit_API_Developers_Guide_Discipline_Specific_Functionality_MEP_Engineering_html.html) \- Discusses the APIs specific to the mechanical, electrical, and plumbing features of Revit.
### Other
[Glossary](../../../Appendices/Revit_API_Revit_API_Developers_Guide_Appendices_Glossary_html.html) \- Definitions of terms used in this document.
[Appendices](../../../Revit_API_Revit_API_Developers_Guide_Appendices_html.html) \- Additional information such as Frequently Asked Questions, Using Visual Basic.Net for programming, and more.
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

22
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_What_Can_You_Do_with_the_Revit_Platform_API_html.md Normal file
View File

@@ -0,0 +1,22 @@
# What Can You Do with the Revit Platform API?
# What Can You Do with the Revit Platform API?
The following are general areas where the API is suitable:
* Creating add-ins and macros to automate repetitive tasks in the Autodesk Revit user interface
* Enforcing project design standards by checking for errors automatically
* Extracting project data for analysis and to generate reports
* Importing external data to create new elements or parameter values
* Integrating other applications, including analysis applications, into Autodesk Revit products
* Creating Autodesk Revit project documentation automatically
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

16
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_What_You_Will_Need_to_Get_Started_html.md Normal file
View File

@@ -0,0 +1,16 @@
# What You Will Need to Get Started
# What You Will Need to Get Started
1. A working understanding of Autodesk Revit.
2. An installation of an Autodesk Revit-based product, including the Software Development Kit.
3. MS Visual Studio 2022 Community Edition (C# or VB.NET). Microsoft Visual Studio 2022 Professional is recommended, though, as Community editions do not support DLL debugging. Alternatively, you can use the built-in SharpDevelop development environment in Revit.
4. Some experience in a .NET based development language. (Autodesk Revit API examples are provided in C# and Visual Basic.NET.)
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

7
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Whats_new_in_this_release_html.md Normal file
View File

@@ -0,0 +1,7 @@
# What's New in this Release
# What's New in this Release
Please see the "What's New" section in RevitAPI.chm (included in the Revit API SDK) for information about changes and new features.
**Parent page:** [Welcome to the Revit Platform API](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)

37
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.md Normal file
View File

@@ -0,0 +1,37 @@
# Welcome to the Revit Platform API
# Welcome to the Revit Platform API
All Autodesk Revit-based products are Parametric Building Information Modeling (BIM) tools. Such a tool can be looked at as a CAD program that is used to build a 3D model rather than a set of individual drawing files. Autodesk Revit modeling is accomplished with real-world elements like columns, walls, doors and windows. The user can create views of the model, including plans, sections and callouts. All these views are directly generated from the 3D physical model so changes made in one view will automatically propagate through all other views. This process virtually eliminates the need to update multiple drawings and details when a change is made in the model.
The Autodesk Revit API is designed to reflect the same user interaction paradigms as the program's Graphical User Interface. Therefore, the first step to understanding the API is to learn how to use the program. If you are an Autodesk Revit novice, we suggest you first start by going through the Tutorials which you can access through the program's Help menu. You may also find it helpful to take a Training class from your local Autodesk reseller. This will help you quickly get up to speed with the program
Autodesk Resources:
* <https://www.autodesk.com/products/revit/overview>
* <https://www.autodesk.com/solutions/aec/bim>
* <https://forums.autodesk.com/t5/revit-api-forum/bd-p/160>
External Resources:
* <http://forums.augi.com/forumdisplay.php?93-Revit>
**Pages in this section**
* [Introduction to the Revit Platform API](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Introduction_to_the_Revit_Platform_API_html.html)
* [What Can You Do with the Revit Platform API?](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_What_Can_You_Do_with_the_Revit_Platform_API_html.html)
* [What You Will Need to Get Started](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_What_You_Will_Need_to_Get_Started_html.html)
* [Installation](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Installation_html.html)
* [Development Requirements](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Development_Requirements_html.html)
* [User Manual](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_User_Manual_html.html)
* [Documentation Conventions](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Documentation_Conventions_html.html)
* [What's New in this Release](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Whats_new_in_this_release_html.html)
* [Third-Party Component Versions](Welcome_to_the_Revit_Platform_API/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_Component_Versions_html.html)
**Parent page:** [Getting Started](../Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.html)

19
Output/revit-api-guide/Introduction/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_html.md Normal file
View File

@@ -0,0 +1,19 @@
# Getting Started
# Getting Started
The Revit Platform API is fully accessible by any language compatible with Microsoft .NET 8.0, such as Visual C# or Visual Basic .NET (VB.NET). Both Visual C# and VB.NET are commonly used to develop Revit Platform API applications. However, the focus of this manual is developing applications using Visual C#.
**Pages in this section**
* [Welcome to the Revit Platform API](Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Welcome_to_the_Revit_Platform_API_html.html)
* [Using the Autodesk Revit API](Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Using_the_Autodesk_Revit_API_html.html)
* [Walkthroughs](Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthroughs_html.html)
* [Walkthrough: Hello World](Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Hello_World_html.html)
* [Walkthrough: Add Hello World Ribbon Panel](Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Add_Hello_World_Ribbon_Panel_html.html)
* [Walkthrough: Retrieve Selected Elements](Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Retrieve_Selected_Elements_html.html)
* [Walkthrough: Retrieve Filtered Elements](Getting_Started/Revit_API_Revit_API_Developers_Guide_Introduction_Getting_Started_Walkthrough_Retrieve_Filtered_Elements_html.html)
**Parent page:** [Introduction](../Revit_API_Revit_API_Developers_Guide_Introduction_html.html)