Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

Navigating the Help System

The Help system in Visual Studio .NET is one of the best features of the IDE. It's context-sensitive, well indexed, and completely searchable. It covers the entire MSDN Library, which includes some 1.5 GB of data. In fact, the Help system is so big that it's worth discussing how you can customize it to get just the data you're looking for.

As part of the multistep Visual Studio .NET installation process, you have the opportunity to install the MSDN documentation that ships with the product. Installing this documentation is a separate step because it allows developers to install the latest MSDN Library from Microsoft. (If you're an MSDN subscriber, be sure to check for the latest MSDN Library if you're installing Visual Studio .NET 2003 soon after its release.)

If you have multiple Help collections installed, you can choose the one you want in the Options dialog box. The default Help collection for Visual Studio .NET 2003 is called the Visual Studio .NET 2003 Combined Help Collection. This is the recommended Help collection because it includes extra documentation to help you with certain add-in features and miscellaneous other features in the product.

You can see the Help page in the Environment folder in the Options dialog box in Figure 14-1. Notice that you can set a preferred language along with the collection you want as the default. You must have the specific language documentation installed on your machine to get an alternative choice for this setting.

A final setting you can specify is whether to display help internally or externally. If you choose to display it internally, you'll see the help information inside the IDE. If you choose the external option, help will be displayed in a window outside the IDE. The external option makes a lot of sense if you're working in a multimonitor environment. Using an external window, you can keep the help open in one screen and your IDE open in another.

Help Windows

Whether you use help that's integrated into the IDE or you use the standalone viewer, you need to be familiar with three organizational windows. The Contents window contains a hierarchical display of the available help topics. The Index window contains a list of the index terms found in the Help collection. And the Search window lets you perform a search of the entire help system for a particular term or phrase. The results of searches are displayed in the Search Results window. Searches have a limit of 500 returns, so it pays to narrow your searches whenever possible. Figure 14-2 shows the Microsoft Document Explorer window, which contains all these same features. You can open this window by clicking the Microsoft Visual Studio .NET 2003 Documentation link in the Microsoft Visual Studio .NET 2003 folder on the Start menu.

The Document Explorer features don't require a lot of explanation. They're pretty straightforward and they've been part of Visual Studio and MSDN for years. As we mentioned, though, the documentation collection is quite large and you can use some techniques and settings to make your searches and index lookups more efficient.

Search and Index Options

What you select as the Filtered By option in the Search window (as shown in Figure 14-3) has a major effect on what information is presented when you enter a string in the Look For box. For example, typing CString while the Visual Studio Macros filter is activated returns the DataSet Class item from the .NET Framework Class Library as the first hit in the Search Results window. If Visual C++ is the active filter, the first hit returned is the CString Operation Relating To C-Style Strings topic from Visual C++ Concepts. With no filter at all, these two items appear in the list together, with no real contextual information. Both results are valid, but the filter helps you pinpoint the specific topic you're searching for.

The Search In Titles Only option limits returns to terms found only in the document titles. You can put this option to good use if you're looking for top-level documentation on a particular subject. Match Related Words causes your search terms to be matched to variations of those terms. For example, searching for link with the Match Related Words option selected might return linked, linking, and linker. The Search In Previous Results option causes your search to be confined to the results of the last search. This lets you drill down in your list of current results.

When you select the Highlight Search Hits (In Topics) option, the terms you're searching for are highlighted in the document window when you view a topic in the search results. This is a fantastic option that helps you easily find the term you're looking for. The highlighting can get annoying when you want to just read the document you're looking at, however, so to clear the document of highlighted search items, deselect this option and refresh the window by clicking the Refresh button on the Web toolbar. Alternatively, you can just double-click the item again in the Search Results window.

Narrowing Search Results

The Search window lets you enter words, phrases, and logical operators to help find the information you're seeking. You can also use certain wildcard characters to refine your search.

