How to: Protect parts of documents by using content controls

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

When you protect part of a document, you prevent users from changing or deleting the content in that part of the document. There are several ways you can protect parts of a Microsoft Office Word document by using content controls:

• You can protect a content control.

• You can protect a part of a document that is not in a content control.

  Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for Word. For more information, see Features available by Office application and project type.

Protect a content control

You can prevent users from editing or deleting a content control by setting properties of the control in a document-level project at design time or at run time.

You can also protect content controls that you add to a document at run time by using a VSTO Add-in project. For more information, see How to: Add content controls to Word documents.

To protect a content control at design time

1. In the document that is hosted in the Visual Studio designer, select the content control that you want to protect.

2. In the Properties window, set one or both of the following properties:

   • To prevent users from editing the control, set LockContents to True.

   • To prevent users from deleting the control, set LockContentControl to True.

3. Click OK.

To protect a content control at run time

1. Set the LockContents property of the content control to true to prevent users from editing the control, and set the LockContentControl property to true to prevent users from deleting the control.

   The following code example demonstrates using the LockContents and LockContentControl properties of two different RichTextContentControl objects in a document-level project. To run this code, add the code to the ThisDocument class in your project, and call the AddProtectedContentControls method from the ThisDocument_Startup event handler.

   private Microsoft.Office.Tools.Word.RichTextContentControl deletableControl;
   private Microsoft.Office.Tools.Word.RichTextContentControl editableControl;
   
   private void AddProtectedContentControls()
   {
       this.Paragraphs[1].Range.InsertParagraphBefore();
       Word.Range range1 = this.Paragraphs[1].Range;
   
       deletableControl = this.Controls.AddRichTextContentControl(range1,
           "deletableControl");
       deletableControl.PlaceholderText = "You can delete this control, " +
           "but you cannot edit it";
       deletableControl.LockContents = true;
   
       range1.InsertParagraphAfter();
       Word.Range range2 = this.Paragraphs[2].Range;
   
       editableControl = this.Controls.AddRichTextContentControl(range2,
           "editableControl");
       editableControl.PlaceholderText = "You can edit this control, " +
           "but you cannot delete it";
       editableControl.LockContentControl = true;
   }
   

   Dim deletableControl As Microsoft.Office.Tools.Word.RichTextContentControl
   Dim editableControl As Microsoft.Office.Tools.Word.RichTextContentControl
   
   Private Sub AddProtectedContentControls()
       Me.Paragraphs(1).Range.InsertParagraphBefore()
       Dim range1 As Word.Range = Me.Paragraphs(1).Range
   
       deletableControl = Me.Controls.AddRichTextContentControl(range1, _
           "deletableControl")
       deletableControl.PlaceholderText = "You can delete this control, " & _
           "but you cannot edit it"
       deletableControl.LockContents = True
   
       range1.InsertParagraphAfter()
       Dim range2 As Word.Range = Me.Paragraphs(2).Range
   
       editableControl = Me.Controls.AddRichTextContentControl(range2, _
           "editableControl")
       editableControl.PlaceholderText = "You can edit this control, " & _
           "but you cannot delete it"
       editableControl.LockContentControl = True
   End Sub
   

   The following code example demonstrates using the LockContents and LockContentControl properties of two different RichTextContentControl objects in a VSTO Add-in project. To run this code, add the code to the ThisAddIn class in your project, and call the AddProtectedContentControls method from the ThisAddIn_Startup event handler.

   Dim deletableControl As Microsoft.Office.Tools.Word.RichTextContentControl
   Dim editableControl As Microsoft.Office.Tools.Word.RichTextContentControl
   
   Private Sub AddProtectedContentControls()
   
       Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
           Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       vstoDocument.Paragraphs(1).Range.InsertParagraphBefore()
       Dim range1 As Word.Range = vstoDocument.Paragraphs(1).Range
   
       deletableControl = vstoDocument.Controls.AddRichTextContentControl(range1, _
           "deletableControl")
       deletableControl.PlaceholderText = "You can delete this control, " & _
           "but you cannot edit it"
       deletableControl.LockContents = True
   
       range1.InsertParagraphAfter()
       Dim range2 As Word.Range = vstoDocument.Paragraphs(2).Range
   
       editableControl = vstoDocument.Controls.AddRichTextContentControl(range2, _
           "editableControl")
       editableControl.PlaceholderText = "You can edit this control, " & _
           "but you cannot delete it"
       editableControl.LockContentControl = True
   End Sub
   

   private Microsoft.Office.Tools.Word.RichTextContentControl deletableControl;
   private Microsoft.Office.Tools.Word.RichTextContentControl editableControl;
   
   private void AddProtectedContentControls()
   {
       Microsoft.Office.Tools.Word.Document vstoDocument = 
           Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
       vstoDocument.Paragraphs[1].Range.InsertParagraphBefore();
       Word.Range range1 = vstoDocument.Paragraphs[1].Range;
   
       deletableControl = vstoDocument.Controls.AddRichTextContentControl(range1,
           "deletableControl");
       deletableControl.PlaceholderText = "You can delete this control, " +
           "but you cannot edit it";
       deletableControl.LockContents = true;
   
       range1.InsertParagraphAfter();
       Word.Range range2 = vstoDocument.Paragraphs[2].Range;
   
       editableControl = vstoDocument.Controls.AddRichTextContentControl(range2,
           "editableControl");
       editableControl.PlaceholderText = "You can edit this control, " +
           "but you cannot delete it.";
       editableControl.LockContentControl = true;
   }
   

