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.