| 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 back to the 'Resources for Visual Studio .NET extensibility' section for more articles like this
|
