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

Code Model Objects

This section explains the workings of the code model objects and their properties. We'll defer an examination of the code model methods until the section titled "Generating Code."

FileCodeModel and CodeModel

The FileCodeModel object and the CodeModel object are the two entryways into the code model; each contains a collection of top-level code elements in addition to methods that allow you to add, delete, and modify those code elements. Table A-1 lists the FileCodeModel properties.

A FileCodeModel object always belongs to a specific source file in a project. You retrieve the FileCodeModel object by using the FileCodeModel property of the ProjectItem object that wraps the source file; once you have a FileCodeModel object, you can use its Parent property to get back to the parent ProjectItem. The most important FileCodeModel property in terms of the code model is CodeElements, which gives you access to the top-level code elements in the corresponding source file.

The Language property returns a GUID that represents the programming language of the source file. The EnvDTE.CodeModelLanguageConstants enumeration defines constants for the Visual Basic, Visual C#, and Visual C++ GUIDs. (The enumeration leaves out the Visual J# GUID: E6FDF8BF-F3D1-11D4-8576-0002A516ECE8.) If you have trouble remembering which GUID goes with which language, you can use code like the following to translate the Language GUIDs into English:

string LanguageFromGUID(string langGuid)
{
string language = String.Empty;
switch (langGuid.ToUpper())
{
case CodeModelLanguageConstants.vsCMLanguageCSharp:
language = "Visual C#";
break;
case CodeModelLanguageConstants.vsCMLanguageVB:
language = "Visual Basic";
break;
case "{E6FDF8BF-F3D1-11D4-8576-0002A516ECE8}":
language = "Visual J#";
break;
case CodeModelLanguageConstants.vsCMLanguageVC:
language = "Visual C++";
break;
default:
language = "Other";
break;
}
return language;
}

Important

You can't just open an arbitrary source file in Visual Studio .NET and access its code elements through the code model. (For example, you can't get a FileCodeModel object from a source file in the Solution Items folder.) Only if you assign the source file to a project of the same language does the code model get built for the source file.

Table A-2 lists the FileCodeModel methods. We'll cover the Addxxx methods and the Remove method in the section titled "Generating Code"; for a complete treatment of the CodeElementFromPoint method, see the section titled "Getting a CodeElement from a Point Object" in Chapter 12.

The CodeModel object returned by the Project.CodeModel property provides a more comprehensive view than does the FileCodeModel object. For one thing, the CodeModel operates at the project level instead of at the project item level, so you can expect to see a greater number of top-level source code elements in its CodeElements collection than you'd see in the typical FileCodeModel.CodeElements collection. Also, depending on the project type, the CodeModel object reveals information that isn't included by the FileCodeModel object, such as assembly-level attributes and external namespaces. The CodeModel properties are shown in Table A-3.

Most of the CodeModel properties mirror those of the FileCodeModel object but provide project-level information. This higher-level perspective comes in handy sometimes; the CodeModel.Language analogue, for example, can tell you the project's programming language even when the project has no files (and, therefore, has no FileCodeModel). The IsCaseSensitive property is unique to CodeModel; this property allows you to determine the case-sensitivity of the project's programming language, which can make all the difference when you have to generate a new code element name.

The CodeModel methods are listed in Table A-4. We'll postpone a closer examination of the Addxxx and Remove methods until the section titled "Generating Code."

The CodeTypeFromFullName method allows you to retrieve a CodeType object for a particular code element, given its fully qualified name.

The CreateCodeTypeRef method lets you create a CodeTypeRef object based on a fully qualified name or a vsCMTypeRef enumeration value. (See Table A-5.) All of the languages except Visual Basic support this method.

Finally, the IsValidID method lets you check whether a given identifier is valid for a particular language. All of the languages implement this method.

CodeElement

The CodeElement object serves as a kind of "base class" for the other code model objects by providing a set of properties common to all of the kinds of programming constructs. Table A-6 lists the CodeElement properties.

^[*] C# won't allow you to reference this property using property syntax because its get accessor takes a parameter. Use an explicit call to the get accessor instead.

