Logo
HOWTO: Understanding Visual Studio behavior when an add-in tries to edit a read-only file

Author: Carlos J. Quintero (Microsoft MVP) Applies to: Microsoft Visual Studio .NET 2002
Date: May 2009   Microsoft Visual Studio .NET 2003
Updated: March 2013   Microsoft Visual Studio 2005
      Microsoft Visual Studio 2008
      Microsoft Visual Studio 2010
      Microsoft Visual Studio 2012
Introduction

A Visual Studio add-in can perform editing actions programmatically on files of a project, using several methods of the EnvDTE.EditPoint or EnvDTE.TextSelection classes such as Insert, Delete, ReplacePattern, etc. After performing such editing actions, the add-in may want to save the file to persist the changes.

However, such editing actions can fail if the file is read-only. This article explains several circumstances that can cause a file to be read-only and the several behaviors that Visual Studio can exhibit when dealing with read-only files. Add-in writers should take into account these circumstances and behaviors when writing add-ins, and test them accordingly to fail gracefully if the editing action can't be completed.

More Information

A file of a project can be read-only in two circumstances:

  • The file is under source code control (such as Microsoft SourceSafe or Team Foundation Server). Typically source code control systems use the read-only attribute of a file to indicate to the developer that the file is not checked-out and to prevent unnoticed editing. When the file is checked-out for editing, the source code control system clears the read-only attribute of the file.
  • The file has the read-only attribute even if it is not under source code control. A possible scenario for this case is when the project uses linked files from a shared network folder which acts as a library of code for several projects. The owner of that library can mark the files with the read-only attribute to indicate to the developer that she shouldn't modify such files.

When you try to edit a file that is read-only, Visual Studio can behave in several ways, depending on how it is configured:

  • If the file is read-only because it is under source code control (it is checked-in, not checked-out), the behavior can be configured through the "Tools", "Options" menu, "Source Control", "Environment" section, "Checked-in item behavior" setting and "Allow checked-in files to be edited" checkbox.
    • If the behavior is "Check out automatically", Visual Studio will try to check out the file without showing a prompt dialog:
      • If the source code control is connected, Visual Studio will check out the file successfully with no prompt and the editing action will succeed.
      • If the source code control is disconnected, Visual Studio will prompt the user for a disconnected checkout:
        • If the user clicks the "Check out (disconnected)" button, the editing action will succeed.
        • If the user clicks the "Cancel" button:
          • If the "Allow checked-in files to be edited" checkbox is not marked, the editing action will fail.
          • If the "Allow checked-in files to be edited" checkbox is marked, the editing action will succeed even if the file is still read-only. However, the file is being edited in memory. When trying to save such file, the user or the add-in will have to deal with that circumstance, either checking out the file or saving it to another location.
    • If the behavior is "Prompt for check out" or "Prompt for exclusive checkouts", Visual Studio will prompt the user for a checkout with a "Check-out for Edit" dialog that can have two buttons ("Check Out" and "Cancel") or three (an additional "Edit" button" if the "Allow checked-in files to be edited" checkbox is marked):
      • If the user clicks the "Check Out" button:
        • If the source code control is connected, Visual Studio will check out the file successfully with no further prompt and the editing action will succeed.
        • If the source code control is disconnected, Visual Studio will prompt again the user, for a disconnected checkout this time:
          • If the user clicks the "Check out (disconnected)" button, the editing action will succeed.
          • If the user clicks the "Cancel" button:
            • If the "Allow checked-in files to be edited" checkbox is not marked, the editing action will fail.
            • If the "Allow checked-in files to be edited" checkbox is marked, the editing action will succeed even if the file is still read-only. However, the file is being edited in memory. When trying to save such file, the user or the add-in will have to deal with that circumstance, either checking out the file or saving it to another location.
      • If the user clicks the "Edit" button, the editing action will succeed. However, the file is being edited in memory. When trying to save such file, the user or the add-in will have to deal with that circumstance, either checking out the file or saving it to another location.
      • If the user clicks the "Cancel" button:
        • If the "Allow checked-in files to be edited" checkbox is not marked, the editing action will fail.
        • If the "Allow checked-in files to be edited" checkbox is marked, the editing action will succeed even if the file is still read-only. However, the file is being edited in memory. When trying to save such file, the user or the add-in will have to deal with that circumstance, either checking out the file or saving it to another location.
    • If the behavior is "Do nothing":
      • If the "Allow checked-in files to be edited" checkbox is not marked, the editing action will fail.
      • If the "Allow checked-in files to be edited" checkbox is marked, the editing action will succeed even if the file is still read-only. However, the file is being edited in memory. When trying to save such file, the user or the add-in will have to deal with that circumstance, either checking out the file or saving it to another location.
  • If the file is read-only but not under source code control, the behavior can be configured through the "Tools", "Options" menu, "Environment", "Documents" section, "Allow editing of read-only files; warn when attempt to save" setting.
    • If the "Allow editing of read-only files; warn when attempt to save" checkbox is marked, the editing action will succeed even if the file is still read-only. However, the file is being edited in memory. When trying to save such file, the user or the add-in will have to deal with that circumstance, either checking out the file or saving it to another location.
    • If the "Allow editing of read-only files; warn when attempt to save" checkbox is not marked, Visual Studio will prompt the user with a "Edit of read-only file" dialog that has three buttons ("Edit In-Memory", "Make Writeable" and "Cancel"):
      • If the user clicks the "Edit In-Memory" button, the editing action will succeed even if the file is still read-only. However, the file is being edited in memory. When trying to save such file, the user or the add-in will have to deal with that circumstance, either checking out the file or saving it to another location.
      • If the user clicks the "Make Writeable" button, the editing action will succeed and the file will not be read-only any more.
      • If the user clicks the "Cancel" button, the editing action will fail.

In short, the editing action of a read-only file can end with three results:

  • The file is edited and when attempting to save it there will be no problem because the file became writeable.
  • The file is edited but when attempting to save it there will be a problem because the file remained read-only.
  • The file was not edited because the user cancelled the action in some prompt dialog.

After an editing action attempt, an add-in can call System.IO.File.GetAttributes with the full name of the file being edited and check if the System.IO.FileAttributes.ReadOnly flag is set.

An add-in can detect the second case because no exception is thrown but the file is still read-only.

An add-in can detect the third case because a COM exception is thrown, for example:

"System.Runtime.InteropServices.COMException (0x80041004): This file is under source code control. It must be checked out before it can be modified."

Ideally the add-in should not show any error if the user cancels an action. But since a COM Exception can happen also in other circumstances when editing a file (if a true error happens, for example), the add-in should ignore the exception only if the file being edited remains read-only when the exception is thrown.



Go to the 'Visual Studio Extensibility (VSX)' web site for more articles like this (Articles section)


Top