HandShaking with Revit

After we got to know what are the possible access to Revit. Lets Implement one.

Create a HandShaking App.

these are the steps we will take in this post, to write our first Revit app.

1. Setup a dll library Project.
2. Reference Revit dlls 
3. Use Revit library in your Class
4. Decorate your Class with Transaction [for more information about this step see here]
5. implement Interface
6. Write your Code
7. Create a Manifest File 
8. Security Concerns
9. Hand Shake with Revit

Setup a dll library Project

We have already explained in a previous My First C# Program how to setup a project. However, that post was for a Console Application. This time we will choose a dll library Project. follow the same steps in the "My First C# Program" post and instead of Selecting Console Application, select  Class Library Project.

You can Set your Project Name anything you want. We will name it "LAI02_HandShaking"

Reference Revit dlls 

Since we need to write an application that communicate with Revit, we need to feed our program with extra information about Revit. Gladly, Autodesk allowed access to Revit through specific dlls. `RevitAPIUI.dll` and `RevitAPI.dll`. These two files can be found here:

[your Revit Installation Folder\RevitAPI.dll]

example: 

• D:\Program Files\Autodesk\Revit 2020\RevitAPI.dll
• D:\Program Files\Autodesk\Revit 2020\RevitAPIUI.dll

to reference these two files to our project follow these steps:

Go to Solution Explorer right click on Reference Select: Add Reference Browse for these 2 library files select both and click on Add. then Click OK.

for a quick view see this Video.

Since all necessary dll files already exists under Revit folder, It is preferable to set Local Copy to false, this will avoid copying those dll files to your output folder.

Note: adding a reference to you project doesn't mean we are using them. we have to explicitly tell our program to use or to address them.

Use Revit library in your Class

Add using statements to inform our Project we need these library in our project.

```using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
```

you can think of these using statements as if you opened a book in a library and kept it open on a specific chapter, so you can easily pick information from.

Decorate your Class with Transaction

above LAI02_HandShaking Class add this decoration

```[Transaction(TransactionMode.Manual)]```

we gave a little bit explanation about what are these decoration in a previous post. but in short, it is required to allow Revit recognize what is the intention of this class is it going to modify the Document or will only Read its contents.

TransactionMode has 2 values. either `Manual` or `ReadOnly`

Implement Interface

Interface is defined by Tutorials Teacher as:

An interface is like a contract. In the human world, the contract between the two or more humans binds them to act as per the contract. In the same way, the interface includes the declaration of one or more functionalities. Entities that implement the interface must define functionalities declared in the interface. In C#, a class or a struct can implement one or more interfaces.~Tutorials Teacher

 with that said you can think of it a list of a must to do list. and like we previously mentioned, it is a requirement to allow Revit recognize this class for accessing. see our Post IExternalCommand is an Access

now move your mouse pointer in your code editor and right click on IExternalCommand, then select Quick Actions and Refactoring...
then select Implement interface.
you can also click on (Ctrl + Period)

now your class should look like this by now:
```[Transaction(TransactionMode.Manual)]
public class LAI02_HandShaking: IExternalCommand
{
    public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
    {
        throw new System.NotImplementedException();
    }
}```

Write your Code

now we are ready to write our first statement. Remove this line

```throw new System.NotImplementedException();```

and write the below

```TaskDialog.Show("HandShaking", "Welcome Professor");
return Result.Succeeded;```

TaskDialog: is a static class library provided by Autodesk and its purpose is to display messages in a window box. it is explained in RevitAPIDoc as

A task dialog is a dialog box that 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.~RevitAPIDoc

and finally your full class.cs file should look like this:
```using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;

namespace LAI02_HandShaking
{
    [Transaction(TransactionMode.Manual)]
    public class LAI02_HandShaking: IExternalCommand
    {
        public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
        {
            TaskDialog.Show("HandShaking", "Welcome Professor");
            return Result.Succeeded;
        }
    }
}```

Now build your Project, Right click on your Project Name in the Solution Explorer and select Build

Create a Manifest File

