Document and File Management

Document and file management make it easy to create and find your documents.

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.

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)	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.

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 NewFamilyDocument(string templateFileName);	DocumentCreated
Document NewProjectTemplateDocument(string templateFilename);	DocumentCreated

Each method requires a template file name as the parameter. The created document is returned based on the template file.

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 specifies whether to rename the file and/or whether to overwrite and 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
    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 Loading Families.