The three most important CodeElement properties are Name, FullName, and Kind. The Name propertyCodeElement's only read/write propertyallows you to retrieve and change the code element's name programmatically. (Visual Basic doesn't implement the Name property's write functionality.) Note, however, that you can't always change the name of a code elementfor example, you can't change the name of a constructor because a constructor must have the same name as its parent class. The FullName property returns the code element's fully qualified name. The Kind property returns a vsCMElement value that identifies the underlying code construct. The vsCMElement enumeration has 40 constants representing the most common code constructs you'll encounter (as well as some of the more obscure ones that we hope you'll never have to deal with).

The Children property returns a CodeElements collection that contains all the code elements related to this one. Languages aren't required to support this propertyand most languages don't support it. Of the four languages that come in the Visual Studio .NET box, only Visual C++ uses the Children property.

Note

As you learn more about the code model, you'll find that Visual C++ contributes to many of its idiosyncrasies. When Visual Studio .NET invited the different language groups to join the code model party, Visual C++ showed up with a code model of its own. For the most part, Visual C++ did its job implementing the Visual Studio .NET code model (by way of its own code model, of course), but some accommodations were made in the Visual Studio .NET code model to allow more access to the Visual C++ native code model. The result is the occasional oddball property, such as CodeElement.Children, and the overrepresentation of Visual C++ in different areas of the code model, such as the constants in the vsCMElement enumeration.

The InfoLocation property returns a value from the vsCMInfoLocation enumeration that lets you know where to find the code construct. Table A-7 lists the vsCMInfoLocation constants.

When the InfoLocation value is vsCMInfoLocationProject, the StartPoint and EndPoint properties return TextPoint objects that delimit the code element in the source file.

The Extender, ExtenderCATID, and ExtenderNames properties allow you to access the extender objects related to the code element. (Extender objects let you add, hide, or replace properties of the underlying code element when you view them in the integrated development environment [IDE].)

The Language and ProjectItem properties are equivalent to the FileCodeModel.Language and FileCodeModel.Parent properties, respectively. The Collection property returns the parent CodeElements collection. The IsCodeType property returns true when the CodeElement object also supports the CodeType interface. (You'll learn all about CodeType later in this chapter.)

Table A-8 lists the CodeElement methods.

The GetStartPoint and GetEndPoint methods return a TextPoint object that marks the start or end, respectively, of some aspect of the code element definition. You specify which aspect to return by passing a vsCMPart enumeration value to the appropriate method. (See Table A-9.) The GetStartPoint and GetEndPoint methods offer more flexibility than do their StartPoint and EndPoint counterparts; in fact, CodeElement.StartPoint and CodeElement.EndPoint are equivalent to CodeElement.GetStartPoint(vsCMPartWholeWithAttributes) and CodeElement.GetEndPoint(vsCMPartWholeWithAttributes), respectively. You can see for yourself how just how flexible the GetStartPoint and GetEndPoint methods are by running the Chapter12\CodeDiscovery\TextFromStartAndEndPoints macro, which calls the two methods with each of the vsCMPart values and displays the results.

Specialized Code Model Objects

This section describes the various objects that correspond directly to specific code constructs. Each of these objects aggregates its specific members with the CodeElement members, which makes for pretty long member lists in the Help files. In the following tables, we factored out the common CodeElement members so we could concentrate on the members specific to each type. We also factored out the properties in Table A-10they're not part of the CodeElement properties, but they're common to all the types described in this section.

The DocComment property allows you to create XML document comments for languages that support them (such as C# and J#). The string you pass to DocComment must contain valid XML enclosed within <doc></doc> elements.

The Comment property creates normal, run-of-the-mill comments. (C# and J#, however, implement the write functionality of their Comment properties by turning a normal string into a <summary> XML document comment.)

CodeNamespace

The CodeNamespace object corresponds to a .NET namespace construct (package in J#, namespace in C# and C++, and Namespace in Visual Basic). CodeNamespace includes the properties listed in Table A-11.

As you can see from Table A-11, the only property specific to CodeNamespace is Members, which lets you access the namespace's top-level code elements.

Table A-12 shows the CodeNamespace methods, which are discussed in detail in the section titled "Generating Code."

CodeType

The CodeType object is a kind of generic object, like CodeElement, that corresponds roughly to what would be a type in the .NET Framework. The CodeType object allows you to treat certain code model typesCodeClass, CodeStruct, CodeDelegate, CodeInterface, and CodeEnumas if they were the same kind of object. Table A-13 lists the CodeType properties.

^[*] C# won't allow you to reference this property using property syntax because its get accessor takes a parameter. Use an explicit call to the get accessor instead.

The Access property sets or returns a vsCMAccess value that determines the code element's access (such as public, private, and so on). Be aware that the CodeType.Access write functionality doesn't work for Visual C++ and Visual Basic. Table A-14 lists the vsCMAccess enumeration constants.

The Attributes property returns a collection of CodeElement objects of type CodeAttribute, one for each attribute that applies to the CodeType. The Bases property returns a collection of CodeElement objects of type CodeClass; each CodeClass represents a base class of the CodeType.

The IsDerivedFrom property lets you discover whether the CodeType has another code element from the current project as one of its bases. Currently, the Visual C++ implementation works correctly for both class and interface bases, the C# and J# implementations work correctly for classes only, and the Visual Basic implementation doesn't work at all.

The DerivedTypes property returns a collection of CodeElement objects that specify which other code constructs in the current project derive from this object. Currently, none of the languages implements DerivedTypes.

The Members property returns a collection of CodeElement objects representing the top-level code constructs contained by the CodeType. Finally, the Namespace property returns the parent namespace.

Table A-15 shows the CodeType methods, which are explained in the section titled "Generating Code."

CodeClass and CodeStruct

The CodeClass and CodeStruct objects represent classes and structures, respectively. In the C family of programming languages, classes and structures are intimately relatedbeginning C++ programming books often introduce the class construct as a struct whose members are private by default. The code model also treats the CodeClass and CodeStruct similarly; in fact, the two objects share exactly the same properties and methods, which is why we group them together here, beginning with Table A-16.

The ImplementedInterfaces property returns a CodeElements collection that contains the interfaces implemented by the class or structure. C#, J#, and Visual Basic implement the ImplementedInterfaces property correctly; Visual C++ includes its implemented interfaces in its Bases collection, so its ImplementedInterfaces property always returns an empty collection.

The IsAbstract property returns whether the object is an abstract class or structure. All of the languages implement the read functionality of IsAbstract; only C# and J# implement the write functionality.

Table A-17 lists the CodeClass and CodeStruct methods, which are explained in the section titled "Generating Code."

CodeInterface

The CodeInterface object encapsulates an interface code construct. Table A-18 shows the CodeInterface properties; as you can see from the table, CodeInterface doesn't define any interface-specific properties.

The CodeInterface methods are shown in Table A-19. You can find an explanation of the Addxxx methods in the section titled "Generating Code."

CodeEnum

The CodeEnum object represents an enumeration code construct. CodeEnum doesn't define any enumeration-specific properties, as you can see from Table A-20.

The CodeEnum methods, shown in Table A-21, have explanations in the "Generating Code" section.

CodeDelegate

The CodeDelegate object represents a delegate code construct. Table A-22 lists the CodeDelegate properties.

^[*] C# won't allow you to reference this property using property syntax because its get accessor takes a parameter. Use an explicit call to the get accessor instead.

The BaseClass property always returns a CodeClass object that represents System.Delegate. Every language except Visual C++ implements the BaseClass property.

The Parameters property returns a collection of CodeElement objects that contains an item for each parameter of the delegate; Visual C++ doesn't implement this property.

The Prototype property returns the delegate's prototype as a string. The Prototype property accepts values from the vsCMPrototype enumeration that determine which aspects of the prototype to return. The vsCMPrototype constants listed in Table A-23 are bit flags, so you can combine them to customize the string returned by Prototype. For example, the combination of vsCMPrototypeFullname, vsCMPrototypeType, vsCMPrototypeParamNames, and vsCMPrototypeParamTypes would return all information about a particular delegate. All of the languages except Visual C++ implement this property.

Finally, the Type property lets you read or write a CodeTypeRef value that represents the delegate's type. Currently, none of the Type property's write implementations works, and read works only for C#, J#, and Visual Basic.

The CodeDelegate methods are shown in Table A-24; you can find explanations for them in the section titled "Generating Code."

CodeVariable

A CodeVariable object represents a variable declaration. Table A-25 lists the CodeVariable properties.

^[*] C# won't allow you to reference this property using property syntax because its get accessor takes a parameter. Use an explicit call to the get accessor instead.

The Access property is similar to the CodeType.Access property and takes the same vsCMAccess values found in Table A-14. All languages implement the Access property's read functionality; only C# and J# implement the write functionality.

The Attributes property returns a CodeElements collection that contains an item of type CodeAttribute for each attribute of the variable.

The InitExpression property lets you read or write the variable's initialization expression. All languages support the InitExpression read functionality, and all languages but Visual Basic support the InitExpression write functionality. The expression you pass to the InitExpression property shouldn't contain an initialization operator because the correct operator is supplied by the language. Also, be aware that InitExpression won't validate the expression you specify.

The IsConstant property lets you read or write whether the variable is declared as a constant. All languages implement the IsConstant read functionality, but the J# implementation always returns False. Every language except Visual Basic implements the IsConstant write functionality.

The IsShared property lets you read or write whether a variable is a class shared variable (True) or a class instance variable (False). The read functionality of IsShared works for all languages and the write functionality works for C# and J#.

The Prototype property returns a string that represents the variable's declaration. This property works the same way as the CodeDelegate.Prototype propertyyou pass it a combination of values from the vsCMPrototype enumeration (listed in Table A-23), and it returns those parts of the declaration that you request. Unlike the InitExpression property, the Prototype property returns the initialization operator along with the initialization expression when passed a value of vsCMPrototypeInitExpression. All languages implement this property.

The Type property sets or returns a CodeTypeRef object that represents the variable's type. All languages implement the Type property's read functionality, but only Visual C++ implements the write functionality.

Table A-26 lists the CodeVariable methods. You can find an explanation of these methods in the section titled "Generating Code."

CodeProperty

The CodeProperty object represents a property code construct. Table A-27 lists the CodeProperty properties. Note that the J# implementation doesn't recognize property declarationsinstead, J# interprets the property's get_xxx and set_xxx methods as CodeFunction objects. Consequently, the explanations that follow Table A-27 won't include mention of J#.

The Access property allows you to read or write the access modifiers of the property. (See Table A-14.) All of the languages implement the read functionality, but only C# implements the write functionalityVisual Basic returns "not implemented" and Visual C++ only allows properties to have public access, so it always returns "read-only".

The Attributes property returns a CodeElements collection containing an item of type CodeAttribute for each attribute that applies to the property.

The Getter and Setter properties let you read or write the property getter and setter, respectively. Getter and Setter each take or return a CodeFunction object that represents the corresponding getter or setter of the property code construct. C# and Visual Basic implement the read functionality of these properties. None of the languages implements the write functionality, but you can achieve the same effect in some of the languages by retrieving the CodeFunction object for the getter or the setter and making changes through the CodeFunction methods.

The Prototype property returns the property's prototype as a string. This property takes a combination of values from the vsCMPrototype enumeration (listed in Table A-23) and returns the requested information about the prototype. Note that CodeProperty.Prototype returns information about the property declaration only and doesn't include prototype information about the property's getter and setter functions. All the languages implement the Prototype property.

The Type property allows you to read or write a CodeTypeRef value that represents the property's type. All of the languages implement the Type property's read functionality, and none of the languages implements the write functionality. However, although you can't change a Visual C++ property's type directly, you can change it indirectly by changing the types of the underlying getter and setter functions.

Table A-28 lists the CodeProperty methods, which are explained in the section titled "Generating Code."

CodeAttribute

The CodeAttribute object corresponds to an attribute as defined by the .NET Framework. Table A-29 shows the CodeAttribute properties.

The Value property lets you read or write the attribute's value. All the languages implement the read functionality, but J# returns the wrong information if the attribute has more than one parameter. Only Visual C++ implements the write functionality.

Table A-30 shows the CodeAttribute methods, which are explained in the section titled "Generating Code."

CodeFunction

The CodeFunction object represents a function or sub procedure code construct. Table A-31 lists the CodeFunction properties.

^[*] C# won't allow you to reference this property using property syntax because its get accessor takes a parameter. Use an explicit call to the get accessor instead.

The Access property lets you read or write the function's access modifiers. (See Table A-14.) All languages implement the read functionality, and all languages but Visual Basic implement the write functionality.

The Attributes property returns a CodeElements collection containing an item of type CodeAttribute for each attribute that applies to the function.

The CanOverride property lets you read or write whether the function is overridable. All the languages implement the read functionality, but Visual C++ always returns True. C# and J# implement the write functionality; however, J# will only let you change from a nonoverridable (final) function to an overridable function.

The FunctionKind property returns one of the vsCMFunction values from Table A-32. Every language implements this property.

The IsOverloaded property returns whether the function is overloaded. When IsOverloaded returns True, the Overloads property returns a collection that contains the function's overloads. Note that the C# and J# Overloads properties hold overloads only, whereas the Visual C++ and Visual Basic Overloads properties include the function in addition to its overloads.

The IsShared property lets you read or write whether a member function is a class shared function (True) or a class instance function (False). The read functionality of IsShared works for all languages, and the write functionality works for Visual C++, C#, and J#.

The MustImplement property lets you read or write whether the function is abstract. All languages support the read functionality. Visual C++ implements the write functionality fully, but C# and J# only allow you to convert an abstract function into a real function.

The Parameters property returns a collection that contains an item for each parameter of the function. All of the languages support this property.

The Prototype property returns a string that represents the function's prototype. This property accepts a combination of values from the vsCMPrototype enumeration in Table A-23 and returns the requested parts of the function's declaration. All of the languages implement this property.

The Type property allows you to read and write a CodeTypeRef value that represents the function's return type. All of the languages implement the read functionality, but only Visual C++ implements the write functionality.

Table A-33 lists the CodeFunction methods, which are explained in the section titled "Generating Code."

CodeParameter

The CodeParameter object represents a parameter of a function, sub procedure, or delegate. Table A-34 lists the CodeParameter properties.

The Attributes property returns a CodeElements collection containing an item for each attribute that applies to the parameter. C#, J#, and Visual Basic implement this property.

The Type property allows you to read or write a CodeTypeRef value that represents the parameter's type. All of the languages implement the read functionality, but only Visual C++ implements the write functionality.

Table A-35 lists the CodeParameter methods, which are explained in the section titled "Generating Code."

CodeTypeRef

The CodeTypeRef object represents the type of a function, delegate, property, variable, or parameter. Table A-36 lists the CodeTypeRef properties.

The AsFullName property returns the type's fully qualified name. All of the languages support this property, but the Visual C++ implementation returns the same value as the AsString property.

The AsString property returns the language's keyword that corresponds to the type. (For example, in C#, AsString returns int for System.Int32.) All of the languages support this property, but the Visual Basic implementation returns the same value as the type name part of the AsFullName property.

The CodeType property returns a CodeType object that represents the type. C#, J#, and Visual Basic support this property, although Visual Basic always returns a vsCMElementOther CodeType.

When the CodeTypeRef represents an array, the ElementType property sets or returns the type of the array's elements, and the Rank property sets or returns the number of dimensions of the array. Currently, none of the languages implements either of these properties.

When the CodeTypeRef represents a CodeElement in a source file, the Parent property returns that CodeElement. All of the languages implement this property.

The TypeKind property returns a vsCMTypeRef value from Table A-5 that signifies the type of the CodeTypeRef. All of the languages implement this property.