A manifest file is like an administrative works. I will detail more about this file in a separate post, but in brief, Since Revit does know nothing about your dll file. Revit API setup a strategy to identify what dll file it should look at. this File is a text file with extension `.addin `containing
```<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
        <AddIn Type="Command">
        <Assembly>D:\Dropbox\API Tutorial\LAI02_HandShaking\LAI02_HandShaking\bin\Debug\LAI02_HandShaking.dll</Assembly>
        <AddInId>239BD853-36E4-461f-9171-C5ACEDA4E111</AddInId>
        <FullClassName>LAI02_HandShaking.LAI02_HandShaking</FullClassName>
        <Text>HandShaking</Text>
        <VendorId>arch4hum</VendorId>
        <VendorDescription>Let's API It</VendorDescription>
        </AddIn>
</RevitAddIns>
```

Now copy the above and start any text editor such as NotePad. and past these in. You need to ensure that line 4 is exactly pointing to your Project Location. then Save this file as LAI02_HandShaking.addin to this locaiton
```C:\ProgramData\Autodesk\Revit\Addins\2020\LAI02_HandShaking.addin```
you need to change 2020 to you related Revit version.

Now Start Revit

Security Concerns

starting from Revit 2017 Autodesk add more control on how additional dll libraries are loaded. in that sense the moment you start Revit and recognize your addin/dll file... it will pop up this message.

Click always load, as long as we are the developer of this addin, aren't we? :)

Hand Shake with Revit

click on addinTab, and click on External Tools button, and select HandShaking

by now, you have completed your first Step to integrate with Revit.

API Entry to Revit World

As we got to know what is API, lets understand how to implement communication between User and Revit.

of course saying let's implement something needs some basic understanding, like translating what a statement points to on Revit. What is Document, and what is UI Document. What is Application, and Transaction.... you don't have to worry about all these terms... gradually you will get know how things works. but in order to be fully familiar with Let's API It you need to have a basic understanding of programming, specifically, Object Oriented Programming (OOP).

UIApplication

UIApplication is the root container of everything in Revit. First you need to think of the computer way of work is like a train. A train moves on rail till it reaches its final destination. and the final destination of a computer work is terminating the application.

See how RevitAPIdoc identify it

Represents an active session of the Autodesk Revit user interface, providing access to UI customization methods, events, the main window, and the active document.  You can access documents from the database level Application object, obtained from the Application property. If you have an instance of the database level Application object, you can construct a UIApplication instance from it.  ~RevitAPIDoc

this is our guy, the Revit Application, which its definition in API is UIApplication. so let's brainstorm your thoughts... What functions expected to be found in this class UIApplication?
...
..
.
Well your guess would be right if you thought of Open/Close Projects/Families..etc. but definitely uiapp has a lot of functions to do. and going through them all we will write millions of posts to cover it all. however, we will keep visiting uiapp through this blog on the necessity to do something.

for now you need to know this is the UIApplication.

but the question could be how on earth i as individual, get an access to tell Revit show me all your mighty?

Googled Image

That is exactly what you need to start to think of "an Access". you need to be aware, that the owner of any Program, if there is a will to let users access their core program function, then there must a design considered for this. meaning there would be no API if originally the application is not designed for that.

Thanks Autodesk for allowing us to do our job the way it suites our needs. you can think of it like the USB Port in your PC. if there is no Port for USB you will never be able to access your USB stick.

I will explain in detail how you setup this access, in another post. but first I need to setup some basic understandings before we start our engine. so please be patient.

What you should also be aware of for now, once Revit starts and loads its Window interface, it starts looking for any available IExternalCommand and IExternalApplication Classes that can be executed. you can think of these two classes as the USB pins, if they match what Revit is looking for, then we have entered Revit World. and as a start Revit instantly sends, its first gift to you, an object called UIControlledApplication.

UIControlledApplication 

This is an argument sent from Revit when it successfully get connected to a new addin. It contains very minimal information, but enough to take you inside and setup your program. it allows you to add an icon/Button to your application. when to show your button and when not. additionally some very useful events such as Idling. again we will explain more about these methods and events by time.

RevitApiDoc defined it as

Represents the Autodesk Revit user interface, providing access to UI customization methods and events.This class does not provide access to documents because it is provided to you through the ExternalApplication OnStartup()/OnShutdown() methods, and those methods are when it is not possible to work with Revit documents. You can work with documents by getting them from the UIApplication class; that class is obtained from events and ExternalCommand callbacks. ~RevitAPIDoc

 well that's it for now. the next post we will talk about how to setup your program to get connected to Revit.