Document and File Management

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

Document OpenDocumentFile(string filename )
Document OpenDocumentFile(ModelPath modelPath, OpenOptions openOptions)

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 method throws Autodesk.Revit.Exceptions.InvalidOperationException if you try to open unsupported file types. If the document is opened successfully, the DocumentOpened event is raised.

The second overload takes a path to the model as a ModelPath rather than a string and the OpenOptions parameter offerst the ability to detach the opened document from central if applicable.

Create a Document

Create new documents using the Application methods in the following table.

Table 4: Create Document in the API

Document NewProjectDocument(string templateFileName);

Document NewFamilyDocument(string templateFileName);

Document NewProjectTemplateDocument(string templateFilename);

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 5: Save and Close Document in API

SaveAs() has 3 overloads. Two overloads take the filename as an argument and but an exception will be thrown if another file exists with the given filename. The third overload takes a filename as an argument as well as a second argument that specifies whether to rename the file and/or whether to overwrite and existing file, if it exists.

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.

The UIDocument class also provides methods to save and close instances.

Table 6: Save and Close UIDocument in API

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.

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.