Protect a part of a document that is not in a content control

You can prevent users from changing an area of a document by putting the area in a GroupContentControl. This is useful in the following scenarios:

• You want to protect an area that does not contain content controls.

• You want to protect an area that already contains content controls, but the text or other items that you want to protect are not in the content controls.

Note

If you create a GroupContentControl that contains embedded content controls, the embedded content controls are not automatically protected. To prevent users from editing an embedded content control, use the LockContents property of the control.

To protect an area of a document at design time

1. In the document that is hosted in the Visual Studio designer, select the area that you want to protect.

2. On the Ribbon, click the Developer tab.

   Note

   If the Developer tab is not visible, you must first show it. For more information, see How to: Show the developer tab on the ribbon.

3. In the Controls group, click the Group drop-down button, and then click Group.

   A GroupContentControl that contains the protected region is automatically generated in the ThisDocument class in your project. A border that represents the group control is visible at design time, but there is no visible border at run time.

To protect an area of a document at run time

1. Programmatically select the area that you want to protect, and then call the AddGroupContentControl method to create a GroupContentControl.

   The following code example for a document-level project adds text to the first paragraph in the document, selects the first paragraph, and then instantiates a GroupContentControl. To run this code, add the code to the ThisDocument class in your project, and call the ProtectFirstParagraph method from the ThisDocument_Startup event handler.

   private Microsoft.Office.Tools.Word.GroupContentControl groupControl1;
   
   private void ProtectFirstParagraph()
   {
       this.Paragraphs[1].Range.InsertParagraphBefore();
       Word.Range range1 = this.Paragraphs[1].Range;
   
       range1.Text = "You cannot edit or change the formatting of text " +
           "in this sentence, because this sentence is in a GroupContentControl.";
       range1.Select();
       groupControl1 = this.Controls.AddGroupContentControl("groupControl1");
   }
   

   Dim groupControl1 As Microsoft.Office.Tools.Word.GroupContentControl
   
   Private Sub ProtectFirstParagraph()
       Me.Paragraphs(1).Range.InsertParagraphBefore()
       Dim range1 As Word.Range = Me.Paragraphs(1).Range
       range1.Text = "You cannot edit or change the formatting of text " & _
               "in this paragraph, because this paragraph is in a GroupContentControl."
       range1.Select()
   
       groupControl1 = Me.Controls.AddGroupContentControl("groupControl1")
   End Sub
   

   The following code example for a VSTO Add-in project adds text to the first paragraph in the active document, selects the first paragraph, and then instantiates a GroupContentControl. To run this code, add the code to the ThisAddIn class in your project, and call the ProtectFirstParagraph method from the ThisAddIn_Startup event handler.

   Dim groupControl1 As Microsoft.Office.Tools.Word.GroupContentControl
   
   Private Sub ProtectFirstParagraph()
   
       Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
           Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       VstoDocument.Paragraphs(1).Range.InsertParagraphBefore()
   
       Dim range1 As Word.Range = VstoDocument.Paragraphs(1).Range
       range1.Text = "You cannot edit or change the formatting of text " & _
               "in this paragraph, because this paragraph is in a GroupContentControl."
       range1.Select()
   
       groupControl1 = VstoDocument.Controls.AddGroupContentControl("groupControl1")
   End Sub
   

          private Microsoft.Office.Tools.Word.GroupContentControl groupControl1;
   
          private void ProtectFirstParagraph()
          {
              Microsoft.Office.Tools.Word.Document vstoDocument =
                  Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
              vstoDocument.Paragraphs[1].Range.InsertParagraphBefore();
   
              Word.Range range1 = vstoDocument.Paragraphs[1].Range;
              range1.Text = "You cannot edit or change the formatting of text " +
                  "in this sentence, because this sentence is in a GroupContentControl.";
              range1.Select();
   
              groupControl1 = vstoDocument.Controls.AddGroupContentControl("groupControl1");
          }
   

See also

• Automate Word by using extended objects
• Content controls
• How to: Add content controls to Word documents
• Host items and host controls overview
• Programmatic limitations of host items and host controls
• Add controls to Office documents at run time