There are several Document methods for use with a workshared project file.
If a document is not already workshared, which can be determined from the Document.IsWorkshared property, worksharing can be enabled via the Revit API using the Document.EnableWorksharing() method. The document's Undo history will be cleared by this command, therefore this command and others executed before it cannot be undone. Additionally, all transaction phases (e.g. transactions, transaction groups and sub-transactions) that were explicitly started must be finished prior to calling EnableWorksharing().
The method Document.ReloadLatest() retrieves changes from the central model (due to one or more synchronizations with central) and merges them into the current session.
The following examples uses ReloadLatest() to update the current session after confirming with the user that it is OK to do so.
|
Code Region: Reload from Central |
public static void ReloadLatestWithMessage(Document doc)
{
// Tell user what we're doing
TaskDialog td = new TaskDialog("Alert");
td.MainInstruction = "Application 'Automatic element creator' needs to reload changes from central in order to proceed.";
td.MainContent = "This will update your local with all changes currently in the central model. This operation " +
"may take some time depending on the number of changes available on the central.";
td.CommonButtons = TaskDialogCommonButtons.Ok | TaskDialogCommonButtons.Cancel;
TaskDialogResult result = td.Show();
if (result == TaskDialogResult.Ok)
{
// There are no currently customizable user options for ReloadLatest.
doc.ReloadLatest(new ReloadLatestOptions());
TaskDialog.Show("Proceeding...", "Reload operation completed, proceeding with updates.");
}
else
{
TaskDialog.Show("Canceled.", "Reload operation canceled, so changes will not be made. Return to this command later when ready to reload.");
}
}
|
The method Document.SynchronizeWithCentral() reloads any changes from the central model so that the current session is up to date and then saves local changes back to central. A save to central is performed even if no changes were made.
When using SynchronizeWithCentral(), options can be specified for accessing the central model as well as synchronizing with it. The main option for accessing the central is to determine how the call should behave if the central model is locked. Since the synchronization requires a temporary lock on the central model, it cannot be performed if the model is already locked. The default behavior is to wait and repeatedly try to lock the central model in order to proceed with the synchronization. This behavior can be overridden using the TransactWithCentralOptions parameter of the SynchronizeWithCentral() method.
The SynchronizeWithCentralOptions parameter of the method is used to set options for the actual synchronization, such as whether elements or worksets owned by the current user should be relinquished during synchronization.
In the following example, an attempt is made to synchronize with a central model. If the central model is locked, it will immediately give up.
|
Code Region: Synchronize with Central |
public void SyncWithoutRelinquishing(Document doc)
{
// Set options for accessing central model
TransactWithCentralOptions transOpts = new TransactWithCentralOptions();
SynchLockCallback transCallBack = new SynchLockCallback();
// Override default behavior of waiting to try again if the central model is locked
transOpts.SetLockCallback(transCallBack);
// Set options for synchronizing with central
SynchronizeWithCentralOptions syncOpts = new SynchronizeWithCentralOptions();
// Sync without relinquishing any checked out elements or worksets
RelinquishOptions relinquishOpts = new RelinquishOptions(false);
syncOpts.SetRelinquishOptions(relinquishOpts);
// Do not automatically save local model after sync
syncOpts.SaveLocalAfter = false;
syncOpts.Comment = "Changes to Workset1";
try
{
doc.SynchronizeWithCentral(transOpts, syncOpts);
}
catch (Exception e)
{
TaskDialog.Show("Synchronize Failed", e.Message);
}
}
class SynchLockCallback : ICentralLockedCallback
{
// If unable to lock central, give up rather than waiting
public bool ShouldWaitForLockAvailability()
{
return false;
}
}
|
In the next example, the user is given a message prior to synching, and is given options on whether to relinquish all elements when synchronizing, or keep worksets checked out.
|
Code Region: Synchronize with Central With Message |
public static void SynchWithCentralWithMessage(Document doc)
{
// Checkout workset (for use with "keep checked out worksets" option later)
FilteredWorksetCollector fwc = new FilteredWorksetCollector(doc);
fwc.OfKind(WorksetKind.UserWorkset);
Workset workset1 = fwc.First<Workset>(ws => ws.Name == "Workset1");
WorksharingUtils.CheckoutWorksets(doc, new WorksetId[] { workset1.Id });
// Make a change
using (Transaction t = new Transaction(doc, "Add Level"))
{
t.Start();
Level.Create(doc, 100);
t.Commit();
}
// Tell user what we're doing
TaskDialog td = new TaskDialog("Alert");
td.MainInstruction = "Application 'Automatic element creator' has made changes and is prepared to synchronize with central.";
td.MainContent = "This will update central with all changes currently made in the project by the application or by the user. This operation " +
"may take some time depending on the number of changes made by the app and by the user.";
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink1, "Do not synchronize at this time.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink2, "Synchronize and relinquish all elements.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink3, "Synchronize but keep checked out worksets.");
td.DefaultButton = TaskDialogResult.CommandLink1;
TaskDialogResult result = td.Show();
switch (result)
{
case TaskDialogResult.CommandLink1:
default:
{
// Do not synch. Nothing to do.
break;
}
case TaskDialogResult.CommandLink2:
case TaskDialogResult.CommandLink3:
{
// Prepare to synch
// TransactWithCentralOptions has to do with the behavior related to locked or busy central models.
// We'll use the default behavior.
TransactWithCentralOptions twcOpts = new TransactWithCentralOptions();
// Setup synch-with-central options (add a comment about our change)
SynchronizeWithCentralOptions swcOpts = new SynchronizeWithCentralOptions();
swcOpts.Comment = "Synchronized by 'Automatic element creator' with user acceptance.";
if (result == TaskDialogResult.CommandLink3)
{
// Setup relinquish options to keep user worksets checked out
RelinquishOptions rOptions = new RelinquishOptions(true);
rOptions.UserWorksets = false;
swcOpts.SetRelinquishOptions(rOptions);
}
doc.SynchronizeWithCentral(twcOpts, swcOpts);
break;
}
}
}
|
The WorksharingUtils.CreateNewLocal() method copies a central model to a new local file. This method does not open the new file. For an example of creating a new local model and opening it, see Opening a Workshared Document