Let's take a minute to go through some of the general rules regarding help searches. We'll assume that you generally know what you're looking for but that you don't want to sift through hundreds of hits to get the information you need. To search for a string consisting of multiple terms, you should enclose your search phrases in quotes. Doing so will return an exact match for the phrase you're searching for. For example, searching for CString returns 500 matches (the maximum number returned from any search). Searching for "CString object" returns just over 170 hits. Knowing just what you're looking for and making your searches more specific has obvious advantages.

You can use logical operators to include or exclude certain types of results. For example, you're probably aware that placing an OR between your search terms returns all pages that include either term in the search. Table 14-1 lists the logical operators you can use to narrow searches in Visual Studio .NET.

One of the more interesting logical operators is the THRU operator. Using this operator, you can search for a range of numbered terms. You might use this operator to search for a range of constants or a set of error values. Note that numeric searches using the THRU operator tend to take a long time, especially if you combine that search with a second operator.

You can broaden or narrow your searches by employing wildcardsfor example, to search for terms that might have different spellings or extensions. Table 14-2 lists the two available wildcard characters.

Creating Custom Help Filters

If you find yourself searching for related terms from different help topics, you might want to create a custom help filter. For example, if you plan to work with both COM and .NET in a solution you're creating, you might find it easier to create a custom filter that returns hits from these two topics rather than creating a more specific help string under a broader search filter.

To create a custom help filter, open the Edit Help Filters window by typing Help.EditFilters in the Command Window or by choosing the Edit Filters command from the Help menu. You can see the Edit Help Filters window in Figure 14-4.

In the Filter Definition box, you can enter a set of attributes that narrows the list of items returned in an index or a search. You can enter search attributes that specify the language, product, target operating system, or even the technology you want to search. The possible attributes are listed in the List Of Available Attributes And Their Values box at the bottom of the Edit Help Filters window. Attributes are grouped using parentheses, and you can use logical operators to specify the type of inclusion in the string.

To create a simple COM/.NET subset, we can string together two DocSet attributes with two Technology attributes:

("DocSet"="NETFramework" OR "DocSet" = "NETFrameworkExtender") or
("Technology"="COMt" OR "Technology"="COMt" )

You have a large number of attributes to choose from when you create attributes. For the most part, you'll probably want to string together document sets, languages, and technologies, but other attributes are available. You can click on individual attributes in the List Of Available Attributes window and they'll be added to the currently open set automatically.

As you create the list of attributes you want to use, click the Calculate button to see how many topics will show up in your new list. You can use this number to determine whether your attributes are too broad or exclusive to be useful.

Searching from the Command Window

A feature that will be popular with programmers who are used to the Vim editor is the ability to search for a help topic from the Command Window. The Help.F1Help command is aliased to help by default in the Command Window. The F1Help command takes one argumenta string representing the F1 keyword you want to search for. If the term you're searching for is an F1 keyword, you get the specific help topic for that keyword when you type >help
term
in the Command Window, where term is the word you're searching for. If the term you're searching for is not an F1 keyword, the term is placed in the Index window and the index results are displayed.

If you're looking for help on a named command in Visual Studio .NET, the F1 keyword for that command is usually the command itself, so if you know the command name, you can easily get to the help topic. For example, to get help on the Find command, you type >help Edit.Find in the Command Window. You can try this with any of the named commands you've worked with in this book, and you should immediately get the topic you're searching for. The terms you might search for include:

Edit.ReplaceInFiles

Help.Index

File.NewFile

Debug.Start

If you start to get used to this function and you're curious about how to determine the F1 keywords for particular help topics, you can turn on debugging in the Dynamic Help window by adding an entry to the registry. The key is:

HKCU\Software\Microsoft\VisualStudio\7.1\Dynamic Help

To turn on debugging, you must add the string key "Display Debug Output in Retail" if it doesn't exist and set its value to "Yes". Figure 14-5 shows the Dynamic Help window after debugging has been enabled. Keep in mind that only topics assigned to F1 help work this way. Other search terms open the Index window.