As a developer, the one thing that is almost as important to me as my development environment is the documentation for the libraries I plan on using. Documentation is broken up into two different pieces of information: reference and concepts.
- Reference documentation is used to explain the namespaces, classes, and members that make up a library. Members might be methods, properties, or enumerators.
- Concepts, often referred to as developer topics, explain how to implement various parts of a library in your program.
These two things aren't earth shattering by any means, but that is the general way I approach the organization of the AutoCAD developer documentation. What is most important to you as a developer is where this documentation exists so you can do your job, and that is to write the programs that your customers or company expect.
The ObjectARX SDK is a set of not only library and header files that describe the AutoCAD ObjectARX and Managed .NET APIs, but also contains sample projects and most importantly the documentation for these two APIs (or most of it, more on that in a bit). The ObjectARX SDK, is essential, whether you are developing applications with C++ or VB.NET/C#. You can download the ObjectARX SDK from http://www.objectarx.com/. Once downloaded, execute the EXE file to install the ObjectARX SDK which wants to be installed to an Autodesk folder under root drive of your workstation.
The ObjectARX SDK contains 11 folders:
- Classmap - Drawing file that outlines the hierarchy of the ObjectARX, Managed .NET, and ActiveX object models.
- Docs - CHM files that make up most of the ObjectARX and Managed .NET documentation set, with the exception of the Managed .NET Developer's Guide.
- Inc - Platform independent library and header files for developing ObjectARX and Managed .NET applications.
- Inc-Win32 - Windows 32-bit (x86) library and header specific files for developing ObjectARX and Managed .NET applications.
- Inc-x64 - Windows 64-bit (x64) library and header specific files for developing ObjectARX and Managed .NET applications.
- Lib-Win32 - Windows 32-bit (x86) library specific files for developing ObjectARX applications.
- Lib-x64 - Windows 64-bit (x64) library specific files for developing ObjectARX applications.
- Redistrib-Win32 - Precompiled DBX files for the AecModeler and Hidden Line Representation libraries that can be distributed with your 32-bit applications.
- Redistrib-x64 -Precompiled DBX files for the AecModeler and Hidden Line Representation libraries that can be distributed with your 64-bit applications.
- Samples - Sample projects that demonstrate various aspects of the ObjectARX and Managed .NET APIs.
- Utils - Additional libraries that are less frequently used; AModeler, Atil, BRep, and Hidden Line Representation.
My main focus is on the developer documentation, so that is what this article will be focusing on. if you want additional information on the various other parts of the ObjectARX SDK, see the developer documentation. :)
The Classmap provides a visual representation of how the objects in the ObjectARX, Managed .NET, and ActiveX libraries are related to each other. This can be helpful in understanding object inheritance or where an object is located within the object models.
ObjectARX and Managed .NET Documentation
A majority of the ObjectARX and Managed .NET documentation is only available from the CHM files that are in the Docs folder of the ObjectARX SDK installation folder. The following provides a summary of each CHM file that is available:
- arxdev.chm - ObjectARX Developer's Guide which contains concepts related to developing applications with the ObjectARX API.
- arxdoc.chm - Main file that allows you to search and browse all of the available CHM files located in the folder from a single documentation file.
- arxiop.chm - Interoperability Guide which outlines the best practices to use when developing and deploying your applications.
- arxmgd.chm - Managed .NET Reference Guide which provides information about the classes and members exposed in the library files of the AutoCAD Managed .NET API.
- arxmgr.chm - Migration Guide which contains information about updating applications to 64-bit, and handling the New Tab Page and changes to the graphics system.
- arxref.chm - ObjectARX Reference Guide which provides information about the classes and members exposed in the header and library files of the ObjectARX API.
- readarx.chm - ObjectARX Readme that contains last minute changes or important information on the changes in the latest release
The Managed .NET Developer's Guide until recently has only been available online (http://bit.ly/1RdYZ2L), but starting with the AutoCAD 2017 release it is now also available as a CHM file for offline viewing. The CHM file for the Managed .NET Developer's Guide is not part of the ObjectARX SDK and must be downloaded separately, a ZIP file containing the CHM file and a new version of the arxdoc.chm file can be downloaded directly from http://bit.ly/1pxfLz8. After downloading the file, copy the two CHM files into the Docs folder of the ObjectARX SDK installation folder.
Making the Managed .NET Developer's Guide available offline has been an on going request for several years now, so let us know what you think and if there is anything we can improve. As time goes along, additional index terms will be added to topics to improve the discoverability of topics.
Accessing Developer Documentation from Visual Studio
CHM files are the current backbone of the ObjectARX and Managed .NET developer documentation, but parts of the documentation can be accessed from within Microsoft Visual Studio. Since AutoCAD 2012, a separate Help installer has allowed for the integration of the ObjectARX and Managed .NET Reference Guides into Microsoft Visual Studio. This integration provides:
- Contextual F1 support from a code editor window; highlight a member's name and press F1 to open the Microsoft Help Viewer to the specific topic.
- Browse and search the reference topics from within Microsoft Visual Studio without needing to browse to and open the CHM files. The integrated help contains the same content as the CHM files.
To utilize the integrated help within Microsoft Visual Studio, download one of the following ZIP files and run the installer:
- AutoCAD 2017 (supports Microsoft Visual Studio 2015)
- AutoCAD 2016 (supports Microsoft Visual Studio 2012 and 2013)
- AutoCAD 2015 (supports Microsoft Visual Studio 2012)
- AutoCAD 2014 (supports Microsoft Visual Studio 2010 and 2012)
- AutoCAD 2013 (supports Microsoft Visual Studio 2010)
- AutoCAD 2012 (supports Microsoft Visual Studio 2010)
Starting with AutoCAD 2017, some of the reference content can be accessed via tooltips with the Intellisense feature and Object Browser in Microsoft Visual Studio. This is done by providing segments of the content as XML documentation for each of the public AutoCAD Managed .NET libraries. Not all classes and members have documentation at this moment, but 85+% have some form of documentation at this time. This is very much a work in progress yet.
To utilize the XML documentation, download one of the following ZIP files and extract its contents to the location in which you reference the AutoCAD Managed .NET DLLs from for you projects:
While the XML documentation has only been created back to AutoCAD 2015, it is possible to use the XML documentation for AutoCAD 2015 with an earlier version of the AutoCAD Managed .NET libraries. For example, simply download the ZIP file created for AutoCAD 2015 and extract the XML files into the location of the AutoCAD 2014 libraries. The XML documentation should be recognized by Microsoft Visual Studio and displayed in the environment.
Note: The XML documentation will also part of the official AutoCAD 2017 .NET NuGet packages (https://www.nuget.org/packages/AutoCAD.NET/) once they have been published.
I will expand on the in Microsoft Visual Studio integrated help and XML documentation in a future article. These two features can be huge productivity gains as a developer.
If you have any comments about the developer documentation please let me know. I am always looking for ways to improve the content and access to the developer documentation.