|
|
| Author: |
Carlos J. Quintero (Microsoft MVP) |
Applies to: |
Microsoft Visual Studio .NET 2002 |
| Date: |
May 2009 |
|
Microsoft Visual Studio .NET 2003 |
| |
|
|
Microsoft Visual Studio 2005 |
| |
|
|
Microsoft Visual Studio 2008 |
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
You can code, design, locate code and document your apps much faster using VB.NET, C#, C++ or Visual J#:  
|
